2. Configuration

This section describes how to configure Routing Service JSON Trasformation.

All configuration is specified in Routing Service’s XML configuration file.

2.1. Supported Data Types

Routing Service JSON Trasformation requires users to specify the name of a member that the transformation will either read as a JSON string (when parsing a DDS sample from JSON), or set the contents of using a JSON string (obtained by converting a DDS sample to JSON).

The type of this input/output members can be any of the following “string-like” types:

• string

• sequence<octet>

• sequence<char>

• octet[N]

• char[N]

When going from DDS to JSON, the transformation will always store a “well-terminated” string in the output member (i.e. a string which ends with a “nul” terminator, ‘0’).

When parsing DDS samples from JSON, the input string should be properly terminated, but it doesn’t need to be.

If the value retrieved from the input member does not already end with a 0, the transformation will add one, possibly by first allocating a sufficiently large buffer and then copying the original value into it. This reallocation is only performed for sequence members, and it will only be performed if the value does not already meet the maximum size defined for those members (if not unbounded).

2.2. Load the JSON Transformation Plugin

Routing Service JSON Trasformation must be registered as a Routing Service plugin by using the <transformation_plugin> tag.

The following snippet demonstrates how to register the plugin in the <plugin_library> section of Routing Service’s XML configuration:

<?xml version="1.0"?>
<dds>
    <plugin_library name="MyPlugins">
        <transformation_plugin name="JsonTransformation">
        <dll>rtijsontransf</dll>
        <create_function>
            RTI_TSFM_JsonTransformationPlugin_create
        </create_function>
    </transformation_plugin>
    </plugin_library>
</dds>

Warning

Routing Service must be able to find the Routing Service JSON Trasformation dynamic library (librtijsontransf.so on Linux® systems, librtijsontransf.dylib on macOS® systems, or rtijsontransf.dll on Windows® systems). Make sure to include the library’s directory in the library search path environment variable appropriate for your system (LD_LIBRARY_PATH on Linux systems, RTI_LD_LIBRARY_PATH on macOS systems, or PATH on Windows systems, etc.).

Once the dynamic library and constructor function have been registered, Routing Service will create an instance of the plugin during start-up.

2.2.1. Configuration Properties

The Routing Service JSON Trasformation uses the following properties to configure its behavior:

Table 2.1 JSON Transformation Configuration Properties

Property	Required	Default	Accepted Values	Description
buffer_member	YES	-	String	An identifier for a member of a type (e.g. ‘foo.bar’)
transform_type	YES	-	‘serialize’ or ‘deserialize’	‘serialize’ transforms the buffer from DDS to JSON ‘deserialize’ transforms the buffer from JSON to DDS.
indent	No	0	Integer >= 0	This represents the number of ‘tabs’ that are added to the JSON output. Each ‘tab’ is represented as 3 whitespaces. A value of 0 will replace the new line characters n by whitespaces.
unbounded_member_serialized_size_initial	No	255	Integer >= 0	This property represents the amount of bytes that are preallocated when using unbounded sequences and strings in the member identified by buffer_member.

For example, having the following type:

<types>
    <struct name="MessagePayload">
        <member name="data" type="byte" sequenceMaxLength="-1"/>
    </struct>
    <struct name="MyType">
        <member name="payload" type="nonBasic" nonBasicTypeName="MessagePayload"/>
    </struct>
</types>

We can configure the properties as follow:

<transformation plugin_name="MyPlugins::JsonTransformation">
    <input_type_name>MyType</input_type_name>
    <property>
        <value>
            <element>
                <name>transform_type</name>
                <value>deserialize</value>
            </element>
            <element>
                <name>buffer_member</name>
                <value>payload.data</value>
            </element>
        </value>
    </property>
</transformation>