io.mats3.serial.json

Class MatsSerializerJson

java.lang.Object

io.mats3.serial.json.MatsSerializerJson

All Implemented Interfaces:

MatsSerializer<java.lang.String>

public class MatsSerializerJson
extends java.lang.Object
implements MatsSerializer<java.lang.String>

Implementation of MatsSerializer that employs Jackson JSON library for serialization and deserialization, and compress and decompress using Deflater and Inflater.

The Jackson ObjectMapper is configured to only handle fields (think "data struct"), i.e. not use setters or getters; and to only include non-null fields; and upon deserialization to ignore properties from the JSON that has no field in the class to be deserialized into (both to enable the modification of DTOs on the client side by removing fields that aren't used in that client scenario, and to handle widening conversions for incoming DTOs), and to use string serialization for dates (and handle the JSR310 new dates):

 // Create Jackson ObjectMapper
 ObjectMapper mapper = new ObjectMapper();
 // Do not use setters and getters, thus only fields, and ignore visibility modifiers.
 mapper.setVisibility(PropertyAccessor.ALL, Visibility.NONE);
 mapper.setVisibility(PropertyAccessor.FIELD, Visibility.ANY);
 // Drop null fields (null fields in DTOs are dropped from serialization to JSON)
 mapper.setSerializationInclusion(Include.NON_NULL);
 // Do not fail on unknown fields (i.e. if DTO class to deserialize to lacks fields that are present in the JSON)
 mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
 // Handle the java.time classes sanely, i.e. as dates, not a bunch of integers.
 mapper.registerModule(new JavaTimeModule());
 // .. and write dates and times as Strings, e.g. 2020-11-15
 mapper.configure(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS, false);
 // Handle JDK8 Optionals as normal fields.
 mapper.registerModule(new Jdk8Module());
 

Nested Class Summary

Nested classes/interfaces inherited from interface io.mats3.serial.MatsSerializer

MatsSerializer.DeserializedMatsTrace<Z>, MatsSerializer.SerializationException, MatsSerializer.SerializedMatsTrace

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_COMPRESSION_LEVEL The default compression level - which I chose to be Deflater.BEST_SPEED (compression level 1), since I assume that the rather small incremental reduction in size does not outweigh the pretty large increase in time, as one hopefully runs on a pretty fast network (and that the MQ backing store is fast).
static java.lang.String	IDENTIFICATION

Fields inherited from interface io.mats3.serial.MatsSerializer

META_KEY_POSTFIX

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	MatsSerializerJson(int compressionLevel) Constructs a MatsSerializer, using the specified Compression Level - refer to Deflater's constants and levels.

Method Summary

Modifier and Type	Method and Description
protected void	adjustStreamReadConstraints(com.fasterxml.jackson.databind.ObjectMapper mapper)
protected byte[]	compress(byte[] data)
static MatsSerializerJson	create() Constructs a MatsSerializer, using the DEFAULT_COMPRESSION_LEVEL (which is Deflater.BEST_SPEED, which is 1).
static MatsSerializerJson	create(int compressionLevel) Constructs a MatsSerializer, using the specified Compression Level - refer to Deflater's constants and levels.
MatsTrace<java.lang.String>	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.
protected byte[]	decompress(byte[] data, int offset, int length, int bestGuessDecompressedSize)
MatsSerializer.DeserializedMatsTrace<java.lang.String>	deserializeMatsTrace(byte[] matsTraceBytes, int offset, int length, java.lang.String meta) Used for deserializing a byte array into a MatsTrace - this includes offset and length.
MatsSerializer.DeserializedMatsTrace<java.lang.String>	deserializeMatsTrace(byte[] matsTraceBytes, java.lang.String meta) Used for deserializing a byte array into a MatsTrace - this uses the entire byte array.
<T> T	deserializeObject(java.lang.String serialized, java.lang.Class<T> type) Used for deserializing type Z (typically String) to STOs and DTOs.
protected void	extraConfigureObjectMapper(com.fasterxml.jackson.databind.ObjectMapper mapper) Override if you want to change the Jackson ObjectMapper.
boolean	handlesMeta(java.lang.String meta) Whether this implementation of MatsSerializer handles the specified "meta".
<T> T	newInstance(java.lang.Class<T> clazz) Will return a new instance of the requested type.
MatsSerializer.SerializedMatsTrace	serializeMatsTrace(MatsTrace<java.lang.String> matsTrace) Used for serializing the MatsTrace to a byte array.
java.lang.String	serializeObject(java.lang.Object object) Used for serializing STOs and DTOs into type Z, typically String.
int	sizeOfSerialized(java.lang.String s)

Methods inherited from class java.lang.Object

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

Field Detail

IDENTIFICATION

public static java.lang.String IDENTIFICATION

DEFAULT_COMPRESSION_LEVEL

public static int DEFAULT_COMPRESSION_LEVEL

The default compression level - which I chose to be Deflater.BEST_SPEED (compression level 1), since I assume that the rather small incremental reduction in size does not outweigh the pretty large increase in time, as one hopefully runs on a pretty fast network (and that the MQ backing store is fast).

Constructor Detail

MatsSerializerJson

protected MatsSerializerJson(int compressionLevel)

Constructs a MatsSerializer, using the specified Compression Level - refer to Deflater's constants and levels.

Parameters:

compressionLevel - the compression level given to Deflater to use.

Method Detail

create

public static MatsSerializerJson create()

Constructs a MatsSerializer, using the DEFAULT_COMPRESSION_LEVEL (which is Deflater.BEST_SPEED, which is 1).

create

public static MatsSerializerJson create(int compressionLevel)

Constructs a MatsSerializer, using the specified Compression Level - refer to Deflater's constants and levels.

Parameters:

compressionLevel - the compression level given to Deflater to use.

adjustStreamReadConstraints

protected void adjustStreamReadConstraints(com.fasterxml.jackson.databind.ObjectMapper mapper)

extraConfigureObjectMapper

protected void extraConfigureObjectMapper(com.fasterxml.jackson.databind.ObjectMapper mapper)

Override if you want to change the Jackson ObjectMapper. Not really recommended.

handlesMeta

public boolean handlesMeta(java.lang.String meta)

Description copied from interface: MatsSerializer

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.

Specified by:

handlesMeta in interface MatsSerializer<java.lang.String>

createNewMatsTrace

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

Description copied from interface: MatsSerializer

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.

Specified by:

createNewMatsTrace in interface MatsSerializer<java.lang.String>

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

public MatsSerializer.SerializedMatsTrace serializeMatsTrace(MatsTrace<java.lang.String> matsTrace)

Description copied from interface: MatsSerializer

Used for serializing the MatsTrace to a byte array.

Specified by:

serializeMatsTrace in interface MatsSerializer<java.lang.String>

Parameters:

matsTrace - the MatsTrace instance to serialize.

Returns:

a byte array representation of the provided MatsTrace.

See Also:

MatsSerializer.META_KEY_POSTFIX

deserializeMatsTrace

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

Description copied from interface: MatsSerializer

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

Specified by:

deserializeMatsTrace in interface MatsSerializer<java.lang.String>

Parameters:

matsTraceBytes - 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:

MatsSerializer.META_KEY_POSTFIX

deserializeMatsTrace

public MatsSerializer.DeserializedMatsTrace<java.lang.String> deserializeMatsTrace(byte[] matsTraceBytes,
                                                                                   int offset,
                                                                                   int length,
                                                                                   java.lang.String meta)

Description copied from interface: MatsSerializer

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

Specified by:

deserializeMatsTrace in interface MatsSerializer<java.lang.String>

Parameters:

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

offset - from where to start in the byte array.

length - 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:

MatsSerializer.META_KEY_POSTFIX

serializeObject

public java.lang.String serializeObject(java.lang.Object object)

Description copied from interface: MatsSerializer

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

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

Specified by:

serializeObject in interface MatsSerializer<java.lang.String>

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

public int sizeOfSerialized(java.lang.String s)

Specified by:

sizeOfSerialized in interface MatsSerializer<java.lang.String>

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

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

Description copied from interface: MatsSerializer

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.

Specified by:

deserializeObject in interface MatsSerializer<java.lang.String>

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

public <T> T newInstance(java.lang.Class<T> clazz)

Description copied from interface: MatsSerializer

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.

Specified by:

newInstance in interface MatsSerializer<java.lang.String>

Type Parameters:

T - the type of that class.

Parameters:

clazz - Which class you want an object of.

Returns:

an "empty" new instance of the class.

compress

protected byte[] compress(byte[] data)

decompress

protected byte[] decompress(byte[] data,
                            int offset,
                            int length,
                            int bestGuessDecompressedSize)