Class DefaultCasterChain<T, S extends io.fluxzero.common.api.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 io.fluxzero.common.api.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:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    protected static class 
    DefaultCasterChain.ConvertingSerializedObject<I,O>
    A SerializedObject wrapper that applies a Converter to translate data from one format to another.
    protected static class 
    DefaultCasterChain.DataRevision
    Represents a unique combination of serialized object type and revision, used as a key in the caster registry.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    DefaultCasterChain(Collection<?> casterCandidates, Class<T> dataType, boolean down)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    canSkipCast(S input, Integer desiredRevision)
    Whether this chain is guaranteed to return the input as one unchanged logical value.
    Stream<S>
    cast(Stream<? extends S> input, Integer desiredRevision)
    Casts the given stream of input values to the output format, optionally considering a target revision.
    S
    castFirstOrNull(S input, Integer desiredRevision)
     
    protected static <BEFORE,INTERNAL>
    CasterChain<io.fluxzero.common.api.SerializedObject<BEFORE>, io.fluxzero.common.api.SerializedObject<?>>
    create(Collection<?> casterCandidates, io.fluxzero.common.serialization.Converter<BEFORE,INTERNAL> converter, boolean down)
     
    protected static <BEFORE,INTERNAL>
    CasterChain<io.fluxzero.common.api.SerializedObject<BEFORE>, io.fluxzero.common.api.SerializedObject<?>>
    create(Collection<?> casterCandidates, io.fluxzero.common.serialization.Converter<BEFORE,INTERNAL> converter, boolean down, UnaryOperator<String> inputTypeResolver)
     
    protected static <T, S extends io.fluxzero.common.api.SerializedObject<T>>
    CasterChain<S,S>
    create(Collection<?> casterCandidates, Class<T> dataType, boolean down)
     
    static <T, S extends io.fluxzero.common.api.SerializedObject<T>>
    CasterChain<S,S>
    createDowncaster(Collection<?> casterCandidates, Class<T> dataType)
    Builds a downcaster chain from annotated candidates for the supplied serialized data type.
    static <BEFORE,INTERNAL>
    CasterChain<io.fluxzero.common.api.SerializedObject<BEFORE>, io.fluxzero.common.api.SerializedObject<?>>
    createUpcaster(Collection<?> casterCandidates, io.fluxzero.common.serialization.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.
    static <BEFORE,INTERNAL>
    CasterChain<io.fluxzero.common.api.SerializedObject<BEFORE>, io.fluxzero.common.api.SerializedObject<?>>
    createUpcaster(Collection<?> casterCandidates, io.fluxzero.common.serialization.Converter<BEFORE,INTERNAL> converter, UnaryOperator<String> inputTypeResolver)
    Creates an upcaster chain that normalizes serialized type identifiers before selecting a content upcaster.
    static <T, S extends io.fluxzero.common.api.SerializedObject<T>>
    CasterChain<S,S>
    createUpcaster(Collection<?> casterCandidates, Class<T> dataType)
    Builds an upcaster chain from annotated candidates for the supplied serialized data type.
    List<io.fluxzero.common.api.tracking.ConsumerFilter.PayloadType>
    inputRevisions()
    Complete registered input revisions, or null for an unknown/custom casting implementation.
    S
    prepareForSkippingCast(S input, Integer desiredRevision)
    Prepares an input for direct deserialization when no content caster can transform, split or drop it.
    io.fluxzero.common.Registration
    registerCasterCandidates(Object... candidates)
    Registers the complete batch atomically; a conflicting candidate leaves the chain unchanged.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface Caster

    cast

    Methods inherited from interface CasterChain

    intercept

  • Constructor Details

    • DefaultCasterChain

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

  • Method Details

    • createUpcaster

      public static <BEFORE,INTERNAL> CasterChain<io.fluxzero.common.api.SerializedObject<BEFORE>, io.fluxzero.common.api.SerializedObject<?>> createUpcaster(Collection<?> casterCandidates, io.fluxzero.common.serialization.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<io.fluxzero.common.api.SerializedObject<BEFORE>, io.fluxzero.common.api.SerializedObject<?>> createUpcaster(Collection<?> casterCandidates, io.fluxzero.common.serialization.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 io.fluxzero.common.api.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 io.fluxzero.common.api.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<io.fluxzero.common.api.SerializedObject<BEFORE>, io.fluxzero.common.api.SerializedObject<?>> create(Collection<?> casterCandidates, io.fluxzero.common.serialization.Converter<BEFORE,INTERNAL> converter, boolean down)

    • create

      protected static <BEFORE,INTERNAL> CasterChain<io.fluxzero.common.api.SerializedObject<BEFORE>, io.fluxzero.common.api.SerializedObject<?>> create(Collection<?> casterCandidates, io.fluxzero.common.serialization.Converter<BEFORE,INTERNAL> converter, boolean down, UnaryOperator<String> inputTypeResolver)

    • create

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

    • inputRevisions

      public List<io.fluxzero.common.api.tracking.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 io.fluxzero.common.api.SerializedObject<T>>

    • registerCasterCandidates

      public io.fluxzero.common.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 io.fluxzero.common.api.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 io.fluxzero.common.api.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 io.fluxzero.common.api.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 io.fluxzero.common.api.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 io.fluxzero.common.api.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