3.4.2.8. RTI Routing Service

The following issues affect backward compatibility in Routing Service starting in Release 6.0.0.

3.4.2.8.1. Application Binary Interface

3.4.2.8.1.1. Service Library

The Routing Service Library does not provide ABI compatibility. Applications and libraries that linked against previous versions of this library are not guaranteed to work starting in 6.0.0. Applications and libraries that linked against this library will need to be recompiled. See Section 1.3.2.

3.4.2.8.1.2. Infrastructure Library

The Routing Service Infrastructure Library does not provide ABI compatibility. Applications and libraries (usually Adapters and Transformation plug-ins) that linked against previous versions of this library are not guaranteed to work in 6.0.0 and later. Applications and libraries that linked against this library will need to be recompiled. See Section 1.3.2.

3.4.2.8.2. APIs

3.4.2.8.2.1. Adapter API

The Routing Service Adapter C API has changed in 6.0.0, and existing implementations are required to be recompiled. These changes are minimal and should not affect the API interface. Therefore, existing Adapter implementation code should recompile with no additional changes.

3.4.2.8.2.2. Service API

The Routing Service Service C API has changed in 6.0.0, and existing applications that use this API are required to be recompiled. These changes are minimal and should not affect the API interface. Therefore, existing applications and libraries using the Service API should recompile with no additional changes.

3.4.2.8.3. Configuration

3.4.2.8.3.1. XSD compatibility

3.4.2.8.3.1.1. New <participant> and <connection> tags

Starting in 6.0.0, the Routing Service XSD definition no longer allows the use of tags <participant_1>, <participant_2>, <connection_1>, and <connection_2> that could appear within <domain_route>. Instead, these tags should be replaced with the <participant> and <connection> tags, which now receive a name.

For example the following legacy XML is no longer valid:

<domain_route>
    <participant_1>...</participant_1>
    <connection_2>...</connection_2>
</domain_route>

Instead, the equivalent and compatible XML code is shown as follows:

<domain_route>
    <participant name="1">...</participant>
    <connection name="2">...</connection>
</domain_route>

The command-line version of Routing Service incorporates an option to convert legacy XML configuration files to their equivalent compliant version. Look for the option -convertLegacyXml in the command-line help.

For example, the following command will convert an existing legacy file with name routerLegacy.xml and generate a new file with the name routerConverted.xml in the same directory:

[NDDSHOME]/bin/rtiroutingservice \
        -cfgFile routerLegacy.xml -convertLegacyXml routerConverted.xml

3.4.2.8.3.1.2. User-defined DTD entities no longer supported

As of 6.0.0, user-defined entities within a Routing Service configuration file are no longer processed, and Routing Service will generate a parsing error. For example, consider this XML configuration:

<!DOCTYPE routing_service[

   <!ENTITY enabled "true">
]>
<routing_service>
    <administration>
    <domain_id>0</domain_id>
    <distributed_logger>
        <enabled>&enabled;</enabled>
    </distributed_logger>
    </administration>
</routing_service>

This example will cause an XSD validation error because the Routing Service parser engine will not expand the DTD entity with its content.

Instead, you can use XML user variables in the form $(MY_VAR). For example, consider the configuration below:

<routing_service>
    <administration>
    <domain_id>0</domain_id>
    <distributed_logger>
        <enabled>$(ENABLED)</enabled>
    </distributed_logger>
    </administration>
</routing_service>

The value of the variable ENABLED can be provided through an environment variable of the same name, through the -DENABLED=<value> when running with the shipped Routing Service application, or through the ServiceProperty::user_environment when using the Routing Service API.

[RTI Issue ID ROUTING-660]

3.4.2.8.3.2. XML Validation

Routing Service incorporates builtin XSD validation of XML configuration files. Routing Service will fail to load non-compliant XML configuration files. You will need to update your XML configuration files (see Section 3.4.2.8.3.1) to be compliant with the new definitions.

Note

As a temporary workaround, you can disable XSD validation by using the option -ignoreXsdValidation in the command-line version of Routing Service or by setting enforce_xsd_validation to false in the library version of Routing Service. This workaround is not recommended and should be used only for testing purposes during the migration process.

3.4.2.8.4. Administration and Monitoring

3.4.2.8.4.1. New models

The Routing Service remote administration and monitoring interfaces (including DDS topics and command-syntax) have been redesigned in 6.0.0. They are no longer compatible with the interfaces from previous releases. Any applications that used the legacy interfaces to administer or monitor Routing Service will no longer communicate and will need to be updated to use the new interfaces. See Remote Administration in the Routing Service User’s Manual. See Monitoring in the Routing Service User’s Manual.

Note

RTI Administration Console has been updated to use the new administration and monitoring interfaces, so it will use the new DDS model and commands to communicate with Routing Service.

3.4.2.8.4.2. “Ignore” warnings

In 6.0.0, if WARNINGs are enabled, you may receive the following warning in Routing Service saying that you are ignoring a participant even though you are not ignoring it:

DISCParticipantDiscoveryPlugin_assertRemoteParticipant:remote entity ignored by user: 0X1017E82,0XD1817B1C,0X80642BE7,0X1C1

This warning is reported when the administration/monitoring participant uses the same domain ID as one of the Routing Service participants. In this case, the administration/monitoring participant will not communicate with the Routing Service participant.

This warning is intended (new) behavior in 6.0.0. You may see this warning if you are migrating to 6.0.0 using the same domain ID configuration as in 5.3.1. If you change the domain ID of the administration/monitoring participant, the warning will not occur and the participant will not be ignored.

3.4.2.8.5. QoS

Routing Service has not made any changes in 6.0.0 to the entities’ QoS with regards to previous versions. See Section 3.4.2.1.3 for QoS changes in the Core Libraries that may affect Routing Service.

3.4.2.8.6. Performance

In 6.0.0, for very small data sizes (between 1-64 bytes), Routing Service throughput is ~10% worse and latency is ~3% higher.

3.4.2.8.7. Library Size

A comparison of Routing Service libraries sizes for the architecture x64Linux3gcc4.8.2 is shown in Table 3.9.

Table 3.9 Library Size Comparison for x64Linux3gcc4.8.2 in MBs
	5.3.1	6.0.0	Change (%)
ritroutingsevice.so	3.9	6.35	+38.58
rtiroutingservicez.a	6.15	9.77	+37.05
rtirsinfrastructure.so	0.023	0.028	+17.8
rtirsinfrastructurez.a	0.025	0.028	+10.7

3.4.2.8.8. Documentation

In 6.0.0, the Routing Service Release Notes, Getting Started Guide, and User’s Manual have been consolidated into a single document, which is available in HTML and PDF formats. You can find them in your Connext installation in the following locations:

HTML main page: [NDDSHOME]/doc/manuals/routing_service/index.html
PDF: [NDDSHOME]/doc/manuals/routing_service/RTI_RoutingService_UsersManual.pdf