io.mats3.serial

Interface MatsSerializer<Z>

Type Parameters:

Z - The type which STOs and DTOs are serialized into. When employing JSON for the "outer" serialization of MatsTrace, it does not make that much sense to use a binary (Z=byte[]) "inner" representation of the DTOs and STOs, because JSON is terrible at serializing byte arrays.

All Known Implementing Classes:

MatsSerializerJson

public interface MatsSerializer<Z>

Defines the operations needed serialize and deserialize MatsTraces to and from byte arrays (e.g. UTF-8 encoded JSON or XML, or some binary serialization protocol), and STOs and DTOs to and from type Z, where Z can e.g. be byte arrays or Strings. This is separated out from the Mats communication implementation (i.e. JMS or RabbitMQ), as it is a separate aspect, i.e. both the JMS and RabbitMQ implementation can utilize the same serializer.

There are two levels of serialization needed: For the DTOs and STOs that the Mats API expose to the "end user", and then the serialization of the MatsTrace itself. There is an implementation of MatsTrace in the impl package called MatsTraceFieldImpl which is meant to be serialized by fields (thus the field names are short).

The default implementation in 'mats-serial-json' (MatsSerializerJson) employs the Jackson JSON library to serialize to JSON, both for the "inner" DTO-and-STO part, and for the "outer" MatsTrace part.

It is worth pointing out that all the communicating parties needs to be using the same serialization mechanism, as this constitute the "wire-representation" of the protocol that MatsTrace represents. There is however a mechanism to handle different serializations, by means of a metadata construct: Along with the serialized bytes, a metadata String must be provided. It is thus possible to construct a MatsSerializer that holds multiple underlying MatsSerializers, choosing based on the "meta" String. This can then be used to upgrade from a format to another.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	MatsSerializer.DeserializedMatsTrace<Z>
static class	MatsSerializer.SerializationException The methods in this interface shall throw this RuntimeException if they encounter problems.
static interface	MatsSerializer.SerializedMatsTrace

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	META_KEY_POSTFIX The key postfix that should be used for the "meta" key on which the meta value from serializeMatsTrace(MatsTrace) should be stored.

Method Summary

Modifier and Type	Method and Description
MatsTrace<Z>	createNewMatsTrace(java.lang.String traceId, java.lang.String flowId, MatsTrace.KeepMatsTrace keepMatsTrace, boolean nonPersistent, boolean interactive, long ttlMillis, boolean noAudit) Used when initiating a new Mats flow.
MatsSerializer.DeserializedMatsTrace<Z>	deserializeMatsTrace(byte[] serialized, int offset, int len, java.lang.String meta) Used for deserializing a byte array into a MatsTrace - this includes offset and length.
MatsSerializer.DeserializedMatsTrace<Z>	deserializeMatsTrace(byte[] serialized, java.lang.String meta) Used for deserializing a byte array into a MatsTrace - this uses the entire byte array.
<T> T	deserializeObject(Z serialized, java.lang.Class<T> type) Used for deserializing type Z (typically String) to STOs and DTOs.
default boolean	handlesMeta(java.lang.String meta) Whether this implementation of MatsSerializer handles the specified "meta".
<T> T	newInstance(java.lang.Class<T> type) Will return a new instance of the requested type.
MatsSerializer.SerializedMatsTrace	serializeMatsTrace(MatsTrace<Z> matsTrace) Used for serializing the MatsTrace to a byte array.
Z	serializeObject(java.lang.Object object) Used for serializing STOs and DTOs into type Z, typically String.
int	sizeOfSerialized(Z z)

Field Detail

META_KEY_POSTFIX

static final java.lang.String META_KEY_POSTFIX

The key postfix that should be used for the "meta" key on which the meta value from serializeMatsTrace(MatsTrace) should be stored. The meta value needs to be provided back when invoking deserializeMatsTrace(byte[], String).

See Also:

Constant Field Values

Method Detail

handlesMeta

default boolean handlesMeta(java.lang.String meta)

Whether this implementation of MatsSerializer handles the specified "meta".

This feature can at some point be used to configure up a bunch of serializers, whereby the one that handles the incoming format gets the job to deserialize it into a MatsTrace. One can then also migrate to a newer version in a two (three)-step fashion: First make a revision-change that includes the new serializer version, but still employs the old for serialization. Then, when all parties are upgraded to the new config, you make a new revision or minor change that changes the config to employ the new serializer for serialization. Then, when all parties are up on this version, you can potentially make a third version that removes the old serializer.

createNewMatsTrace

MatsTrace<Z> createNewMatsTrace(java.lang.String traceId,
                                java.lang.String flowId,
                                MatsTrace.KeepMatsTrace keepMatsTrace,
                                boolean nonPersistent,
                                boolean interactive,
                                long ttlMillis,
                                boolean noAudit)

