Interface Codec<V>

Type Parameters:
V - the type of value this codec handles
All Known Implementing Classes:
BinaryCodec, BinaryNumberCodec, BooleanCodec, ChoiceCodec, ConstantCodec, FixedCodePointStringCodec, FixedHexStringCodec, FixedListCodec, LazyCodec, NotImplementedCodec, PairCodec, RecordingCodec, SequentialObjectCodec, StreamCodePointStringCodec, StreamHexStringCodec, StreamListCodec, TaggedObjectCodec, TripleCodec, VariableByteLengthCodec, VariableItemLengthCodec
public interface Codec<V>
Interface for encoding and decoding values to and from byte streams.

  • Method Summary

    Modifier and Type
    Method
    Description
    V
    decode(InputStream input)
    Decodes a value from the input stream.
    EncodeResult
    encode(V value, OutputStream output)
    Encodes the given value and writes it to the output stream.
    default Codec<V>
    validate(Validator<V> validator)
    Returns a new codec that applies a Validator on both encode and decode.
    default Codec<V>
    validate(Predicate<V> check, String message)
    Returns a new codec that checks the value on both encode and decode.
    default Codec<V>
    validate(Predicate<V> check, Function<V,String> message)
    Returns a new codec that checks the value on both encode and decode, deriving the error message from the rejected value.
    default <U> Codec<U>
    xmap(Converter<V,U> converter)
    Returns a new codec that maps between types using a Converter.
    default <U> Codec<U>
    xmap(Function<V,U> decoder, Function<U,V> encoder)
    Returns a new codec that applies bidirectional mapping functions to transform between value types.

  • Method Details

    • encode

      EncodeResult encode(V value, OutputStream output) throws IOException
      Encodes the given value and writes it to the output stream.
      Parameters:
      value - the value to encode
      output - the output stream to write the encoded bytes to
      Returns:
      the encode result containing logical count and bytes written
      Throws:
      IOException - if an I/O error occurs during encoding
      IllegalArgumentException - if the value violates codec constraints (e.g. wrong length)
      CodecException - if an encoding error is detected (e.g. invalid value, field errors)

    • decode

      V decode(InputStream input) throws IOException
      Decodes a value from the input stream.
      Parameters:
      input - the input stream to read the encoded bytes from
      Returns:
      the decoded value
      Throws:
      IOException - if an I/O error occurs during decoding
      CodecException - if a decoding error is detected (e.g. invalid data, field errors)

    • xmap

      default <U> Codec<U> xmap(Function<V,U> decoder, Function<U,V> encoder)
      Returns a new codec that applies bidirectional mapping functions to transform between value types.

      The decoder function is applied after decoding (base type → mapped type), and the encoder function is applied before encoding (mapped type → base type).

      Type Parameters:
      U - the mapped value type
      Parameters:
      decoder - the function to apply after decoding
      encoder - the function to apply before encoding
      Returns:
      a new codec that maps between V and U

    • xmap

      default <U> Codec<U> xmap(Converter<V,U> converter)
      Returns a new codec that maps between types using a Converter.

      The converter provides the bidirectional mapping between the base type V and the mapped type U. This is useful for reusable or composed conversions. 

      BiMap<Integer, Color> colors = BiMap.of(
    Map.entry(1, Color.RED),
    Map.entry(2, Color.GREEN),
    Map.entry(3, Color.BLUE)
);
Codec<Color> colorCodec = Codecs.uint8().xmap(colors);
      Type Parameters:
      U - the mapped value type
      Parameters:
      converter - the bidirectional conversion between V and U
      Returns:
      a new codec that maps between V and U

    • validate

      default Codec<V> validate(Predicate<V> check, String message)
      Returns a new codec that checks the value on both encode and decode.

      The check runs before writing on encode and after reading on decode. A failed check throws IllegalArgumentException on encode and CodecException on decode. 

      Codec<Integer> amount = Codecs.uint16().validate(v -> v > 0, "amount must be positive");
      Parameters:
      check - the condition the value must satisfy
      message - the error message used when the check fails
      Returns:
      a new codec that validates values passing through it
      Throws:
      NullPointerException - if any argument is null

    • validate

      default Codec<V> validate(Predicate<V> check, Function<V,String> message)
      Returns a new codec that checks the value on both encode and decode, deriving the error message from the rejected value.

      The message function is applied only when the check fails. 

      Codec<String> type = Codecs.ascii(2).validate("BT"::equals,
    actual -> "expected constant [BT] but got [%s]".formatted(actual));
      Parameters:
      check - the condition the value must satisfy
      message - produces the error message from the rejected value
      Returns:
      a new codec that validates values passing through it
      Throws:
      NullPointerException - if any argument is null

    • validate

      default Codec<V> validate(Validator<V> validator)
      Returns a new codec that applies a Validator on both encode and decode.

      A validator pairs the condition with its message, so a check can be named once and shared across the codecs that need it rather than restated at each call site: 

      static final Validator<Integer> POSITIVE_AMOUNT =
    Validator.of(v -> v > 0, "amount must be positive");

Codec<Integer> amount = Codecs.uint16().validate(POSITIVE_AMOUNT);
Codec<Integer> fee = Codecs.uint32().validate(POSITIVE_AMOUNT.and(UNDER_LIMIT));
      Parameters:
      validator - the check to apply
      Returns:
      a new codec that validates values passing through it
      Throws:
      NullPointerException - if validator is null