Interface Codec<T extends @UnknownNullability Object>

Type Parameters:
T - The type to be represented by this codec, nullable T will provide nullable results.
All Superinterfaces:
Decoder<T>, Encoder<T>
All Known Subinterfaces:
DataComponent<T>, StructCodec<R>
public interface Codec<T extends @UnknownNullability Object> extends Encoder<T>, Decoder<T>

A Codec represents a combined Encoder and Decoder for a value. Enabling easy encoding and decoding of values to and from a between formats, making serialization simple, reusable and type safe. Going between formats is handled by Transcoder.

Most of the primitive or commonly used codecs are provided as static fields in this interface. For example, INT is a codec for integers, and STRING is a codec for strings. You can even use Enum(Class) for enums, which will convert the enum to a string representation and back.

Codecs are immutable, you must chain methods to create a codec that you want. For example 
        Codec<@Nullable String> codec = Codec.STRING.optional()
        Codec<Set<@Nullable String>> setCodec = codec.set();

Heavily inspired by Mojang/DataFixerUpper, licensed under the MIT license.

  • Field Details

  • Method Details

    • Enum

      @Contract(pure=true, value="_ -> new") static <E extends Enum<E>> Codec<E> Enum(Class<E> enumClass)
      Creates an enum codec from a given class
      Converts the Enum.name() into lowercase when encoding and uppercase into decoding then passing it to Enum.valueOf(Class, String)
      Type Parameters:
      E - Enum type, E must be an enum
      Parameters:
      enumClass - the enum class
      Returns:
      the codec enum

    • Recursive

      @Contract(pure=true, value="_ -> new") static <T> Codec<T> Recursive(Function<Codec<T>,Codec<T>> func)
      Create a recursive codec from the parent codec
      Useful when you want to keep encoding/decoding until there is nothing left.
      Type Parameters:
      T - The codec Type
      Parameters:
      func - the function to get the codec from.
      Returns:
      the recursive codec

    • ForwardRef

      @Contract(pure=true, value="_ -> new") static <T> Codec<T> ForwardRef(Supplier<Codec<T>> supplier)
      Lazily gets the reference of a codec; considered immutably lazy.
      Useful for breaking possible cyclic loading of recursive codecs. This may become a stable value in the future; don't rely on supplier getting called multiple times.
      Type Parameters:
      T - the codec type
      Parameters:
      supplier - the supplier to load the codec from.
      Returns:
      the supplier

    • RegistryTaggedUnion

      @Deprecated @Contract(pure=true, value="_, _, _ -> new") static <T> StructCodec<T> RegistryTaggedUnion(Registry<StructCodec<? extends T>> registry, Function<T, StructCodec<? extends T>> serializerGetter, String key)
      Deprecated.
      Use RegistryTaggedUnion(String, Registry, Function) instead. Shortcut for RegistryTaggedUnion(Registries.Selector, Function, String)
      Type Parameters:
      T - the struct codec type.
      Parameters:
      registry - the codec registry
      serializerGetter - the codec getter
      key - the map key
      Returns:
      a StructCodec

    • RegistryTaggedUnion

      @Deprecated @Contract(pure=true, value="_, _, _ -> new") static <T> StructCodec<T> RegistryTaggedUnion(Registries.Selector<StructCodec<? extends T>> registrySelector, Function<T, StructCodec<? extends T>> serializerGetter, String key)
      Deprecated.
      Use RegistryTaggedUnion(String, Registries.Selector, Function) instead. Creates a StructCodec to bidirectionally map values of T to their encoded values
      Registry selectors will be used to lookup values of codecs of T. Then will be used to map to object T from key
      Type Parameters:
      T - the codec type
      Parameters:
      registrySelector - the registry selector used during lookup.
      serializerGetter - the serializer for each value of T
      key - the map key for T
      Returns:
      a StructCodec bidirectionally mapping values of T

    • RegistryTaggedUnion

      @Contract(pure=true, value="_, _ -> new") static <T> StructCodec<T> RegistryTaggedUnion(Registry<StructCodec<? extends T>> registry, Function<T, StructCodec<? extends T>> serializerGetter)
      Shortcut for RegistryTaggedUnion(String, Registry, Function) where key will be "type"
      Type Parameters:
      T - the struct codec type.
      Parameters:
      registry - the codec registry
      serializerGetter - the codec getter
      Returns:
      a StructCodec

    • RegistryTaggedUnion

      @Contract(pure=true, value="_, _, _ -> new") static <T> StructCodec<T> RegistryTaggedUnion(String key, Registry<StructCodec<? extends T>> registry, Function<T, StructCodec<? extends T>> serializerGetter)
      Shortcut for RegistryTaggedUnion(String, Registries.Selector, Function) where selector will be registry
      Type Parameters:
      T - the struct codec type.
      Parameters:
      key - the map key
      registry - the codec registry
      serializerGetter - the codec getter
      Returns:
      a StructCodec

    • RegistryTaggedUnion

      @Contract(pure=true, value="_, _ -> new") static <T> StructCodec<T> RegistryTaggedUnion(Registries.Selector<StructCodec<? extends T>> registrySelector, Function<T, StructCodec<? extends T>> serializerGetter)
      Shortcut for RegistryTaggedUnion(String, Registries.Selector, Function) where key will be "type"
      Type Parameters:
      T - the codec type
      Parameters:
      registrySelector - the registry selector used during lookup.
      serializerGetter - the serializer for each value of T
      Returns:
      a StructCodec bidirectionally mapping values of T

    • RegistryTaggedUnion

      @Contract(pure=true, value="_, _, _ -> new") static <T> StructCodec<T> RegistryTaggedUnion(String key, Registries.Selector<StructCodec<? extends T>> registrySelector, Function<T, StructCodec<? extends T>> serializerGetter)
      Creates a StructCodec to bidirectionally map values of T to their encoded values
      Registry selectors will be used to lookup values of codecs of T. Then will be used to map to object T from key
      Type Parameters:
      T - the codec type
      Parameters:
      key - the map key for T
      registrySelector - the registry selector used during lookup.
      serializerGetter - the serializer for each value of T
      Returns:
      a StructCodec bidirectionally mapping values of T

    • Either

      @Contract(pure=true, value="_, _ -> new") static <L,R> Codec<Either<L,R>> Either(Codec<L> leftCodec, Codec<R> rightCodec)
      Creates an Either Codec, depending on the value of Either decides which codec to use.
      Type Parameters:
      L - the left type
      R - the right type
      Parameters:
      leftCodec - the left codec
      rightCodec - the right codec
      Returns:
      a Codec with Either of L and R

    • EitherStruct

      @Contract(pure=true, value="_, _ -> new") static <L,R> StructCodec<Either<L,R>> EitherStruct(StructCodec<L> leftCodec, StructCodec<R> rightCodec)
      Creates an Either Codec, depending on the value of Either decides which codec to use.
      Type Parameters:
      L - the left type
      R - the right type
      Parameters:
      leftCodec - the left codec
      rightCodec - the right codec
      Returns:
      a StructCodec with Either of L and R

    • optional

      @Contract(pure=true, value="-> new") default Codec<@Nullable T> optional()
      Creates an optional codec, where null is encodable into Transcoder.createNull().
      Returns:
      the optional codec of type T

    • optional

      @Contract(pure=true, value="_ -> new") default Codec<@UnknownNullability T> optional(T defaultValue)
      Creates an optional codec, where null is encodable and is encoded when value equals defaultValue or null through Transcoder.createNull().
      The default value will be used if the decoding is null or fails to decode.
      Parameters:
      defaultValue - the default value
      Returns:
      the optional codec of type T
      Throws:
      NullPointerException - if defaultValue is null, use optional() instead.

    • transform

      @Contract(pure=true, value="_, _ -> new") default <S extends @UnknownNullability Object> Codec<S> transform(ThrowingFunction<T,S> to, ThrowingFunction<S,T> from)
      Transforms an object from S to another T and from T back to S
      Type Parameters:
      S - the type
      Parameters:
      to - the function to S from T
      from - the function from S to T
      Returns:
      the transforming codec of S

    • list

      @Contract(pure=true, value="_ -> new") default Codec<@Unmodifiable List<T>> list(int maxSize)
      Creates an unmodifiable list codec of T where its size is no larger than maxSize.
      Parameters:
      maxSize - the max size of the list before returning an error result.
      Returns:
      the list codec of type T

    • list

      @Contract(pure=true, value="-> new") default Codec<@Unmodifiable List<T>> list()
      Creates an unmodifiable unbounded list codec. See list(int)
      Returns:
      the unbounded list codec of type T

    • listOrSingle

      @Contract(pure=true, value="_ -> new") default Codec<@Unmodifiable @Nullable List<T>> listOrSingle(int maxSize)
      Returns an unmodifiable list or the first element or null if no such element exists.
      Parameters:
      maxSize - the max size of the list before returning an error result
      Returns:
      the list codec of type T

    • listOrSingle

      @Contract(pure=true, value="-> new") default Codec<@Unmodifiable @Nullable List<T>> listOrSingle()
      Returns an unmodifiable unbounded list or the first element or null if no such element exists. See listOrSingle(int)
      Returns:
      the list codec of type T

    • set

      @Contract(pure=true, value="_ -> new") default Codec<@Unmodifiable Set<T>> set(int maxSize)
      Creates an unmodifiable set where its max is no larger than maxSize
      Parameters:
      maxSize - the max size before returning an error result
      Returns:
      the set codec of type T

    • set

      @Contract(pure=true, value="-> new") default Codec<@Unmodifiable Set<T>> set()
      Creates an unmodifiable unbounded set. See set(int)
      Returns:
      the set codec of type T

    • mapValue

      @Contract(pure=true, value="_, _ -> new") default <V> Codec<@Unmodifiable Map<T,V>> mapValue(Codec<V> valueCodec, int maxSize)
      Creates an unmodifiable map of key T and value of V
      Type Parameters:
      V - the value type
      Parameters:
      valueCodec - the codec to use for V
      maxSize - the max size before returning an error result.
      Returns:
      the map codec of type T and V

    • mapValue

      @Contract(pure=true, value="_ -> new") default <V> Codec<@Unmodifiable Map<T,V>> mapValue(Codec<V> valueCodec)
      Creates an unmodifiable map of key T and value of V. See mapValue(Codec, int)
      Type Parameters:
      V - the value type
      Parameters:
      valueCodec - the codec to use for V
      Returns:
      the map codec of type T and V

    • mapValueTyped

      @Contract(pure=true, value="_, _, _ -> new") default <V> Codec<@Unmodifiable Map<T,V>> mapValueTyped(Function<T,Codec<V>> mapper, int maxSize, boolean cached)
      Creates an unmodifiable map of key T and value of V where the codec for V is determined by the key T
      Type Parameters:
      V - the value type
      Parameters:
      mapper - the function to get the codec for V from T
      maxSize - the max size before returning an error result.
      cached - whether to cache codecs for each key
      Returns:
      the map codec of type T and V

    • mapValueTyped

      @Contract(pure=true, value="_, _ -> new") default <V> Codec<@Unmodifiable Map<T,V>> mapValueTyped(Function<T,Codec<V>> mapper, int maxSize)
      Creates an unmodifiable map of key T and value of V where the codec for V is determined by the key T
      Type Parameters:
      V - the value type
      Parameters:
      mapper - the function to get the codec for V from T
      maxSize - the max size before returning an error result.
      Returns:
      the map codec of type T and V

    • mapValueTyped

      @Contract(pure=true, value="_, _ -> new") default <V> Codec<@Unmodifiable Map<T,V>> mapValueTyped(Function<T,Codec<V>> mapper, boolean cached)
      Creates an unmodifiable map of key T and value of V where the codec for V is determined by the key T
      Type Parameters:
      V - the value type
      Parameters:
      mapper - the function to get the codec for V from T
      cached - whether to cache codecs for each key
      Returns:
      the map codec of type T and V

    • mapValueTyped

      @Contract(pure=true, value="_ -> new") default <V> Codec<@Unmodifiable Map<T,V>> mapValueTyped(Function<T,Codec<V>> mapper)
      Creates an unmodifiable map of key T and value of V where the codec for V is determined by the key T
      Type Parameters:
      V - the value type
      Parameters:
      mapper - the function to get the codec for V from T
      Returns:
      the map codec of type T and V

    • unionType

      @Contract(pure=true, value="_, _ -> new") default <R> StructCodec<R> unionType(Function<T, StructCodec<? extends R>> serializers, Function<R, ? extends T> keyFunc)
      Creates a union type of type R. See unionType(String, Function, Function)
      Useful when you have an interface of T and want a codec subclasses of T
      Type Parameters:
      R - the return type; T or a subclass
      Parameters:
      serializers - the map from T value to its serializer
      keyFunc - to map from R to its value of T
      Returns:
      the struct codec union of R

    • unionType

      @Contract(pure=true, value="_, _, _ -> new") default <R> StructCodec<R> unionType(String keyField, Function<T, StructCodec<? extends R>> serializers, Function<R, ? extends T> keyFunc)
      Creates a union type of type R
      Useful when you have an interface of T and want a codec subclasses of T
      Type Parameters:
      R - the return type; T or a subclass
      Parameters:
      keyField - the map key
      serializers - the map from T value to its serializer
      keyFunc - to map from R to its value of T
      Returns:
      the struct codec union of R

    • orElse

      @Contract(pure=true, value="_ -> new") default Codec<T> orElse(Codec<T> other)
      Creates a or else codec where it will attempt to use the first codec then use the second one if it fails.
      If both codecs fail the first error will be returned instead.
      Parameters:
      other - the other codec
      Returns:
      the or else codec of T

    • orElse

      @Contract(pure=true, value="_ -> new") default <S> Codec<T> orElse(Codec<S> other, ThrowingFunction<S,T> mapper)
      Creates a or else codec where it will attempt to use the first codec then use the second one and transform via mapper if it fails.
      If both codecs fail the first error will be returned instead.
      Parameters:
      other - the other codec
      mapper - the mapper to transform the error into a value of T
      Returns:
      the or else codec of T