Used when initiating a new Mats flow. Since the MatsTrace implementation is dependent on the serialization mechanism in use, we need a way provided by the serializer to instantiate new instances of the implementation of MatsTrace. A MatsTrace.Call must be added before it is good to be sent.

Parameters:

traceId - the Trace Id of this new MatsTrace.

flowId - System-defined id for this call flow - guaranteed unique.

keepMatsTrace - to which extent the MatsTrace should "keep trace", i.e. whether all Calls and States should be kept through the entire flow from initiation to terminator - default shall be MatsTrace.KeepMatsTrace.COMPACT. The only reason for why this exists is for debugging: The implementation cannot depend on this feature. To see the call history, do a toString() on the ProcessContext of the lambda, which should perform a toString() on the corresponding MatsTrace, which should have a human readable trace output.

nonPersistent - whether the message should be JMS-style "non-persistent" - default shall be false, i.e. the default is that a message is persistent.

interactive - whether the message should be prioritized in that a human is actively waiting for the reply, default shall be false.

ttlMillis - the number of milliseconds the message should live before being time out. 0 means "forever", and is the default.

noAudit - hint to the underlying implementation, or to any monitoring/auditing tooling on the Message Broker, that it does not make much value in auditing this message flow, typically because it is just a "getter" of information to show to some user, or a health-check validating that some service is up and answers in a timely fashion.

Returns:

a new instance of the underlying MatsTrace implementation.

serializeMatsTrace

MatsSerializer.SerializedMatsTrace serializeMatsTrace(MatsTrace<Z> matsTrace)

Used for serializing the MatsTrace to a byte array.

Parameters:

matsTrace - the MatsTrace instance to serialize.

Returns:

a byte array representation of the provided MatsTrace.

See Also:

META_KEY_POSTFIX

deserializeMatsTrace

MatsSerializer.DeserializedMatsTrace<Z> deserializeMatsTrace(byte[] serialized,
                                                             int offset,
                                                             int len,
                                                             java.lang.String meta)

Used for deserializing a byte array into a MatsTrace - this includes offset and length.

Parameters:

serialized - the byte array from which to reconstitute the MatsTrace.

offset - from where to start in the byte array.

len - how many bytes to use of the byte array, from the offset.

meta - some meta information that the deserialized needs back from the serialization process.

Returns:

the reconstituted MatsTrace.

See Also:

META_KEY_POSTFIX

deserializeMatsTrace

MatsSerializer.DeserializedMatsTrace<Z> deserializeMatsTrace(byte[] serialized,
                                                             java.lang.String meta)

Used for deserializing a byte array into a MatsTrace - this uses the entire byte array.

Parameters:

serialized - the byte array from which to reconstitute the MatsTrace.

meta - some meta information that the deserialized needs back from the serialization process.

Returns:

the reconstituted MatsTrace.

See Also:

META_KEY_POSTFIX

serializeObject

Z serializeObject(java.lang.Object object)

Used for serializing STOs and DTOs into type Z, typically String.

If null is provided as the Object parameter, then null shall be returned.

Parameters:

object - the object to serialize. If null is provided, then null shall be returned.

Returns:

a String representation of the provided object, or null if null was provided as 'object'.

sizeOfSerialized

int sizeOfSerialized(Z z)

Returns:

the size in bytes or characters of the serialized DTO or STO, shall return 0 for null. This is meant for metrics, NOT for determining an absolute byte size for a storage array or anything to this effect.

deserializeObject

<T> T deserializeObject(Z serialized,
                        java.lang.Class<T> type)

Used for deserializing type Z (typically String) to STOs and DTOs.

If null is provided as the 'Z serialized' parameter, then null shall be returned.

Parameters:

serialized - the value of type T that should be deserialized into an object of Class T. If null is provided, then null shall be returned.

type - the Class that the supplied value of type Z is thought to represent (i.e. the STO or DTO class).

Returns:

the reconstituted Object (STO or DTO), or null if null was provided as 'serialized'.

newInstance

<T> T newInstance(java.lang.Class<T> type)

Will return a new instance of the requested type. This is used to instantiate "empty objects" for Endpoint State objects (STOs), and to test, at Endpoint registration, whether it is possible to get hold of instances of the Request and Reply DTO for an Endpoint (to ensure that it will be possible in runtime).

The reason for having this in the MatsSerializer is that it is somewhat dependent on the object serializer in use: GSON allows to instantiate private, missing-no-args-constructor classes, while Jackson does not.

Type Parameters:

T - the type of that class.

Parameters:

type - Which class you want an object of.

Returns:

an "empty" new instance of the class.