Interface Serializer

All Superinterfaces:
ContentFilter
All Known Implementing Classes:
AbstractSerializer, JacksonSerializer, ProxySerializer
public interface Serializer extends ContentFilter
Mechanism to serialize and deserialize objects to and from byte[] representations.

A Serializer transforms Java objects into Data containers (holding raw byte arrays) and restores them back, optionally using format hints or handling type revisions via upcasting/downcasting.

It also provides lazy deserialization and registration hooks for custom (de)casters. This makes it central to Fluxzero’s persistence, transport, and replay systems.

Responsibilities

  • Serialize objects with optional format hints
  • Deserialize to objects or messages, lazily if needed
  • Support revisioned types via upcasting and downcasting
  • Enable flexible error strategies for unknown types
See Also:

  • Method Details

    • serialize

      default Data<byte[]> serialize(Object object)
      Serializes the given object to a Data wrapper using the default format.
      Parameters:
      object - the object to serialize
      Returns:
      the serialized object wrapped in Data
      Throws:
      SerializationException - if serialization fails

    • serialize

      Data<byte[]> serialize(Object object, String format)
      Serializes the given object into a Data wrapper using the specified format.
      Parameters:
      object - the object to serialize
      format - the desired serialization format (e.g. \"json\"); may be null
      Returns:
      serialized object as Data
      Throws:
      SerializationException - if serialization fails

    • deserialize

      default <T> T deserialize(SerializedObject<byte[]> data)
      Upcasts and deserializes the given Data object to an object of type T. If the input data cannot be deserialized to a single result (due to upcasting) a DeserializationException is thrown.
      Type Parameters:
      T - Type of object to deserialize to
      Parameters:
      data - Data to deserialize
      Returns:
      Object resulting from the deserialization
      Throws:
      DeserializationException - if deserialization fails

    • deserialize

      default <T> T deserialize(SerializedObject<byte[]> data, Class<T> type)
      Upcasts and deserializes the given Data object to an object of type T. If the input data cannot be deserialized to a single result (due to upcasting) a DeserializationException is thrown.
      Type Parameters:
      T - Type of object to deserialize to
      Parameters:
      data - Data to deserialize
      Returns:
      Object resulting from the deserialization
      Throws:
      DeserializationException - if deserialization fails

    • deserialize

      <I extends SerializedObject<byte[]>> Stream<DeserializingObject<byte[],I>> deserialize(Stream<I> dataStream, UnknownTypeStrategy unknownTypeStrategy)
      Upcasts and deserializes a stream of serialized objects. Each result in the output stream contains both a provider for the deserialized object and the serialized object after upcasting that is used as the source of the deserialized object.

      Deserialization is performed lazily. This means that actual conversion for a given result in the output stream only happens if DeserializingObject.getPayload() is invoked on the result. This has the advantage that a caller can inspect what type will be returned via

      invalid reference 
      DeserializingObject#getSerializedObject()
      before deciding to go through with the deserialization.

      You can specify whether deserialization of a result in the output stream should fail with a DeserializationException if a type is unknown (not a class). It is up to the implementation to determine what should happen if a type is unknown but the failOnUnknownType flag is false.

      Type Parameters:
      I - the type of the serialized object
      Parameters:
      dataStream - data input stream to deserialize
      unknownTypeStrategy - value that determines what to do when encountering unknown types
      Returns:
      a stream containing deserialization results

    • deserializeMessages

      default Stream<DeserializingMessage> deserializeMessages(Stream<SerializedMessage> dataStream, MessageType messageType)
      Deserializes a stream of SerializedMessage into DeserializingMessage instances with the specified MessageType.
      Parameters:
      dataStream - the stream of messages
      messageType - the type of message (COMMAND, EVENT, etc.)
      Returns:
      stream of deserialized messages

    • deserializeMessages

      default Stream<DeserializingMessage> deserializeMessages(Stream<SerializedMessage> dataStream, MessageType messageType, String topic)
      Deserializes a stream of SerializedMessage into DeserializingMessage instances with the specified MessageType.
      Parameters:
      dataStream - the stream of messages
      messageType - the type of message (COMMAND, EVENT, etc.)
      topic - the topic of the message if the type is CUSTOM or DOCUMENT, otherwise null
      Returns:
      stream of deserialized messages

    • deserializeMessages

      default Stream<DeserializingMessage> deserializeMessages(Stream<SerializedMessage> dataStream, MessageType messageType, UnknownTypeStrategy unknownTypeStrategy)
      Deserializes a stream of SerializedMessage into DeserializingMessage instances with the specified MessageType.
      Parameters:
      dataStream - the stream of messages
      messageType - the type of message (COMMAND, EVENT, etc.)
      unknownTypeStrategy - value that determines what to do when encountering unknown types
      Returns:
      stream of deserialized messages

    • deserializeMessages

      default Stream<DeserializingMessage> deserializeMessages(Stream<SerializedMessage> dataStream, MessageType messageType, String topic, UnknownTypeStrategy unknownTypeStrategy)
      Deserializes a stream of SerializedMessage into DeserializingMessage instances with the specified MessageType.
      Parameters:
      dataStream - the stream of messages
      messageType - the type of message (COMMAND, EVENT, etc.)
      topic - the topic of the message if the type is CUSTOM or DOCUMENT, otherwise null
      unknownTypeStrategy - value that determines what to do when encountering unknown types
      Returns:
      stream of deserialized messages

    • deserializeMessage

      default DeserializingMessage deserializeMessage(SerializedMessage message, MessageType messageType)
      Deserializes a single SerializedMessage into a DeserializingMessage. If the input data cannot be deserialized to a single result (due to upcasting) a DeserializationException is thrown.
      Parameters:
      message - the message to deserialize
      messageType - the message type
      Returns:
      the deserialized message

    • convert

      <V> V convert(Object value, Type type)
      Converts a given object to another type using the serializer's object mapping rules.
      Type Parameters:
      V - the result type
      Parameters:
      value - the input value
      type - the target type
      Returns:
      the converted value

    • clone

      <V> V clone(Object value)
      Creates a deep copy of the given object using serialization.
      Type Parameters:
      V - the type of the value
      Parameters:
      value - the object to clone
      Returns:
      a deep copy

    • registerUpcasters

      Registration registerUpcasters(Object... casterCandidates)
      Registers one or more upcaster candidates.
      Parameters:
      casterCandidates - beans with upcasting logic
      Returns:
      a registration handle

    • registerDowncasters

      Registration registerDowncasters(Object... casterCandidates)
      Registers one or more downcaster candidates.
      Parameters:
      casterCandidates - beans with downcasting logic
      Returns:
      a registration handle

    • registerCasters

      default Registration registerCasters(Object... casterCandidates)
      Registers upcasters and downcasters in one step.
      Parameters:
      casterCandidates - beans with casting logic
      Returns:
      a merged registration handle

    • registerTypeCaster

      Registration registerTypeCaster(String oldType, String newType)
      Registers a mapping from an old type identifier to a new one.
      Parameters:
      oldType - the legacy type name
      newType - the canonical or updated type name
      Returns:
      a registration handle

    • upcastType

      String upcastType(String type)
      Returns the upcasted type name for a legacy type identifier.
      Parameters:
      type - the original type
      Returns:
      the remapped (or unchanged) type name

    • downcast

      Object downcast(Object object, int desiredRevision)
      Downcasts the given object to a previous revision.
      Parameters:
      object - the object to downcast
      desiredRevision - the target revision
      Returns:
      a revisioned form of the object

    • downcast

      Object downcast(Data<?> data, int desiredRevision)
      Downcasts a Data object to the specified revision level.
      Parameters:
      data - the serialized data
      desiredRevision - the target revision number
      Returns:
      a transformed object matching the older revision