Type-safe serialization abstraction for Java. Codec provides a simple, generic Codec<T>
interface that your libraries depend on, letting applications choose their serialization
framework (Jackson, Gson, Protocol Buffers, etc.) without coupling library code to a
specific implementation.
📖 Documentation: jwcarman.github.io/codec · API reference: jwcarman.github.io/codec/api
- Java 25+
- Spring Boot 4.x (only if you use the starter — the backends themselves are Spring-free)
Note
The dependency snippets below name the latest release. This repository's
main branch tracks ahead of it — anything the
Changelog lists
under Unreleased is not in that release yet.
Use the BOM for version alignment:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.jwcarman.codec</groupId>
<artifactId>codec-bom</artifactId>
<version>0.10.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
For Spring Boot applications, add the starter (it brings the auto-configuration), then the backend you want:
<dependency>
<groupId>org.jwcarman.codec</groupId>
<artifactId>codec-spring-boot-starter</artifactId>
</dependency>
Outside Spring, skip the starter and just add a backend — construct its factory
directly (e.g. new JacksonCodecFactory(objectMapper)). Backend choices:
<!-- Jackson 3 (JSON) -->
<dependency>
<groupId>org.jwcarman.codec</groupId>
<artifactId>codec-jackson</artifactId>
</dependency>
<!-- Jackson 2 (JSON, for projects on Jackson 2, com.fasterxml.jackson) -->
<dependency>
<groupId>org.jwcarman.codec</groupId>
<artifactId>codec-jackson2</artifactId>
</dependency>
<!-- Gson (JSON) -->
<dependency>
<groupId>org.jwcarman.codec</groupId>
<artifactId>codec-gson</artifactId>
</dependency>
<!-- JSON-B (Jakarta JSON Binding; bring a provider, e.g. Yasson) -->
<dependency>
<groupId>org.jwcarman.codec</groupId>
<artifactId>codec-jsonb</artifactId>
</dependency>
<!-- Protocol Buffers -->
<dependency>
<groupId>org.jwcarman.codec</groupId>
<artifactId>codec-protobuf</artifactId>
</dependency>
<!-- Apache Fory (JVM-only binary; classes must be registered, so build the
factory with ForyCodecFactory.of(Person.class, ...) or your own Fory) -->
<dependency>
<groupId>org.jwcarman.codec</groupId>
<artifactId>codec-fory</artifactId>
</dependency>
Inject a CodecFactory and create codecs for your types:
import org.jwcarman.codec.Codec;
import org.jwcarman.codec.CodecFactory;
@Service
public class MyService {
private final Codec<Person> personCodec;
public MyService(CodecFactory codecFactory) {
this.personCodec = codecFactory.create(Person.class);
}
public byte[] serialize(Person person) {
return personCodec.encode(person);
}
public Person deserialize(byte[] bytes) {
return personCodec.decode(bytes);
}
}
For generic types, use TypeRef:
Codec<List<Person>> codec = codecFactory.create(new TypeRef<List<Person>>() {});
Layer any Codec<byte[]> transform (compression, encryption, a custom one)
onto a codec with andThen. Encoding applies transforms left to right;
decoding inverts them automatically. See
Codec Composition for
the built-in compression transforms, decompression-bomb protection, and how to
write your own:
Codec<Person> codec = codecFactory.create(Person.class).andThen(new GzipCodec());
To change your storage strategy later without rewriting stored data, wrap the
codec in a versioned one (codec-versioned). It writes a 3-byte header naming
the version that produced each payload and dispatches on it when reading, so old
data stays readable while new data is written by the new strategy:
Codec<Person> codec = VersionedCodec.<Person>builder()
.version(1, jacksonFactory.create(Person.class))
.version(2, foryFactory.create(Person.class).andThen(new ZstdCodec()))
.writing(2) // deploy readers first, then flip this
.build();
| Module | What it is | Artifact |
|---|---|---|
| Core | Core interfaces (Codec, CodecFactory, TypeRef) |
codec-core |
| Transforms | Byte transforms with no dependencies beyond codec-core: gzip, deflate, Base64, Base32, hex, checksum, text |
codec-transforms |
| Versioned | Format versioning: a version header that lets the storage strategy change | codec-versioned |
| Jackson | Jackson 3.x JSON (tools.jackson) |
codec-jackson |
| Jackson 2 | Jackson 2.x JSON (com.fasterxml.jackson) |
codec-jackson2 |
| Gson | Gson JSON | codec-gson |
| JSON-B | Jakarta JSON Binding | codec-jsonb |
| Protobuf | Protocol Buffers | codec-protobuf |
| Fory | Apache Fory binary (JVM-only, registration required) | codec-fory |
| Crypto | AES-256-GCM envelope encryption transform | codec-crypto |
| Zstandard | Zstandard compression transform | codec-zstd |
| LZ4 | LZ4 frame compression transform | codec-lz4 |
| Spring Data Redis | RedisSerializer adapter, cache auto-configuration |
codec-spring-data-redis |
| Kafka | Serializer, Deserializer, and Serde adapters |
codec-kafka |
| Auto-configure | Spring Boot auto-configuration for all backends | codec-autoconfigure |
| Starter | Spring Boot starter (core + auto-configure) | codec-spring-boot-starter |
Speed and ratio claims are backed by benchmarks.
The core module provides three types:
public interface Codec<T> {
byte[] encode(T value);
T decode(byte[] bytes);
}
Every encode/decode failure is a CodecException in one of four families —
fix the value, quarantine the payload, hold it for a newer reader, or retry —
keyed to what the caller does next. See
Handling Failures.
public interface CodecFactory {
<T> Codec<T> create(TypeRef<T> typeRef);
default <T> Codec<T> create(Class<T> type) {
return create(TypeRef.of(type));
}
}
A super type token that captures generic type information at runtime:
// Simple types
TypeRef<String> ref = TypeRef.of(String.class);
// Generic types
TypeRef<List<String>> ref = new TypeRef<>() {};
// Nested generics
TypeRef<Map<String, List<Integer>>> ref = new TypeRef<>() {};
TypeRef implements equals() and hashCode() based on the captured Type,
making it safe to use as a map key for caching codecs.
The codec-spring-boot-starter (via codec-autoconfigure) registers a
CodecFactory bean for whichever backend is on the classpath. The backend
modules themselves are Spring-free. See
Spring Boot for
backend precedence, bean reuse, and what the starter does not include.
# Compile and run tests
./mvnw clean verify
# Apply code formatting
./mvnw spotless:apply
# Apply license headers
./mvnw -Plicense license:format
See CONTRIBUTING.md for guidelines.