Writing payload converters

Implementing the converter

If you need to convert data to or from an external system into a format that is not supported by the provided framework converters or if you require any custom data conversion, you will need to create a custom payload converter. The converter can then be used and specified in the service properties for a service handler.

The framework uses reflection to identify all implementations of PayloadConverters and to instantiate them. Hence, the following rules must be followed while writing payload converters:

A payload converter must implement the PayloadConverter interface.
A payload converter can implement a public static getName method to define the name by which it must be referred to in service properties. The name must not start with a $ character, as this is reserved for converters provided by DiffusionData.
```
NOTE: If this method is not implemented, the SimpleName of the class will be used as the name of the converter.
```
If the input type or output type of the converter is a Diffusion topic type, corresponding types should be used for the input or output type of the converter.

Diffusion Topic Type Input/Output Type

Diffusion Topic Type	Input/Output Type
JSON	`JSON`
STRING	`String`
INT64	`Long`
DOUBLE	`Double`
BINARY	`Binary`

JSON

JSON

STRING

String

INT64

Long

DOUBLE

Double

BINARY

Binary

If the converter requires any construction parameters, it should implement a constructor that accepts a Map of String to Object. The values of such construction parameters should be obtained from the map and validated as required.
If the construction parameters are not mandatory, and the instance can be created without any parameters, a public no-arg constructor should also be implemented.
The Diffusion Datypes instance can be used for reading and writing Diffusion values.
A payload converter may be called from many threads simultaneously and, therefore, should ideally be stateless or must otherwise be thread-safe.

public final class ScoreToJsonPayloadConverter
    implements PayloadConverter<String, JSON> {

    public static String getName() {
        return "Score_to_JSON";
    }

    @Override
    public JSON convert(Object value) {
        return Diffusion.dataTypes().json().fromJsonString("{ \"score\" : \"" + value + "\" }");
    }
}

Example: Non-configurable PayloadConverter implementation which takes a string value and creates a JSON object containing "score" property with the value

See Sample implementation of a payload converter, which converts JSON data to string representation of CSV data.

Payload converters are invoked by the framework while publishing to Diffusion, and as a result, they must operate synchronously. Nonetheless, there is no restriction preventing a converter from making calls to external services to perform conversions, provided that it blocks the process until a response is received.

Documenting the converter

Any implementation of a PayloadConverter in the application should be documented in the application user guide, specifying the following details:

Converter name
Configuration parameter requirements
For required configuration parameters, include details such as the parameter name, value type, and description.