Module net.minestom.server
Package net.minestom.server.codec

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) 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) 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) 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

      @Contract(pure=true) static <T> StructCodec<T> RegistryTaggedUnion(Registry<StructCodec<? extends T>> registry, Function<T,StructCodec<? extends T>> serializerGetter, String key)
      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

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

    • Either

      @Contract(pure=true) 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 Codec and Codec

    • optional

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

    • optional

      @Contract(pure=true) 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 Codec
      Throws:
      NullPointerException - if defaultValue is null, use optional() instead.

    • transform

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

    • list

      @Contract(pure=true) default Codec<List<T>> list(int maxSize)
      Creates a list codec of Codec 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 Codec

    • list

      @Contract(pure=true) default Codec<List<T>> list()
      Creates an unbounded list codec. See list(int)
      Returns:
      the unbounded list codec of type Codec

    • listOrSingle

      @Contract(pure=true) default Codec<List<@Nullable T>> listOrSingle(int maxSize)
      Returns a 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 Codec

    • listOrSingle

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

    • set

      @Contract(pure=true) default Codec<Set<T>> set(int maxSize)
      Creates a 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 Codec

    • set

      @Contract(pure=true) default Codec<Set<T>> set()
      Creates an unbounded set. See set(int)
      Returns:
      the set codec of type Codec

    • mapValue

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

    • mapValue

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

    • unionType

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

    • unionType

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

    • orElse

      @Contract(pure=true) 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 Codec