4. Configuration

4.1. Configuring Routing Service

This document describes how to configure Routing Service. For installation instructions or to walk through some simple examples, please see the appropriate section.

When you start Routing Service, you can specify a configuration file in XML format. In that file, you can set properties that control the behavior of the service. This chapter describes how to write a configuration file.

4.2. Terms to Know

Before learning how to configure Routing Service, you should become familiar with a few key terms and concepts:

• An AutoRoute defines a set of potential Routes that can be instantiated based on deny/allow filters on the stream name and registered type name.
• A Transformation is a pluggable component that changes data from an input stream to an output stream.
• An Adapter is a pluggable component that allows Routing Service to consume and produce data for different data domains. By default, Routing Service is distributed with a builtin DDS adapter.

4.3. How to Load the XML Configuration

Routing Service loads its XML configuration from multiple locations. This section presents the various sources of configuration files, listed in load order.

• [working directory]/USER_ROUTING_SERVICE.xml This file is loaded automatically if it exists.
• [NDDSHOME]/resource/xml/RTI_ROUTING_SERVICE.xml This file is loaded automatically if it exists.
• One or more files (semicolon-separated) specified using the command-line parameter -cfgFile.

Note

[working directory] indicates the path to the current working directory from which you run Routing Service.

The tag [NDDSHOME] indicates the path to your Connext DDS installation.

You may use a combination of the above sources and load multiple configuration files.

Here is an example configuration file. You will learn the meaning of each line as you read the rest of this section.

<?xml version="1.0"?>
<dds>
    <routing_service name="TopicBridgeExample" group_name="MyGroup">
        <domain_route name="DomainRoute">
            <participant name="domain0">
               <domain_id>0</domain_id>
            </participant>

            <participant name="domain1">
               <domain_id>1</domain_id>
            </participant>

            <session name="Session">
                <topic_route name="SquaresToCircles">

                    <input participant="domain0">
                        <registered_type_name>
                            ShapeType
                        </registered_type_name>
                        <topic_name>Square</topic_name>
                    </input>

                    <output participant="domain1">
                        <registered_type_name>
                            ShapeType
                        </registered_type_name>
                        <topic_name>Circle</topic_name>
                    </output>

                </topic_route>
            </session>
        </domain_route>
    </routing_service>
</dds>

4.4. XML Syntax and Validation

The XML representation of DDS-related resources must follow these syntax rules:

• It shall be a well-formed XML document according to the criteria defined in clause 2.1 of the Extensible Markup Language standard.
• It shall use UTF-8 character encoding for XML elements and values.
• It shall use <dds> as the root tag of every document.

To validate the loaded configuration, Routing Service relies on an XSD file that describes the format of the XML content. We recommend including a reference to this document in the XML file that contains the service’s configuration; this provides helpful features in code editors such as Visual Studio®, Eclipse®, and NetBeans®, including validation and auto-completion while you are editing the XML file.

The XSD definitions of the XML elements are in [NDDSHOME]/resource/schema/rti_routing_service.xsd.

To include a reference to the XSD document in your XML file, use the attribute xsi:noNamespaceSchemaLocation in the <dds> tag. For example:

<?xml version="1.0" encoding="UTF-8"?>
<dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="[NDDSHOME]/resource/schema/rti_routing_service.xsd">
    <!-- ... -->
</dds>

Note

The tag [NDDSHOME] indicates the path to your Connext DDS installation.

4.5. XML Tags for Configuring RTI Routing Service

This section describes the XML tags you can use in a Routing Service configuration file. The following diagram and Table 4.1 describe the top-level tags allowed within the root <dds> tag.

Warning

The tables in this section may not necessarily reflect the order the Routing Service XSD requires. Use these tables as a documentation reference only.

Figure 4.1 Top-level Tags in the Configuration File

Table 4.1 Top-Level Tags in the Configuration File

Tags within <dds>	Description	Multiplicity
<qos_library>	Specifies a QoS library and profiles. The contents of this tag are specified in the same manner as for a Connext DDS application. See Configuring QoS with XML, in the Connext DDS Core Libraries User’s Manual.	0..*
<types>	Defines types that can be used by Routing Service. See Section 4.5.7.2.	0..1
<plugin_library>	Specifies a library of Routing Service plugins. Available plug-ins are Adapters, Transformations and Processors. See Section 4.5.9.	0..*
<routing_service>	Specifies a Routing Service configuration. See Section 4.5.1. Attributes name: Uniquely identifies a Routing Service configuration. Optional. enabled: A boolean that indicates whether this entity is auto-enabled when the service starts. If set to false, the entity can be enabled after the service starts through remote administration. Optional. Default: true. group_name: A name that can be used to implement a specific policy when the communication happens between Routing Service of the same group. For example, in the builtin DDS adapter, a DomainParticipant will ignore other DomainParticipants in the same group, as a way to avoid circular communication. Optional. Default: RTI_RoutingService_[Host Name]_ [Process ID] Example <routing_service name="ExampleService"> <!-- your service settings ... --> </routing_service>	1..*

4.5.1. Routing Service Tag

A configuration file must have at least one <routing_service> tag. This tag is used to configure an execution of Routing Service. A configuration file may contain multiple <routing_service> tags.

When you start Routing Service, you can specify which <routing_service> tag to use to configure the service using the -cfgName command-line parameter.

Because a configuration file may contain multiple <routing_service> tags, one file can be used to configure multiple Routing Service executions.

Figure 4.2 and Table 4.2 describes the tags allowed within a <routing_service> tag.

Figure 4.2 Routing Service Tag Structure

Table 4.2 Routing Service Tag

Tags within <routing_service>	Description	Multiplicity
<annotation>	Contains a <documentation> tag that can be used to provide a configuration description.	0..1
<administration>	Enables and configures remote administration. See Section 4.5.2 and Section 5.	0..1
<monitoring>	Enables and configures general remote monitoring. General monitoring settings are applicable to all the Routing Service entities unless they are explicitly overridden. See Section 4.5.3 and Section 6.	0..1
<entity_monitoring>	Enables and configures remote monitoring for the service entity. See Section 4.5.3.1 and Section 6.	0..1
<jvm>	Configures the Java JVM used to load and run Java adapters. For example: Example <jvm> <class_path> <element>SocketAdapter.jar</element> </class_path> <options> <element>-Xms32m</element> <element>-Xmx128m</element> </options> </jvm> You can use the <options> tag to specify options for the JVM, such as the initial and maximum Java heap sizes.	0..1
<domain_route>	Defines a mapping between two or more data domains. See Section 4.5.4. Attributes name: uniquely identifies a domain_route configuration. Optional. enabled: A boolean that indicates whether this entity is auto-enabled when the service starts. If set to false, the entity can be enabled after the service starts through remote administration. Optional. Default: true.	0..1

