Interface Serializer

All Superinterfaces:
ContentFilter
All Known Implementing Classes:
AbstractSerializer, JacksonSerializer
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

    • serializedPropertyPaths

      default List<String> serializedPropertyPaths(Object payload, String propertyPath)
      Resolves a slash-separated Java property path to its serialized names, with the canonical name first and any accepted aliases following it. Data protection uses this when editing an intermediate payload without losing unrelated serialized fields. An empty list means the property is not serialized.

      Serializers that rename, flatten, or alias properties must override this method using their own configuration. Returned path segments use JSON Pointer escaping (~0 and ~1), without a leading slash. Implementations must reject configurations whose mapping cannot be established safely. The default throws rather than guessing a mapping that could leave private values in the serialized payload.

      Parameters:
      payload - the logical payload, used to resolve polymorphic nested values
      propertyPath - the Java property path
      Returns:
      canonical serialized path and aliases, or an empty list for an omitted property
      Throws:
      UnsupportedOperationException - if safe property mapping is not supported

    • serialize

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

    • normalize

      io.fluxzero.common.api.SerializedObject<byte[]> normalize(io.fluxzero.common.api.SerializedObject<?> serializedObject)
      Normalizes an already-serialized object to the target byte-based representation of this serializer.
      Parameters:
      serializedObject - the serialized object to normalize
      Returns:
      the normalized byte-based serialized object

    • serialize

      io.fluxzero.common.api.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(io.fluxzero.common.api.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(io.fluxzero.common.api.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 io.fluxzero.common.api.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<io.fluxzero.common.api.SerializedMessage> dataStream, io.fluxzero.common.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<io.fluxzero.common.api.SerializedMessage> dataStream, io.fluxzero.common.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<io.fluxzero.common.api.SerializedMessage> dataStream, io.fluxzero.common.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<io.fluxzero.common.api.SerializedMessage> dataStream, io.fluxzero.common.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

    • deserializeFirstMessageOrNull

      default DeserializingMessage deserializeFirstMessageOrNull(io.fluxzero.common.api.SerializedMessage message, io.fluxzero.common.MessageType messageType, String topic)
      Deserializes one SerializedMessage into the first resulting DeserializingMessage, or null if no result remains.

      This preserves the same semantics as deserializeMessages(Stream.of(message), ...).findAny(): upcasters that drop a message return null, and upcasters that split a message contribute only their first result.

      Parameters:
      message - the serialized message
      messageType - the type of message (COMMAND, EVENT, etc.)
      topic - the topic of the message if the type is CUSTOM or DOCUMENT, otherwise null
      Returns:
      the first deserialized message, or null

    • deserializeFirstMessage

      default Optional<DeserializingMessage> deserializeFirstMessage(io.fluxzero.common.api.SerializedMessage message, io.fluxzero.common.MessageType messageType, String topic)
      Deserializes one SerializedMessage into the first resulting DeserializingMessage.

      This preserves the same semantics as deserializeMessages(Stream.of(message), ...).findAny(): upcasters that drop a message return Optional.empty(), and upcasters that split a message contribute only their first result.

      Parameters:
      message - the serialized message
      messageType - the type of message (COMMAND, EVENT, etc.)
      topic - the topic of the message if the type is CUSTOM or DOCUMENT, otherwise null
      Returns:
      the first deserialized message, if any

    • serializedClassWithoutUpcasting

      default Class<?> serializedClassWithoutUpcasting(io.fluxzero.common.api.SerializedObject<?> serializedObject)
      Resolves the payload class when this serialized value is guaranteed not to require structural upcasting.

      This conservative hook supports allocation-sensitive replay planning. null means that callers must use the normal deserialization pipeline; it does not mean that the serialized type is unknown.

    • deserializeMessage

      default DeserializingMessage deserializeMessage(io.fluxzero.common.api.SerializedMessage message, io.fluxzero.common.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

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

    • registerDowncasters

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

    • registerCasters

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

    • registerTypeCaster

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

    • registerTypeAlias

      default io.fluxzero.common.Registration registerTypeAlias(String oldType, String newType)
      Registers an exact alias from a serialized type name to its current type name.

      This is the preferred name for registerTypeCaster(String, String). Multiple aliases may be registered and chained. Exact aliases take precedence over package aliases.

      Parameters:
      oldType - the legacy serialized type name
      newType - the current type name
      Returns:
      a registration handle

    • registerPackageAlias

      default io.fluxzero.common.Registration registerPackageAlias(String oldPackage, String newPackage)
      Registers an alias from a legacy package and all its subpackages to a current package.

      Implementations that support package aliases should preserve the class-name suffix and prefer the longest matching package prefix when multiple aliases match.

      Parameters:
      oldPackage - the legacy package name, without a trailing wildcard
      newPackage - the current package name, without a trailing wildcard
      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

    • resolveTypeName

      default String resolveTypeName(String type)
      Resolves a serialized type identifier after applying historical aliases. Fully qualified and canonical type names remain valid, while unique simple or partial names registered through RegisterType resolve to their fully qualified class name.
      Parameters:
      type - the serialized type identifier
      Returns:
      the current resolvable type name, or the unchanged identifier if it is unknown

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