Package com.diffusiondata.gateway.framework.converters

Payload Converters.

See: Description

Interface Summary

Interface	Description
PayloadConverter<I,O>	The base interface that a payload converter implements.

Package com.diffusiondata.gateway.framework.converters Description

Payload Converters.

A payload converter provides conversion or transformation of values. It takes an input value, performs required manipulation and returns an output value, which can be of same or different format.

Payload converters may be specified for services within the SourceHandler.SourceServiceProperties for source services or SinkHandler.SinkServiceProperties for sink services.

The payload converter specified in the source service should convert the input value into a Diffusion topic type. In this case, values from an external system are passed to a Publisher within a SourceHandler or HybridHandler and is converted into specific Diffusion topic type using the converter.

The payload converter specified in the sink service should convert the value from the Diffusion topic type. In this case, the converter converts values from a Diffusion data type to an external data type before passing values to a SinkHandler via its update method, or to a HybridHandler via its update method.

Payload converters for topic types

If a payload converter is not specified within the service property, a topic type must be specified in which case a default converter for the topic type will be used. Default conversions are shown in the tables below.

Default Conversions for Source service

Topic Type	Converter name	Description
BINARY	"$Object_to_BINARY"	If the value is an instance of Binary, it is returned as is. If the value is a byte[], it will be converted to a Binary object. The caller must not write further data to the array. All other types will throw a PayloadConversionException.
DOUBLE	"$Object_to_Double"	If the value is an instance of Double, it is returned as is. If the value is an instance of Number, the product of its doubleValue method is returned. If the value is null, null will be returned (leading to a null topic value}. For any other type the Double#parseDouble method is used on the toString value of the supplied value and if the string value cannot be parsed as a double, a PayloadConversionException will be thrown.
INT64	"$Object_to_Long"	If the value is an instance of Long, it is returned as is. If the value is an instance of Number, the product of its longValue method is returned. If the value is null, null will be returned (leading to a null topic value}. For any other type the parseLong method is used on the toString value of the supplied value and if the string value cannot be parsed as a long, a PayloadConversionException will be thrown.
JSON	"$Object_to_JSON"	If the value is an instance of JSON, it is returned as is. If a null value is passed, JSON containing "null" will be returned. Otherwise the input object will be converted to a JSON object. Supported types of input objects are basic POJOs, primitives, and collections such as Map and List. If the input value does not contain valid JSON, a PayloadConversionException is thrown.
STRING	"$Object_to_String"	If the value is null, null is returned (leading to a null topic value). If the value is a String it is returned as is. For any other type the product of its toString method is returned.

Default Conversions for Sink service

Topic Type	Converter name	Description
BINARY	"$BINARY_to_byte_array"	A byte[] representation of the topic's Binary value is returned. This is a byte[] view of the actual value and as such must not be modified.
JSON	"$JSON_to_String"	A String is returned which contains the string representation of the JSON object.

Apart from these converters for Diffusion topic types, there are other converters issued with the framework. See the user guide for more details

Writing a Payload Converter

A payload converter must implement PayloadConverter interface.

The input or output type of the converter can be anything that could also be the Diffusion topic type to which the service will be mapped.
The Diffusion com.pushtechnology.diffusion.datatype package (described within the Diffusion Client API) should be used for reading and writing Diffusion values.

Writing Configurable Payload Converters

An application user can configure payload converters to be used for a service. To enable configuration for a converter, it must be written in a specific way, as explained below.

1. The converter must be public.
2. A payload converter can be referred to in the configuration using its name. By default, the name of the converter is the simple name of the implemented class. This can be overridden by specifying a public static method called getName. The name should not start with a '$' character, as this character is reserved for converters provided by DiffusionData.
3. If a payload converter requires construction parameters, a public constructor must be declared that accepts a Map. The key and value of the map must be the name of a parameter and its value, respectively. The value can be of a primitive type, a list of primitives, or a map of primitives.

If converter configuration is specified in the service configuration or in the service properties of a ServiceHandler, the converter instance is instantiated by the framework. Converters that require construction parameters are instantiated by calling their constructor with user-configured parameters.

Payload converters are called in line when publishing or updating and so must operate synchronously. However, there is no reason why a converter should not call out to some external service to perform a conversion as long as it blocks awaiting the response.

Author:

DiffusionData Limited