4.5.1.1. Example: Specifying a configuration in XML

<dds>
    <routing_service name="EmptyConfiguration"/>
    <routing_service name="ShapesDemoConfiguration">
    <!--...-->
    </routing_service>
</dds>

Starting Routing Service with the following command will use the <routing_service> tag with the name EmptyConfiguration.

$NDDSHOME/bin/rtiroutingservice \
        -cfgFile file.xml -cfgName EmptyConfiguration

4.5.2. Administration

You can create a Connext DDS application that can remotely control Routing Service. The <administration> tag is used to enable remote administration and configure its behavior. By default, remote administration is turned off in Routing Service for security reasons. A remote administration section is not required in the configuration file.

When remote administration is enabled, Routing Service will create a DomainParticipant, Publisher, Subscriber, DataWriter, and DataReader. These entities are used to receive commands and send responses. You can configure these entities with QoS tags within the <administration> tag. The following table lists the tags allowed within <administration> tag. Notice that the <domain_id> tag is required.

For more details, please see Section 5.

Note

The command-line options used to configure remote administration take precedence over the XML configuration (see Section 3).

Table 4.3 Administration Tag

Tags within <administration>	Description	Multiplicity
<enabled>	Enables/disables administration. Default: true	0..1
<domain_id>	Specifies which domain ID Routing Service will use to enable remote administration.	0..1
<participant_qos>	Configures the DomainParticipant QoS for remote administration. If the tag is not defined, Routing Service will use the Connext DDS defaults.	0..1
<publisher_qos>	Configures the Publisher QoS for remote administration. If the tag is not defined, Routing Service will use the Connext DDS defaults.	0..1
<subscriber_qos>	Configures the Subscriber QoS for remote administration. If the tag is not defined, Routing Service will use the Connext DDS defaults.	0..1
<datawriter_qos>	Configures the DataWriter QoS for remote administration. If the tag is not defined, Routing Service will use the Connext DDS defaults with the following changes: history.kind = DDS_KEEP_ALL_HISTORY_QOS resource_limits.max_samples = 32	0..1
<datareader_qos>	Configures the DataReader QoS for remote administration. If the tag is not defined, Routing Service will use the Connext DDS defaults with the following changes: reliability.kind = DDS_RELIABLE_RELIABILITY_QOS (this value cannot be changed) history.kind = DDS_KEEP_ALL_HISTORY_QOS resource_limits.max_samples = 32	0..1
<distributed_logger>	Configures RTI Distributed Logger. When you enable it, Routing Service will publish its log messages to Connext DDS. Example: <administration> ... <distributed_logger> <enabled>true</enabled> </distributed_logger> </administration>	0..1
<autosave_on_update>	A boolean that, if true, automatically triggers a save command when configuration updates are received. This value is sent as part of the monitoring configuration data for the Routing Service. Default: false.	0..1
<save_path>	Specifies the file that will contain the saved configuration. A <save_path> must be specified if you want to use the remote save command ((Section 5.2). If the specified file already exists, the file will be overwritten when save is executed. Default: [CURRENT DIRECTORY].	0..1

4.5.3. Monitoring

You can create a Connext DDS application that can remotely monitor the status of Routing Service. To enable remote monitoring and configure its behavior, use the <monitoring> and <entity_monitoring> tags.

By default, remote monitoring is turned off in Routing Service for security and performance reasons. A remote monitoring section is not required in the configuration file.

When remote monitoring is enabled, Routing Service will create one DomainParticipant, one Publisher, five DataWriters for data publication (one for each kind of entity), and five DataWriters for status publication (one for each kind of entity). You can configure the QoS of these entities with the <monitoring> tag defined under <routing_service>. The general remote monitoring parameters specified using the <monitoring> tag in <routing_service> can be overwritten on a per entity basis using the <entity_monitoring> tag.

For more details, please see Section 6.

Note

The command-line options used to configure remote monitoring take precedence over the XML configuration (See Section 3).

Table 4.4 Monitoring Tag

Tags within <monitoring>	Description	Multiplicity
<enabled>	Enables/disables general remote monitoring. Setting this value to true enables monitoring in all the entities unless they explicitly disable it by setting this tag to false in their local <entity_monitoring> tags. Setting this tag to false disables monitoring in all the entities. In this case, any monitoring configuration settings in the entities are ignored. Default: true	0..1
<domain_id>	Specifies which domain ID Routing Service will use to enable remote monitoring.	0..1
<ignore_initialization_failure>	Indicates whether a failure initializing the monitoring engine for the service or any of the underlying entities is ignored.|br| If false, a failure initializing monitoring will result in a failure creating the service or the affected entities. Default: false	0..1
<participant_qos>	Configures the DomainParticipant QoS for remote monitoring. If the tag is not defined, Routing Service will use the Connext DDS defaults, with the following change: resource_limits.type_code_max_serialized_length = 4096	0..1
<publisher_qos>	Configures the Publisher QoS for remote monitoring. If the tag is not defined, Routing Service will use the Connext DDS defaults.	0..1
<datawriter_qos>	Configures the DataWriter QoS for remote monitoring. If the tag is not defined, Routing Service will use the Connext DDS defaults with the following change: durability.kind = DDS_TRANSIENT_LOCAL_DURABILITY_QOS	0..1
<statistics_sampling_period>	Specifies the frequency, in seconds, at which status statistics are gathered. Statistical variables such as latency are part of the entity status. Example: <statistics_sampling_period> <sec>1</sec> <nanosec>0</nanosec> </statistics_sampling_period> The statistics period for a given entity should be smaller than the publication period. The statistics sampling period defined in <routing_service> is inherited by all the entities. An entity can overwrite the period. Default: 1	0..1
<statistics_publication_period>	Specifies the frequency, in seconds, at which the status of an entity is published. Example: <statistics_publication_period> <sec>5</sec> <nanosec>0</nanosec> </statistics_publication_period> The statistics sampling period defined in <routing_service> is inherited by all the entities. An entity can overwrite the period. Default: 5	0..1

4.5.3.1. Monitoring Configuration Inheritance

The monitoring configuration defined in <routing_service> is inherited by all the entities defined inside the tag.

An entity can overwrite three elements of the monitoring configuration:

• The status publication period
• The statistics sampling period
• The historical statistics windows

Each one of these three elements is inherited and can be overwritten independently using the <entity_monitoring> tag.

Table 4.5 Entity Monitoring Tag

Tags within <entity_monitoring>	Description	Multiplicity
<enabled>	Enables/disables remote monitoring for a given entity. If general monitoring is disabled, this value is ignored. Default: true	0..1
<statistics_sampling_period>	Specifies the frequency at which status statistics are gathered. Statistical variables such as latency are part of the entity status. Example: <statistics_sampling_period> <sec>1</sec> <nanosec>0</nanosec> </statistics_sampling_period> The statistics period for a given entity should be smaller than the publication period. If this tag is not defined, historical statistics are inherited from the general monitoring settings. Default: 1 second.	0..1
<statistics_publication_period>	Specifies the frequency at which the status of an entity is published. Example: <statistics_publication_period> <sec>5</sec> <nanosec>0</nanosec> </statistics_publication_period> If this tag is not defined, historical statistics are inherited from the general monitoring settings. Default: 5 seconds.	0..1

4.5.3.1.1. Example: Overriding Publication Period

<routing_service name="MonitoringExample">
    <monitoring>
        <domain_id>55</domain_id>
        <status_publication_period>
            <sec>1</sec>
        </status_publication_period>
        <statistics_sampling_period>
            <sec>1</sec>
            <nanosec>0</nanosec>
        </statistics_sampling_period>
    </monitoring>
    ...
    <domain_route>
        <entity_monitoring>
            <status_publication_period>
                <sec>4</sec>
            </status_publication_period>
        </entity_monitoring>
        ...
    </domain_route>
</routing_service>

4.5.4. Domain Route

A <domain_route> defines a mapping between different data domains. Data available in any of these data domains can be routed to other data domains. For example, a DomainRoute could define a mapping among multiple DDS domains, or between a DDS domain and a MQTT provider’s network. How this data is actually read and written is defined in specific Routes.

A <domain_route> creates one or more Connections. Each Connection typically belongs to a different data domain. The <connection> tag requires the specification of the attribute name, which will be used by the Route to select input and output domains, and the plugin_name, which will be used to associate a Connection with an adapter plugin defined within <adapter_library>.

Routing Service comes with a builtin implementation of a DDS adapter, which can be used by specifying the <participant> tag. Each tag corresponds to exactly one DomainParticipant. A DomainRoute can include both <connection> and <participant> tags to provide communication between DDS domains and other data domains.

Table 4.6 Domain Route Tag

Tags within <domain_route>	Description	Multiplicity
<entity_monitoring>	Enables and configures remote monitoring for the DomainRoute. See Section 6.	0..1
<connection>	Applicable to non-DDS domains. Configures a custom, adapter-based connection. Attributes name: Uniquely identifies a service configuration. Required. plugin_name: Name of the plug-in that creates an adapter object. This name shall refer to an adapter plug-in registered either in a <plugin_library> or with the service’s attach_adapter_plugin() operation. Required. See Table 4.7.	0..*
<participant>	Applicable to DDS domains. Configures a DDS adapter DomainParticipant. See Table 4.8.	0..*
<session>	Defines a multi-threaded context in which data is routed according to specified routes. See Section 4.5.5. Attributes name: uniquely identifies the Session configuration. Optional. enabled: A boolean that indicates whether this entity is auto-enabled when the service starts. If set to false, the entity can be enabled after the service starts through remote administration. Optional. Default: true.	0..*

Table 4.7 Connection Tag

Tags within <connection>	Description	Multiplicity
<property>	A sequence of name-value string pairs that allows you to configure the Connection instance. Example: <property> <value> <element> <name>jms.connection.username</name> <value>myusername</value> </element> </value> </property>	0..1
<registered_type>	Registers a type name and associates it with a type representation. When you define a type in the configuration file, you have to register the type in order to use it in Routes. See Section 4.5.6.	0..*

Table 4.8 Participant Tag

Tags within <participant>	Description	Multiplicity
<domain_id>	Sets the domain ID associated with the DomainParticipant. Default: 0	0..1
<participant_qos>	Sets the participant QoS. The contents of this tag are specified in the same manner as a Connext DDS QoS profile. If not specified, the DDS defaults are used, except for the participant name which takes the following value: “RTI Routing Service: <service name>.<domain route name>#[1|2]” (for example “RTI Routing Service: MyService.MyDomainRoute#1”). Note Changing the default participant name may prevent Routing Service from being detected by Admin Console. You can use a <participant_qos> tag inside a <qos_library>/<qos_profile> previously defined in your configuration file by referring to it, and also override any value: Example: <participant_qos base_name="MyLibrary::MyProfile"> <discovery> <initial_peers> <element>udpv4://192.168.1..12</element> <element>shmem://</element> </initial_peers> </discovery> </participant_qos> See Configuring QoS with XML, in the Connext DDS Core Libraries User’s Manual.	0..1
<memory_management>	Configures certain aspects of how Connext DDS allocates internal memory. The configuration is per DomainParticipant and therefore affects all the contained DDS entities. Example: <memory_management> <sample_buffer_min_size> 1024 </sample_buffer_min_size> <sample_buffer_trim_to_size> true </sample_buffer_trim_to_size> </memory_management> This tag includes the following tags: sample_buffer_min_size: For all DataReaders and DataWriters, the way Connext DDS allocates memory for samples is as follows: Connext DDS pre-allocates space for samples up to size X in the DataReader and DataWriter queues. If a sample has an actual size greater than X, the memory is allocated dynamically for that sample. The default size is 64KB. This is the maximum amount of pre-allocated memory. Dynamic memory allocation may occur when necessary if samples require a bigger size. sample_buffer_trim_to_size: If set to true, after allocating dynamic memory for very large samples, that memory will be released when possible. If false, that memory will not be released but kept for future samples if needed. The default is false. This feature is useful when a data type has a very high maximum size (e.g., megabytes) but most of the samples sent are much smaller than the maximum possible size (e.g., kilobytes). In this case, the memory footprint is reduced dramatically, while still correctly handling the rare cases in which very large samples are published.	0..1
<registered_type>	Registers a type name and associates it with a type representation. When you define a type in the configuration file, you have to register the type in order to use it in Routes. See Section 4.5.6.	0..*

4.5.4.1. Example: Mapping between Two DDS Domains

<domain_route name="DdsDomainRoute">
    <participant name="domain54">
        <domain_id>54</domain_id>
        ...
    </participant>

    <articipant name="domain55">
        <domain_id>55</domain_id>
        ...
    </participant>

    ...
</domain_route>

4.5.4.2. Example: Mapping between a DDS Domain and raw Sockets

<domain_route name="DomainRoute">
    <connection name="SocketAdapter">
        ...
    </connection>

    <participant name="domain55">
        <domain_id>55</domain_id>
        ...
    </participant>

    ...
</domain_route>

4.5.5. Session

A <session> tag defines a multi-threaded context for route processing, including data forwarding. The data is routed according to specified Routes and AutoRoutes.

Each Session will have an associated thread pool to process Routes concurrently, preserving Route safety. Multiple Routes can be processed concurrently, but a single Route can be processed only by one thread at time. By default, the session thread pool has a single thread, which serializes the processing of all the Routes.

Sessions that bridge domains will create a Publisher and a Subscriber from the DomainParticipants associated with the domains. Table 4.9 lists the tags allowed within a <session> tag.

Table 4.9 Session Tag

Tags within <session>	Description	Multiplicity
<entity_monitoring>	Enables and configures remote monitoring for the Session. See Section 6.	0..1
<thread_pool>	Defines the number of threads to process Routes and sets the mask, priority, and stack size of each thread. Example: <thread_pool> <mask>MASK_DEFAULT</mask> <priority>THREAD_PRIORITY_DEFAULT</priority> <stack_size> THREAD_STACK_SIZE_DEFAULT </stack_size> </thread_pool> Default values: size: 1 mask: MASK_DEFAULT priority: THREAD_PRIORITY_DEFAULT stack_size: THREAD_STACK_SIZE_DEFAULT	0..1
<periodic_action>	Specifies a period at which Processors will receive notifications of the periodic event. The Session will wake up and notify the installed Processor every specified period. Default: INFINITE (no periodic notification) Example: <periodic_action> <sec>1</sec> <nanosec>0</nanosec> </periodic_action> The example above indicates the installed Processor should be notified every one second.	0..1
<property>	A sequence of name-value string pairs that allows you to configure the Session instance. Example: <property> <value> <element> <name>com.rti.socket.timeout</name> <value>1</value> </element> </value> </property> These properties are only used in non-DDS domains.	0..1
<subscriber_qos>	Only applicable to Routes that are Connext DDS Routes. Sets the QoS associated with the session Subscribers. There is one Subscriber per DomainParticipant. The contents of this tag are specified in the same manner as a Connext DDS QoS profile. See Configuring QoS with XML, in the Connext DDS Core Libraries User’s Manual. If the tag is not defined, Routing Service will use the Connext DDS defaults.	0..1
<publisher_qos>	Only applicable to Routes that are Connext DDS Routes. Sets the QoS associated with the session Publishers. There is one Publisher per DomainParticipant. The contents of this tag are specified in the same manner as a Connext DDS QoS profile. See Configuring QoS with XML, in the Connext DDS Core Libraries User’s Manual. If the tag is not defined, Routing Service will use the Connext DDS defaults.	0..*
<topic_route> or <route>	Defines a mapping between multiple input and output streams. Attributes name: uniquely identifies a TopicRoute or Route configuration. Optional. enabled: A boolean that indicates whether this entity is auto-enabled when the service starts. If set to false, the entity can be enabled after the service starts through remote administration. Optional. Default: true. See Section 4.5.6.	0..*
<auto_topic_route> or <auto_route>	Defines a factory for Route based on type and stream filters. See Section 4.5.8. Attributes name: uniquely identifies an AutoTopicRoute or AutoRoute configuration. Optional. enabled: A boolean that indicates whether this entity is auto-enabled when the service starts. If set to false, the entity can be enabled after the service starts through remote administration. Optional. Default: true.	0..*

4.5.6. Route

A Route explicitly defines a mapping between one or more input data streams and one or more output data streams. The input and output streams may belong to different data domains.

Route events are processed in the context of the thread belonging to the parent Session. Route event processing includes, among others, calls to the StreamReader read and StreamWriter write operations.

Table 4.10 lists the tags allowed within a <route>. Table 4.11 lists the tags allowed within a <topic_route>.

Table 4.10 Route Tag

Tags within <route>	Description	Multiplicity
<entity_monitoring>	Enables and configures remote monitoring for the Route. See Section 6.	0..1
<route_types>	Defines if the input connection will use types discovered in the output connection and vice versa for the creation of StreamWriters and StreamReaders in the Route. See Section 4.5.7.2.2. Default: false	0..1
<publish_with_original_timestamp>	When this tag is true, the data samples read from the input stream are written into the output stream with the same timestamp that was associated with them when they were made available in the input domain. This option may not be applicable in some adapter implementations in which the concept of timestamp is unsupported. Default: false	0..1
<processor>	Sets a custom Processor for handling the data forwarding process. See Section 7. Attributes plugin_name: Name of the plug-in that creates a Processor object. This name shall refer to a processor plug-in registered either in a <plugin_library> or with the service attach_processor() operation.	0..1
<dds_input>	Only applicable to DDS inputs. Defines an input topic. See Section 4.5.7. Attributes name: uniquely identifies an input configuration. Optional.	0..*
<dds_output>	Only applicable to DDS outputs. Defines an output topic. See Section 4.5.7. Attributes name: uniquely identifies an output configuration. Optional.	0..*
<input>	Only applicable to non-DDS inputs. Defines an input stream. See Section 4.5.7. Attributes name: uniquely identifies an input configuration. Optional.	0..*
<output>	Only applicable to non-DDS outputs. Defines an output stream. See Section 4.5.7. Attributes name: uniquely identifies an output configuration. Optional.	0..*

Table 4.11 Topic Route Tag

Tags within <topic_route>	Description	Multiplicity
<entity_monitoring>	Enables and configures remote monitoring for the TopicRoute. See Section 6.	0..1
<route_types>	Defines if the input connection will use types discovered in the output connection and vice versa for the creation of DataReaders and DataWriters in the Route. See Section 4.5.7.2.2. Default: false	0..1
<publish_with_original_info>	Writes the data sample as if they came from its original writer. Setting this option to true allows having redundant routing services and prevents the applications from receiving duplicate samples. Default: false	0..1
<publish_with_original_timestamp>	Indicates if the data samples are written with their original source timestamp. Default: false	0..1
<propagate_dispose>	Indicates whether or not disposed samples (NOT_ALIVE_DISPOSE) must be propagated by the TopicRoute. This action may be overwritten by the execution of a transformation. Default: true	0..1
<propagate_unregister>	Indicates whether or not disposed samples (NOT_ALIVE_NO_WRITERS) must be propagated by the TopicRoute. This action may be overwritten by the execution of a transformation. Default: true	0..1
<topic_query_proxy>	Configures the forwarding of TopicQueries. See Section 9 for detailed information on how Routing Service processes TopicQueries. The snippet below shows that topic query proxy is enabled in propagation mode, which causes the creation of a TopicQuery on the route’s input for each TopicQuery that an output’s matching DataReader creates. Example: <topic_query_proxy> <enabled>true</enabled> <mode>PROPAGATION</mode> </topic_query_proxy>	0..1
<filter_propagation>	Configures the propagation of content filters. Specifies whether the feature is enabled and when events are processed (Section 8). Filter propagation events can be batched to reduce the traffic in detriment of increasing the delay in propagating the composed filter. Event batching can be configured with the following tags: <max_event_count>: Indicates the minimum number of filter indication events required before propagating the composed filter. <max_event_delay>: Indicates the minimum amount of time to wait before propagating the composed filter. The previous two tags can be set in combination. In this case, the composed filter is propagated whenever one of these conditions is met first. The snippet below shows that filter propagation is enabled, and a filter update is propagated on the StreamReader only after the occurrence of every three filter events (see Section 8). Example: <filter_propagation> <enabled>true</enabled> <max_event_count>3</max_event_count> <max_event_delay> <sec>DURATION_INFINITE_SEC</sec> <nanosec>DURATION_INFINITE_NSEC</nanosec> </max_event_delay> </filter_propagation>	0..1
<processor>	Sets a custom Processor for handling the data forwarding process. See Section 7. Attributes plugin_name: Name of the plug-in that creates a Processor object. This name shall refer to a processor plug-in registered either in a <plugin_library> or with the service attach_processor() operation.	0..1
<input>	Defines an input topic. See Section 4.5.7. Attributes name: uniquely identifies an input configuration. Optional.	0..*
<output>	Defines an output topic. See Section 4.5.7. Attributes name: uniquely identifies an output configuration. Optional.	0..*

4.5.7. Input/Output

Inputs and outputs in a Route or TopicRoute have an associated StreamReader and StreamWriter, respectively. For DDS domains, the StreamReader will contain a DataReader and the StreamWriter will contain a DataWriter. The DataReaders and DataWriters belong to the corresponding Session Subscriber and Publisher.

DDS inputs and outputs within a Route are defined using the <dds_input> and <dds_output> tags. Inputs and outputs from other data domains are defined using the <input> and <output> tags. A TopicRoute is a special kind of Route that allows defining mapping between DDS topics only.

Table 4.12 Route Input/Output Tags

Tags within <input> and <output> of <route>	Description	Multiplicity
<entity_monitoring>	Enables and configures remote monitoring for the Input/Output. See Section 6.	0..1
<stream_name>	Specifies the stream name.	1
<registered_type_name>	Specifies the registered type name of the stream.	1
<creation_mode>	Specifies when to create the StreamReader/StreamWriter. Default: IMMEDIATE See Section 4.5.7.1.	0..1
<property>	A sequence of name-value string pairs that allows you to configure the StreamReader/StreamWriter. Example: <property> <value> <element> <name>com.rti.socket.port</name> <value>16556</value> </element> </value> </property>	0..1
<transformation> (within <output> only)	Sets a data transformation to be applied for every data sample. See Section 4.5.7.3. Attributes plugin_name: Name of the plug-in that creates a Transformation object. This name shall refer to a transformation plug-in registered either in a <plugin_library> or with the service attach_transformation() operation.	0..1

Table 4.13 TopicRoute Input/Output Tags

Tags within <input> and <output> (in <topic_route>) and <dds_input> and <dds_output> (in <route>)	Description	Multiplicity
<topic_name>	Specifies the topic name.	1
<registered_type_name>	Specifies the registered type name of the topic.	1
<creation_mode>	Specifies when to create the StreamReader/StreamWriter. Default: IMMEDIATE See Section 4.5.7.1.	0..1
<datareader_qos> or <datawriter_qos>	Sets the DataReader or DataWriter QoS. The contents of this tag are specified in the same manner as a Connext DDS QoS profile. See Configuring QoS with XML, in the Connext DDS Core Libraries User’s Manual. If the tag is not defined, Routing Service will use the Connext DDS defaults.	0..1
<content_filter>	Defines a SQL content filter for the DataReader. Example: <content_filter> <expression> x &gt; 100 </expression> </content_filter>	0..1
<transformation>` (within <output> only)	Sets a data transformation to be applied for every data sample. See Section 4.5.7.3. Attributes plugin_name: Name of the plug-in that creates a Transformation object. This name shall refer to a transformation plug-in registered either in a <plugin_library> or with the service attach_transformation() operation.	0..1

4.5.7.1. Creation Modes

The way a Route creates its StreamReaders and StreamWriters and starts reading and writing data can be configured.

The <creation_mode> tag in a Route’s <input> and <output> tags controls when StreamReaders/StreamWriters are created.

Table 4.14 Route Creation Mode

<creation_mode> values	Description
IMMEDIATE	The StreamReader/StreamWriter is created as soon as possible; that is, as soon as the types are available. Note that if the type is defined in the configuration file, the creation will occur when the service starts.
ON_DOMAIN_MATCH	The StreamReader is not created until the associated connection discovers a data Producer on the same stream. If the adapter supports partition, the discovered Producer must also belong to the same partition for a match to occur. For example, a DDS input will not create a DataReader until a DataWriter for the same topic and partition is discovered on the same domain. The StreamWriter is not created until the associated connection discovers a data Consumer on the same stream. If the adapter supports partition, the discovered Producer must also belong to the same partition for a match to occur. For example, a DDS output will not create a DataWriter until a DataReader for the same topic and partition is discovered on the same domain.
ON_ROUTE_MATCH	The StreamReader/StreamWriter is not created until all its counterparts in the Route are created.
ON_DOMAIN_AND_ROUTE_MATCH	Both conditions must be true.
ON_DOMAIN_OR_ROUTE_MATCH	At least one of the conditions must be true.

The same rules also apply to the StreamReader/StreamWriter destruction. When the condition that triggered the creation of that entity becomes false, the entity is destroyed. Note that IMMEDIATE will never become false.

For example, if the creation mode of an <input> tag is ON_DOMAIN_MATCH, when all the matching user DataWriters in the input domain are deleted, the input DataReader is deleted.

4.5.7.1.1. Example: Route Starts as Soon as a User DataWriter is Publishing on 1st Domain

<topic_route>
    <input participant="domain1">
        <creation_mode>ON_DOMAIN_MATCH</creation_mode>
        ...
    </input>
    <output participant="domain2">
        <creation_mode>ON_ROUTE_MATCH</creation_mode>
    ...
    </output>
</topic_route>

4.5.7.1.2. Example: Route Starts when Both User DataWriter Appears in 1st Domain and User DataReader Appears in 2nd Domain

<topic_route>
    <input participant="domain1">
        <creation_mode>ON_DOMAIN_AND_ROUTE_MATCH</creation_mode>
        ...
    </input>
    <output participant="domain2">
        <creation_mode>ON_DOMAIN_AND_ROUTE_MATCH</creation_mode>
    ...
    </output>
</topic_route>

4.5.7.2. Specifying Types

The tag <registered_type_name> within the <input> and <output> tags contains the registered type name of the stream. The actual definition of that type can be set in the configuration file or it can be discovered by the Connections.

See Section 2.1.4.3 for more details about type registration.

4.5.7.2.1. Defining Types in the Configuration File

To define and use a type in your XML configuration file:

• Define your type within the <types> tag. The type description is done using the Connext DDS XML format for type definitions. See Creating User Data Types with Extensible Markup Language (XML), in the RTI Connext DDS Core Libraries User’s Manual.
• Register it in the <connection>/<participant> where you will use it.
• Refer to it in the domain route(s) that will use it.

4.5.7.2.1.1. Example: Type Registration in XML

<dds>
    ...
    <types>
        <struct name="PointType">
        ...
        </struct>
    </types>
    ...
    <routing_service name=”MyRoutingService”>
        ...
        <domain_route>
            <connection name="MyConnection">
                ...
                <registered_type name="Position" type_name="PointType"/>
            </connection>
            <participant name="MyParticipant">
                ...
                <registered_type name="Position" type_name="PointType"/>
            </participant>
            ...
            <session>
                <topic_route>
                    <input participant="2">
                        <registered_type_name>Position</registered_type_name>
                    </input>
                    ...
                </topic_route>
            </session>
            ...
        </domain_route>
        ...
    </routing_service>
    ...
<dds>

4.5.7.2.2. Discovering Types

If the registered type name is not defined in the configuration file, Routing Service has to discover its type representation (e.g. typecode). An Input or an Output cannot be enabled if the type has not been registered yet within the referenced Connection.

By default, the StreamReader creation will be tied to the discovery of types in the input domain and the StreamWriter creation will be tied to the discovery of types in the output domain. If you want to use types discovered in either one of the domains for the creation of both the StreamReader and StreamWriter, you must set the <route_types> tag to true.

4.5.7.2.2.1. Example: Route Creation with Type Obtained from Discovery

<dds>
    ...
    <routing_service name=”MyRoutingService”>
        ...
        <domain_route>
            <participant name="MyParticipant"/>
            ...
            <session>
                <topic_route>
                    <input participant="domain1">
                        <registered_type_name>Position</registered_type_name>
                    </input>
                    ...
                </topic_route>
            </session>
            ...
        </domain_route>
        ...
    </routing_service>
    ...
<dds>

4.5.7.3. Data Transformation

An Output can transform the incoming data using a Transformation. To instantiate a Transformation:

1. Implement the transformation plugin API and register in a plug-in library, or attach it to a service instance if you are using the Service API. See Section 7.
2. Instantiate a Transformation object by specifying a <transformation> tag inside a <output> or <dds_output>.

Table 4.15 lists the tags allowed within a <transformation> tag.

Table 4.15 Transformation Tag

Tags within <transformation>	Description	Multiplicity
<property>	A sequence of name-value string pairs that allows you to configure the custom Transformation plug-in object. Example: <property> <value> <element> <name>X</name> <value>Y</value> </element> <element> <name>Y</name> <value>X</value> </element> </value> </property>	0..1

4.5.8. Auto Route

The tag <auto_route> defines a set of potential Routes, with single input and output, both with the same registered type and stream name. A Route can eventually be instantiated when a new stream is discovered with a type name and a stream name that match the filters in the AutoRoute. When this happens, a Route is created with the configuration defined by the AutoRoute.

The generated Route has a name constructed as follows:

[auto_route_name]@[stream_name]

where [auto_route_name] represents the name of the AutoRoute and [stream_name] the name of the matching stream.

DDS inputs and outputs within an AutoRoute are defined using the XML tags <dds_input> and <dds_output>. Input and outputs from other data domains are defined using the tags <input> and <output>.

An AutoTopicRoute is a special kind of AutoRoute that defines a mapping between two DDS domains.

See the following tables for more information on allowable tags:

• Table 4.16 lists the tags allowed within a <auto_route>.
• Table 4.17 lists the tags allowed within a <auto_topic_route>.

Table 4.16 AutoRoute Tag

Tags within <auto_route>	Description	Multiplicity
<entity_monitoring>	Enables and configures remote monitoring for the AutoRoute. See Section 6.	0..1
<publish_with_original_timestamp>	When this tag is true, the data samples read from the input stream are written into the output stream with the same timestamp that was associated with them when they were made available in the input domain. This option may not be applicable in some adapter implementations in which the concept of timestamp is unsupported. Default: false	0..1
<processor>	Sets a custom Processor for handling the data forwarding process. See Section 7. Attributes plugin_name: Name of the plug-in that creates a Processor object. This name shall refer to a processor plug-in registered either in a <plugin_library> or with the service attach_processor() operation.	0..1
<dds_input>	Only applicable to DDS inputs. Defines an input topic.	0..1
<dds_output>	Only applicable to DDS outputs. Defines an output topic.	0..1
<input>	Only applicable to non-DDS inputs. Defines an input stream.	0..1
<output>	Only applicable to non-DDS outputs. Defines an output stream.	0..1

Table 4.17 AutoTopicRoute Tag

Tags within <auto_topic_route>	Description	Multiplicity
<entity_monitoring>	Enables and configures remote monitoring for the AutoTopicRoute. See Section 6.	0..1
<publish_with_original_info>	Writes the data sample as if they came from its original writer. Setting this option to true allows having redundant routing services and prevents the applications from receiving duplicate samples. Default: false	0..1
<publish_with_original_timestamp>	Indicates if the data samples are written with their original source timestamp. Default: false	0..1
<propagate_dispose>	Indicates whether or not disposed samples (NOT_ALIVE_DISPOSE) must be propagated by the TopicRoute. This action may be overwritten by the execution of a transformation. Default: true	0..1
<propagate_unregister>	Indicates whether or not disposed samples (NOT_ALIVE_NO_WRITERS) must be propagated by the TopicRoute. This action may be overwritten by the execution of a transformation. Default: true	0..1
<topic_query_proxy>	Configures the forwarding of TopicQueries. See Section 9 for detailed information on how Routing Service processes TopicQueries. The snippet below shows that topic query proxy is enabled in propagation mode, which causes the creation of a TopicQuery on the route’s input for each TopicQuery that an output’s matching DataReader creates. Example: <topic_query_proxy> <enabled>true</enabled> <mode>PROPAGATION</mode> </topic_query_proxy>	0..1
<filter_propagation>	Configures the propagation of content filters. Specifies whether the feature is enabled and when events are processed. The snippet below shows that filter propagation is enabled, and a filter update is propagated on the StreamReader only after the occurrence of every three filter events (see Section 8). Example: <filter_propagation> <enabled>true</enabled> <max_event_count>3</max_event_count> <max_event_delay> <sec>DDS_DURATION_INFINITE_SEC</sec> <nanosec>DDS_DURATION_INFINITE_NSEC</nanosec> </max_event_delay> </filter_propagation>	0..1
<processor>	Sets a custom Processor for handling the data forwarding process. See Section 7. Attributes plugin_name: Name of the plug-in that creates a Processor object. This name shall refer to a processor plug-in registered either in a <plugin_library> or with the service attach_processor() operation.	0..1
<input>	Defines an input topic.	0..1
<output>	Defines an output topic.	0..1

Table 4.18 AutoRoute Input/Output Tags

Tags within <input> and <output> of <auto_route>	Description	Multiplicity
<entity_monitoring>	Enables and configures remote monitoring for the Input/Output. See Section 6.	0..1
<allow_stream_name_filter>	A stream name filter. You may use a comma-separated list to specify more than one filter. Default: * (allow all)	0..1
<allow_registered_type_name_filter>	A registered type name filter. You may use a comma-separated list to specify more than one filter. Default: * (allow all)	0..1
<deny_stream_name_filter>	A stream name filter that should be denied (excluded). This is applied after the <allow_stream_name_filter>. Default: empty (not applied)	1
<deny_registered_type_filter>	A registered type name filter that should be denied (excluded). This is applied after the <allow_registered_type_name_filter>. Default: empty (not applied)	0..1
<creation_mode>	Specifies when to create the StreamReader/StreamWriter. Default: IMMEDIATE See Section 4.5.7.1.	0..1
<property>	A sequence of name-value string pairs that allows you to configure the StreamReader/StreamWriter. Example: <property> <value> <element> <name>com.rti.socket.port</name> <value>16556</value> </element> </value> </property>	0..1

Table 4.19 AutoTopicRoute Input/Output Tags

Tags within <input> and <output> (in <auto_topic_route>) <dds_input> and <dds_output> (in <auto_route>)	Description	Multiplicity
<entity_monitoring>	Enables and configures remote monitoring for the Input/Output. See Section 6.	0..1
<allow_topic_name_filter>	A Topic name filter. You may use a comma-separated list to specify more than one filter. Default: * (allow all)	0..1
<allow_registered_type_name_filter>	A registered type name filter. You may use a comma-separated list to specify more than one filter. Default: * (allow all)	0..1
<deny_topic_name_filter>	A Topic name filter that should be denied (excluded). This is applied after the <allow_stream_name_filter>. Default: empty (not applied)	1
<deny_registered_type_filter>	A registered type name filter that should be denied (excluded). This is applied after the <allow_registered_type_name_filter>. Default: empty (not applied)	0..1
<creation_mode>	Specifies when to create the StreamReader/StreamWriter. Default: IMMEDIATE See Section 4.5.7.1.	0..1
<datareader_qos> or <datawriter_qos>	Sets the DataReader or DataWriter QoS. The contents of this tag are specified in the same manner as a Connext DDS QoS profile. See Configuring QoS with XML, in the Connext DDS Core Libraries User’s Manual. If the tag is not defined, Routing Service will use the Connext DDS defaults.	0..1
<content_filter>	Defines a SQL content filter for the DataReader. Example: <content_filter> <expression> x &gt; 100 </expression> </content_filter>	0..1

4.5.9. Plugins

All the pluggable components specific to Routing Service are configured within the <plugin_library> tag. Table 4.20 describes the available tags.

Plug-ins are categorized and configured based on the source language. Routing Service supports C/C++ and Java plug-ins. See Section 7 for further information on developing Routing Service plug-ins.

Table 4.20 Configuration tags for plug-in libraries

Tags within <plugin_library>	Description	Multiplicity
<adapter_plugin>	Specifies a C/C++ Adapter plug-in. See Table 12.16. Attributes name: uniquely identifies an Adapter plug-in within a library. This name qualified with the library name represents the plug-in registered name that is referred by <connection> tags. See Table 4.6.	0..*
<java_adapter_plugin>	Specifies a Java Adapter plug-in. See Table 12.17. Attributes (See <adapter_plugin>).	0..*
<transformation_plugin>	Specifies a C/C++ Transformation plug-in. See Table 12.16. Attributes name: uniquely identifies an Transformation plug-in within a library. This name qualified with the library name represents the plug-in registered name that is referred by <transformation> tags. See Section 4.5.6.	0..*
<processor_plugin>	Specifies a C/C++ Processor plug-in. See Table 12.16. Attributes name: uniquely identifies an Processor plug-in within a library. This name qualified with the library name represents the plug-in registered name that is referred by <processor> tags. See Section 4.5.6.	0..*

4.6. Enabling Distributed Logger

Routing Service provides integrated support for RTI Distributed Logger.

Distributed Logger is included in Connext DDS but it is not supported on all platforms; see the Connext DDS Core Libraries Platform Notes to see which platforms support Distributed Logger.

When you enable Distributed Logger, Routing Service will publish its log messages to Connext DDS. Then you can use RTI Admin Console to visualize the log message data. Since the data is provided in a topic, you can also use rtiddsspy or even write your own visualization tool.

To enable Distributed Logger, use the tag <distributed_logger> within <adminstration>. For example:

<routing_service name="default">
    <administration>
        ...

        <distributed_logger>
            <enabled>true</enabled>
        </distributed_logger>
    </administration>
    ...
</routing_service>

For the list of elements that configure Distributed Logger see Section 4.5.2. For more details about Distributed Logger, see Enabling Distributed Logger in RTI Services.

4.7. Support for Extensible Types

Routing Service includes partial support for the ‘“Extensible and Dynamic Topic Types for DDS” specification <http://www.omg.org/spec/DDS-XTypes>’ from the Object Management Group (OMG). This section assumes that you are familiar with Extensible Types and you have read the Connext DDS Core Libraries Getting Started Guide Addendum for Extensible Types.

• Inputs and Outputs can subscribe to and publish topics associated with final and extensible types.
• You can select the type version associated with a topic route by providing the type description in the XML configuration file. The XML description supports structure inheritance. You can learn more about structure inheritance in the Connext DDS Getting Started Guide Addendum for Extensible Types.
• The TypeConsistencyEnforcementQosPolicy can be specified on a per-topic-route basis, in the same way as other QoS policies.
• Within a DomainParticipant, a topic cannot be associated with more than one type version. This prevents the same DomainParticipant from having two Route DataReader or DataWriter with different versions of a type for the same Topic. To achieve this behavior, create two different DomainParticipant, each associating the topic with a different type version.

The type declared in an Input is the version return edin the read operations within the installed Processor of the parent Route, which then can be provided directly to the Outputs, as long as they have a compatible type (or a Transformation that makes it compatible). An Input can subscribe to different-but-compatible types, but those samples are translated to the actual type of the Input.

4.7.1. Example: Samples Published by Two Writers of Type A and B, Respectively

struct A {
  long x;
};

struct B {
    long x;
    long y;
};

Table 4.21 Forwarded data when type in TopicRoute is not extended

Samples published by two DataWriters of types A and B, respectively	Samples forwarded by a TopicRoute for type A in both input and output	Samples received by a B reader
A [x=1]	A [x=1]	B [x=1, y=0]
B [x=10, y=11]	A [x=10]	B [x=10, y=0]

Table 4.22 Forwarded data when type in TopicRoute is extended

Samples published by two DataWriters of types A and B, respectively	Samples forwarded by a TopicRoute for type B in both input and output	Samples received by a B reader
A [x=1]	B [x=1, y=0]	B [x=1, y=0]
B [x=10, y=11]	B [x=10, y=11]	B [x=10, y=11]

4.8. Support for RTI FlatData and Zero Copy Transfer Over Shared Memory

Routing Service supports communication with applications that use RTI FlatData™ and Zero-Copy transfer over shared memory, only on the subscription side.

Warning

On the publication side, Routing Service will ignore the type annotations for these capabilities and will communicate through the regular serialization and deserialization paths.

To enable Routing Service to work with RTI FlatData and Zero-copy transfer over shared memory, you will need to manually define the type in the XML configuration with the proper annotations, and then register this type manually in each DomainParticipant. You can use each of these capabilities separately or together.

For further information about these capabilities, see the Sending Large Data section in the RTI Connext DDS User’s Manual.

4.8.1. Example: Configuration to enable both FlatData and zero-copy transfer over shared memory

<dds>
    <types>
        <struct name="Point"
                transferMode="shmem_ref"
                languageBinding="flat_data"
                extensibility= "final">
            <member name="x" type="long"/>
            <member name="y" type="long"/>
        </struct>
    </types>

    <qos_library name="MyQosLib">
        <qos_profile name="ShmemOnly">
            <participant_qos>
                <discovery>
                    <initial_peers>
                        <element>shmem://</element>
                    </initial_peers>
                </discovery>
                <transport_builtin>
                    <mask>SHMEM</mask>
                </transport_builtin>
            </participant_qos>
        </qos_profile>
    </qos_library>

    <routing_service name="FlatDataWithZeroCopy">

        <domain_route>
            <participant name="InputDomain">
                <domain_id>0</domain_id>
                <participant_qos base_name="MyQosLib::ShmemOnly"/>
                <registered_type name="Point" type_name="Point"/>
            </participant>
            <participant name="OutputDomain">
                <domain_id>1</domain_id>
                <registered_type name="Point" type_name="Point"/>
            </participant>

            <session>
                <topic_route>
                    <input participant="InputDomain">
                        <topic_name>PointTopic</topic_name>
                        <registered_type_name>Point</registered_type_name>
                    </input>
                    <output participant="OutputDomain">
                        <topic_name>PointTopic</topic_name>
                        <!-- The output will ignore the FlataData and Zero Copy capabilities -->
                        <registered_type_name>Point</registered_type_name>
                    </output>
                </topic_route>
            </session>
        </domain_route>
    </routing_service>
</dds>