Class DefaultCasterChain<T, S extends SerializedObject<T>>

java.lang.Object
io.fluxzero.sdk.common.serialization.casting.DefaultCasterChain<T,S>
Type Parameters:
T - the data type of the serialized value (e.g. byte[] or JsonNode)
S - the serialized object wrapper containing the data
All Implemented Interfaces:
Caster<S,S>, CasterChain<S,S>
public class DefaultCasterChain<T, S extends SerializedObject<T>> extends Object implements CasterChain<S,S>
Default implementation of the CasterChain interface used for managing and applying casting operations— typically upcasting or downcasting—on SerializedObject instances.

This class supports flexible runtime registration and execution of type transformers based on annotations such as Upcast and Downcast. It allows the system to evolve serialized object schemas over time while maintaining backward and forward compatibility.

Key Responsibilities

  • Applies registered caster functions based on a combination of object type and revision.
  • Supports both upcasting (increasing version) and downcasting (lowering version) based on configuration.
  • Provides utility methods to create upcasters and downcasters using optional format conversion logic.
  • Allows chaining via intercept() for use with ConvertingSerializedObject wrappers.

Usage

CasterChain<SerializedObject<byte[]>, SerializedObject<?>> upcaster =
    DefaultCasterChain.createUpcaster(candidates, JsonNode.class);

Stream<SerializedObject<byte[]>> transformed = upcaster.cast(inputStream, latestRevision);

Design Notes

  • Backed by a Map<DataRevision, AnnotatedCaster<T>> which ensures casting operations are deterministic.
  • When multiple methods would match the same revision, an exception is thrown to prevent ambiguous resolution.
  • Supports optional format conversion using a Converter via DefaultCasterChain.ConvertingSerializedObject wrapper.
See Also:

  • Constructor Details

    • DefaultCasterChain

      protected DefaultCasterChain(Collection<?> casterCandidates, Class<T> dataType, boolean down)

  • Method Details

    • createUpcaster

      public static <BEFORE,INTERNAL> CasterChain<SerializedObject<BEFORE>, SerializedObject<?>> createUpcaster(Collection<?> casterCandidates, Converter<BEFORE,INTERNAL> converter)
      Builds an upcaster chain from the candidate handlers, using the converter to bridge their internal data representation without normalizing incoming type identifiers before upcaster selection.

    • createUpcaster

      public static <BEFORE,INTERNAL> CasterChain<SerializedObject<BEFORE>, SerializedObject<?>> createUpcaster(Collection<?> casterCandidates, Converter<BEFORE,INTERNAL> converter, UnaryOperator<String> inputTypeResolver)
      Creates an upcaster chain that normalizes serialized type identifiers before selecting a content upcaster.
      Parameters:
      casterCandidates - candidate objects containing upcaster methods
      converter - converter between serialized and intermediate data
      inputTypeResolver - resolver applied to each incoming serialized type
      Returns:
      the configured upcaster chain

    • createUpcaster

      public static <T, S extends SerializedObject<T>> CasterChain<S,S> createUpcaster(Collection<?> casterCandidates, Class<T> dataType)
      Builds an upcaster chain from annotated candidates for the supplied serialized data type.

    • createDowncaster

      public static <T, S extends SerializedObject<T>> CasterChain<S,S> createDowncaster(Collection<?> casterCandidates, Class<T> dataType)
      Builds a downcaster chain from annotated candidates for the supplied serialized data type.

    • create

      protected static <BEFORE,INTERNAL> CasterChain<SerializedObject<BEFORE>, SerializedObject<?>> create(Collection<?> casterCandidates, Converter<BEFORE,INTERNAL> converter, boolean down)

    • create

      protected static <BEFORE,INTERNAL> CasterChain<SerializedObject<BEFORE>, SerializedObject<?>> create(Collection<?> casterCandidates, Converter<BEFORE,INTERNAL> converter, boolean down, UnaryOperator<String> inputTypeResolver)

    • create

      protected static <T, S extends SerializedObject<T>> CasterChain<S,S> create(Collection<?> casterCandidates, Class<T> dataType, boolean down)

    • inputRevisions

      public List<ConsumerFilter.PayloadType> inputRevisions()
      Description copied from interface: CasterChain
      Complete registered input revisions, or null for an unknown/custom casting implementation.
      Specified by:
      inputRevisions in interface CasterChain<T, S extends SerializedObject<T>>

    • registerCasterCandidates

      public Registration registerCasterCandidates(Object... candidates)
      Registers the complete batch atomically; a conflicting candidate leaves the chain unchanged.
      Specified by:
      registerCasterCandidates in interface CasterChain<T, S extends SerializedObject<T>>
      Parameters:
      candidates - one or more caster providers
      Returns:
      a Registration that can be used to remove the registered casters

    • cast

      public Stream<S> cast(Stream<? extends S> input, Integer desiredRevision)
      Description copied from interface: Caster
      Casts the given stream of input values to the output format, optionally considering a target revision.
      Specified by:
      cast in interface Caster<T, S extends SerializedObject<T>>
      Parameters:
      input - the input stream of values
      desiredRevision - the target revision number (nullable)
      Returns:
      a stream of transformed output values

    • castFirstOrNull

      public S castFirstOrNull(S input, Integer desiredRevision)
      Specified by:
      castFirstOrNull in interface CasterChain<T, S extends SerializedObject<T>>

    • canSkipCast

      public boolean canSkipCast(S input, Integer desiredRevision)
      Description copied from interface: CasterChain
      Whether this chain is guaranteed to return the input as one unchanged logical value.

      The default is deliberately conservative. Implementations may return true only when no caster can drop, split or transform this input at the requested revision.

      Specified by:
      canSkipCast in interface CasterChain<T, S extends SerializedObject<T>>

    • prepareForSkippingCast

      public S prepareForSkippingCast(S input, Integer desiredRevision)
      Description copied from interface: CasterChain
      Prepares an input for direct deserialization when no content caster can transform, split or drop it. Implementations may normalize its type identifier, but must not execute content casters or converters.

      Returns the prepared input, or null when the ordinary casting path is required. The default is deliberately conservative, including for intercepted chains whose callbacks may transform their input.

      Specified by:
      prepareForSkippingCast in interface CasterChain<T, S extends SerializedObject<T>>
      Parameters:
      input - the input value
      desiredRevision - the target revision number (nullable)
      Returns:
      the input with any required type normalization, or null if casting cannot safely be skipped