Skip to content

Codec

Type-safe serialization abstraction for Java.

Java 25+ · Spring Boot 4.x (starter only)

Get started View on GitHub

Two small interfaces — Codec<T> and CodecFactory — sit between your code and whichever serialization library you pick. Choose the backend by adding a module; nothing in your code changes.

For library authors who need to serialize values without choosing a serializer for their users, and for the applications that consume those libraries. It is not a serializer itself and not a replacement for Apache Commons Codec — it is the seam that lets Jackson, Gson, Protobuf, or Fory sit behind one interface.

Codec<Person> codec = codecFactory.create(Person.class);

byte[] bytes = codec.encode(person);
Person decoded = codec.decode(bytes);

Why

Building-block libraries often need to serialize values — cache entries, queue payloads, journal records — without dictating how. Hard-coding Jackson (or anything else) forces that choice onto every consumer. Codec keeps the contract tiny and pushes the backend decision to the classpath.

What you get

  • A clean SPI

    Codec<T> encodes and decodes. CodecFactory produces a codec for any type. That is the whole contract. Every failure is a CodecException in one of four families keyed to what you do next.

  • Generics that round-trip

    TypeRef<T> captures parameterized types, so List<Person> comes back as List<Person> — no erasure surprises.

  • Pluggable backends

    Jackson 3.x, Jackson 2.x, Gson, JSON-B, Protocol Buffers, and Apache Fory, each in its own Spring-free module — plus CBOR, Smile, YAML, and XML by mapper swap.

  • Composition

    Layer compression, encryption, or a text-safe encoding onto any codec with andThen. Gzip, deflate, zstd, and LZ4 ship with decompression-bomb protection.

  • Envelope encryption

    AES-256-GCM with pluggable key management — in-process keys or your KMS — and a published threat model.

  • Spring Boot auto-configuration

    Add the starter and a backend; get a CodecFactory bean. A BOM keeps versions aligned.

Modules

Module What it is
codec-core The SPI: Codec, CodecFactory, TypeRef — nothing else
codec-transforms Codec<byte[]> transforms with no dependencies beyond codec-core: gzip, deflate, Base64, Base32, hex, checksum, text
codec-versioned Format versioning: a version header that lets the storage strategy change
codec-jackson Jackson 3.x (tools.jackson) JSON backend
codec-jackson2 Jackson 2.x (com.fasterxml.jackson) JSON backend
codec-gson Gson JSON backend
codec-jsonb Jakarta JSON Binding (JSON-B) backend
codec-protobuf Protocol Buffers backend
codec-fory Apache Fory binary backend — fast JVM-only serialization with mandatory class registration
codec-crypto AES-256-GCM envelope encryption with pluggable key management
codec-zstd Zstandard compression transform
codec-lz4 LZ4 compression transform
codec-spring-data-redis RedisSerializer adapter for Spring Data Redis
codec-kafka Serializer, Deserializer, and Serde adapters for Kafka
codec-autoconfigure Spring Boot auto-configuration for all backends
codec-spring-boot-starter Starter bundling core + auto-configuration
codec-bom Bill of materials for version alignment

Where next