Interface Codec<T>

Type Parameters:
T - The Java type that this codec is responsible for handling.
All Known Implementing Classes:
Codec.EitherCodec, Codec.OneOfCodec
public interface Codec<T>
A bidirectional serializer and deserializer capable of translating between Java objects and various serialized formats defined by a DynamicOps provider.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static class 
    Codec.CodecException
    An unchecked exception utilized for failures occurring during the serialization or deserialization process.
    static final record 
    Codec.EitherCodec<A,B>
    Internal implementation for handling the Either type, allowing for bifurcated data structures.
    static final record 
    Codec.Field<P,T>
    Represents the definition of a single field within a structured object.
    static final record 
    Codec.OneOfCodec<T>
    Internal implementation that iterates through a list of codecs until one successfully processes the data.

  • Method Summary

    Modifier and Type
    Method
    Description
    default <C extends Collection<T>>
    Codec<C>
    collection(Supplier<C> factory)
    Creates a codec for a specific collection implementation.
    <D> T
    decode(DynamicOps<D> ops, D input)
    Decodes a serialized input of a specific data format into a Java object.
    static <A,B> Codec<Either<A,B>>
    either(Codec<A> left, Codec<B> right)
    Creates a codec for an Either container.
    <D> D
    encode(DynamicOps<D> ops, T value)
    Encodes a Java object into its serialized representation.
    static <E extends Enum<E>>
    Codec<E>
    enumCodec(Class<E> enumClass)
    Creates a codec for an Enum type using its string name.
    static <T> Codec<T>
    fallback(Codec<? extends T> left, Codec<? extends T> right)
    Combines two codecs such that the secondary is used if the primary fails.
    default <P> Codec.Field<P,T>
    fieldOf(String name, Function<P,T> getter)
    Defines this codec as a field within a larger object structure.
    default Codec<List<T>>
    list()
    Creates a codec for a List of elements of type T.
    static <K,V> Codec<Map<K,V>>
    map(Codec<K> keyCodec, Codec<V> valueCodec)
    Creates a codec for a Map structure.
    default Codec<T>
    nullable()
    Modifies the codec to treat null Java values as empty serialized states.
    static <T> Codec<T>
    of(Function<Object,T> decoder, Function<T,Object> encoder)
    Factory method to create a simple codec from mapping functions.
    static <T> Codec<T>
    oneOf(Codec<? extends T>... codecs)
    Combines multiple codecs to be tried in sequence.
    default Codec<Optional<T>>
    optional()
    Wraps the current codec to handle Java Optional values.
    default Codec<T>
    orElse(T defaultValue)
    Wraps this codec with a default value to be used if decoding fails or returns null.
    default <U> Codec<U>
    unchecked()
    Performs an unsafe cast of this codec to another type.
    default <R> Codec<R>
    xmap(Function<? super T, ? extends R> forward, Function<? super R, ? extends T> backward)
    Transforms this codec to handle a new type R via two-way conversion functions.

  • Method Details

    • decode

      <D> T decode(DynamicOps<D> ops, D input)
      Decodes a serialized input of a specific data format into a Java object.
      Type Parameters:
      D - The type of the serialized data (e.g., JsonElement, NBTCompound, ByteBuf).
      Parameters:
      ops - The provider defining how to navigate and read data of type D.
      input - The raw serialized input to be processed.
      Returns:
      The resulting Java object of type T.
      Throws:
      Codec.CodecException - If the input data is malformed, missing fields, or type-mismatched.

    • encode

      <D> D encode(DynamicOps<D> ops, T value)
      Encodes a Java object into its serialized representation.
      Type Parameters:
      D - The target type of the serialized data.
      Parameters:
      ops - The provider defining how to construct data of type D.
      value - The Java object instance to be serialized.
      Returns:
      The serialized data representing the object.
      Throws:
      Codec.CodecException - If the object contains non-serializable states or illegal values.

    • of

      static <T> Codec<T> of(Function<Object,T> decoder, Function<T,Object> encoder)
      Factory method to create a simple codec from mapping functions.
      Type Parameters:
      T - The target Java type.
      Parameters:
      decoder - Function to convert raw objects (from DynamicOps) to type T.
      encoder - Function to convert type T to raw objects.
      Returns:
      A basic Codec implementation.

    • map

      static <K,V> Codec<Map<K,V>> map(Codec<K> keyCodec, Codec<V> valueCodec)
      Creates a codec for a Map structure.
      Type Parameters:
      K - Key type.
      V - Value type.
      Parameters:
      keyCodec - Codec for keys.
      valueCodec - Codec for values.
      Returns:
      A codec handling Map types.

    • enumCodec

      static <E extends Enum<E>> Codec<E> enumCodec(Class<E> enumClass)
      Creates a codec for an Enum type using its string name.
      Type Parameters:
      E - Enum type.
      Parameters:
      enumClass - The class literal of the enum.
      Returns:
      A codec for the specified enum.

    • fallback

      static <T> Codec<T> fallback(Codec<? extends T> left, Codec<? extends T> right)
      Combines two codecs such that the secondary is used if the primary fails. Internally implemented as a OneOfCodec wrapper.
      Type Parameters:
      T - Target type.
      Parameters:
      left - Primary codec.
      right - Fallback codec.
      Returns:
      A fallback-enabled codec.

    • either

      static <A,B> Codec<Either<A,B>> either(Codec<A> left, Codec<B> right)
      Creates a codec for an Either container.
      Type Parameters:
      A - Left branch type.
      B - Right branch type.
      Parameters:
      left - Codec for type A.
      right - Codec for type B.
      Returns:
      A codec for Either.

    • oneOf

      @SafeVarargs static <T> Codec<T> oneOf(Codec<? extends T>... codecs)
      Combines multiple codecs to be tried in sequence.
      Type Parameters:
      T - Target type.
      Parameters:
      codecs - Array of codecs to attempt.
      Returns:
      A multi-branch codec.

    • xmap

      default <R> Codec<R> xmap(Function<? super T, ? extends R> forward, Function<? super R, ? extends T> backward)
      Transforms this codec to handle a new type R via two-way conversion functions.
      Type Parameters:
      R - The new target Java type.
      Parameters:
      forward - Conversion function from T to R.
      backward - Conversion function from R to T.
      Returns:
      A codec for type R.

    • orElse

      default Codec<T> orElse(T defaultValue)
      Wraps this codec with a default value to be used if decoding fails or returns null.
      Parameters:
      defaultValue - The value to return on failure.
      Returns:
      A codec that provides a default result.

    • list

      default Codec<List<T>> list()
      Creates a codec for a List of elements of type T.
      Returns:
      A codec for a List of T.

    • unchecked

      default <U> Codec<U> unchecked()
      Performs an unsafe cast of this codec to another type.
      Type Parameters:
      U - Target type.
      Returns:
      The same codec instance cast to Codec of U.

    • collection

      default <C extends Collection<T>> Codec<C> collection(Supplier<C> factory)
      Creates a codec for a specific collection implementation. Handles complex logic to propagate list serialization through OneOf codecs.
      Type Parameters:
      C - The specific collection type (e.g., Set, Queue).
      Parameters:
      factory - Supplier to create a new collection instance.
      Returns:
      A collection-specific codec.

    • optional

      default Codec<Optional<T>> optional()
      Wraps the current codec to handle Java Optional values.
      Returns:
      A codec for Optional of T.

    • nullable

      default Codec<T> nullable()
      Modifies the codec to treat null Java values as empty serialized states.
      Returns:
      A null-safe version of this codec.

    • fieldOf

      default <P> Codec.Field<P,T> fieldOf(String name, Function<P,T> getter)
      Defines this codec as a field within a larger object structure.
      Type Parameters:
      P - The parent object type.
      Parameters:
      name - The name of the field.
      getter - The function to get the field value from the parent.
      Returns:
      A Field definition object.