8. Configuration

8.1. Configuring Routing Service

This section provides a reference for the XML elements that conform a Routing Service configuration. For details on how to provide XML configurations to Routing Service. refer to Configuring RTI Services. This chapter describes how to compose an XML configuration.

Note

Routing Service makes use of XSD files to validate the XML configuration files used to configure Routing Service. Due to the restrictions imposed by XSD schemas for XML 1.0, some of the tags used in the configuration must be grouped in order. This behavior is intended; Routing Service validates the XML files before parsing them to catch as many errors as possible beforehand.

8.2. 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 8.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 8.1 Top-level Tags in the Configuration File

Table 8.1 Top-Level Tags in the Configuration File

Tags within <dds>	Description	Multiplicity
<configuration_variables>	Assigns default values to XML variables. See Configuration Variables.	0..*
<qos_library>	Specifies a QoS library and profiles. The contents of this tag are specified in the same manner as for a Connext 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 Specifying Types.	0..1
<plugin_library>	Specifies a library of Routing Service plugins. Available plug-ins are Adapters, Transformations and Processors. See Plugins.	0..*
<routing_service>	Specifies a Routing Service configuration. See Routing Service Tag. Attributes name: Uniquely identifies a Routing Service configuration. Required. 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>	0..*

8.2.1. Routing Service Tag

The <routing_service> tag is used to configure an execution of Routing Service. Configurations may contain multiple <routing_service> tags, so you will need to select which Service configuration to run (for example with -cfgName command-line parameter).

Note that the <routing_service> tag is optional. This is allowed so that different aspects of the configurations can be separated in different parts. For example, you could have all the QoS profiles in one file, and all the Service configurations in another.

Table 8.2 describes the tags allowed within a <routing_service> tag.

Table 8.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 Administration and Remote Administration.	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 Monitoring and Monitoring.	0..1
<entity_monitoring>	Enables and configures remote monitoring for the service entity. See Monitoring Configuration Inheritance and Monitoring.	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 Domain Route. 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..*

8.2.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

8.2.2. Administration

You can create a Connext 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 Remote Administration.

Note

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

Table 8.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
<distributed_logger>	Configures RTI Distributed Logger. When you enable it, Routing Service will publish its log messages to Connext. Example: <administration> ... <distributed_logger> <enabled>true</enabled> </distributed_logger> </administration>	0..1
<domain_participant_qos>	Configures the DomainParticipant QoS for remote administration. If the tag is not defined, Routing Service will use the Connext defaults.	0..1
<publisher_qos>	Configures the Publisher QoS for remote administration. If the tag is not defined, Routing Service will use the Connext defaults.	0..1
<subscriber_qos>	Configures the Subscriber QoS for remote administration. If the tag is not defined, Routing Service will use the Connext defaults.	0..1
<datareader_qos>	Configures the DataReader QoS for remote administration. If the tag is not defined, Routing Service will use the Connext 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
<datawriter_qos>	Configures the DataWriter QoS for remote administration. If the tag is not defined, Routing Service will use the Connext defaults with the following changes: history.kind = DDS_KEEP_ALL_HISTORY_QOS resource_limits.max_samples = 32	0..1
<memory_management>	Configures certain aspects of how Connext 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 allocates memory for samples is as follows: Connext 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
<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 (API Reference). If the specified file already exists, the file will be overwritten when save is executed. Default: [CURRENT DIRECTORY].	0..1
<save_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
<reuse_monitoring_participant>	Indicates whether the Monitoring participant is reused as the administration participant. If this tag is set to true and Monitoring is enabled, the tags domain_id and domain_participant_qos will be ignored if present. This tag has no effect if Monitoring is disabled or if the service is started in unloaded mode. Default: false.	0..1

8.2.3. Monitoring

You can create a Connext 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 Monitoring.

Note

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

Table 8.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
<domain_participant_qos>	Configures the DomainParticipant QoS for remote monitoring. If the tag is not defined, Routing Service will use the Connext 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 defaults.	0..1
<datawriter_qos>	Configures the DataWriter QoS for remote monitoring. If the tag is not defined, Routing Service will use the Connext 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
<status_publication_period>	Specifies the frequency, in seconds, at which the status of an entity is published. Example: <status_publication_period> <sec>5</sec> <nanosec>0</nanosec> </status_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

8.2.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 8.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
<status_publication_period>	Specifies the frequency at which the status of an entity is published. Example: <status_publication_period> <sec>5</sec> <nanosec>0</nanosec> </status_publication_period> If this tag is not defined, historical statistics are inherited from the general monitoring settings. Default: 5 seconds.	0..1

8.2.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>

8.2.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 <plugin_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 8.6 describes the tags allowed within a <domain_route> tag.

Table 8.6 Domain Route Tag

Tags within <domain_route>	Description	Multiplicity
<entity_monitoring>	Enables and configures remote monitoring for the DomainRoute. See Monitoring.	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 8.7.	0..*
<participant>	Applicable to DDS domains. Configures a DDS adapter DomainParticipant. See Table 8.8.	0..*
<session>	Defines a multi-threaded context in which data is routed according to specified routes. See Session. 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 8.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
<register_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 Route.	0..*

Table 8.8 Participant Tag

Tags within <participant>	Description	Multiplicity
<domain_id>	Sets the domain ID associated with the DomainParticipant. Default: 0	0..1
<domain_participant_qos>	Sets the participant QoS. The contents of this tag are specified in the same manner as a Connext QoS profile. If not specified, the DDS defaults are used, except for the participant name which takes the following value: “RTI Routing Service: <app name>.<domain route name>#<participant name>” where: - app name: The application name of the running Routing Service - domain route route: the configuration name of the parent DomainRoute - participant name: the configuration name of the DomainParticipant For example: “RTI Routing Service: MyService.MyDomainRoute#domain1” Note Changing the default participant name may prevent Routing Service from being detected by Admin Console. You can use a <domain_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: <domain_participant_qos base_name="MyLibrary::MyProfile"> <discovery> <initial_peers> <element>udpv4://192.168.1.12</element> <element>shmem://</element> </initial_peers> </discovery> </domain_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 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 allocates memory for samples is as follows: Connext 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
<register_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 Route.	0..*

8.2.4.1. Example: Mapping between Two DDS Domains

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

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

    ...
</domain_route>

8.2.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>

8.2.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 8.9 lists the tags allowed within a <session> tag.

Table 8.9 Session Tag

Tags within <session>	Description	Multiplicity
<entity_monitoring>	Enables and configures remote monitoring for the Session. See Monitoring.	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. This setting represents a default value for all the Routes in this | SESSION|. 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 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 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 defaults.	0..1
<publisher_qos>	Only applicable to Routes that are Connext 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 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 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 Route.	0..*
<auto_topic_route> or <auto_route>	Defines a factory for Route based on type and stream filters. See Auto Route. 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..*

8.2.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 8.10 lists the tags allowed within a <route>. Table 8.11 lists the tags allowed within a <topic_route>.

Table 8.10 Route Tag

Tags within <route>	Description	Multiplicity
<entity_monitoring>	Enables and configures remote monitoring for the Route. See Monitoring.	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 Discovering Types. Default: true	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
<periodic_action>	Specifies a period at which the installed Processor will receive notifications of the periodic event. The Session will wake up and notify the installed Processor every specified period. This tag overrides the value set, if any, in the parent Session. 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
<enable_data_on_inputs>	Indicates whether this route enables the dispatch of DATA_ON_INPUTS event. Default: True	0..1
<processor>	Sets a custom Processor for handling the data forwarding process. See Software Development Kit. 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 Input/Output. Attributes name: uniquely identifies an input configuration. Optional.	0..*
<dds_output>	Only applicable to DDS outputs. Defines an output topic. See Input/Output. Attributes name: uniquely identifies an output configuration. Optional.	0..*
<input>	Only applicable to non-DDS inputs. Defines an input stream. See Input/Output. Attributes name: uniquely identifies an input configuration. Optional.	0..*
<output>	Only applicable to non-DDS outputs. Defines an output stream. See Input/Output. Attributes name: uniquely identifies an output configuration. Optional.	0..*

Table 8.11 Topic Route Tag

Tags within <topic_route>	Description	Multiplicity
<entity_monitoring>	Enables and configures remote monitoring for the TopicRoute. See Monitoring.	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 Discovering Types. Default: true	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 Topic Query Support for detailed information on how Routing Service processes TopicQueries. The following tags are used to configure this tag: <enabled>: Whether topic query forwarding is enabled or not. By default, it is disabled. <mode>: How the TopicRoute handles the TopicQueries received from the user DataReaders on the subscription side. There are two modes for handling topic queries: DISPATCH and PROPAGATION. See Topic Query Support for details on each mode. Default: PROPAGATION. The XML 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 (Propagating Content Filters). 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 Propagating Content Filters). 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
<periodic_action>	Specifies a period at which the installed Processor will receive notifications of the periodic event. The Session will wake up and notify the installed Processor every specified period.|br| This tag overrides the value set, if any, in the parent Session. 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
<enable_data_on_inputs>	Indicates whether this route enables the dispatch of DATA_ON_INPUTS event. Default: True	0..1
<processor>	Sets a custom Processor for handling the data forwarding process. See Software Development Kit. 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 Input/Output. Attributes name: uniquely identifies an input configuration. Optional.	0..*
<output>	Defines an output topic. See Input/Output. Attributes name: uniquely identifies an output configuration. Optional.	0..*

8.2.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 8.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 Monitoring.	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 Creation Modes.	0..1
<on_delete_wait_for_ack_timeout>	Specifies a period for which the StreamWriter will wait for acknowledgment before its elimination. See Waiting for Acknowledgments in a DataWriter, in the Connext DDS Core Libraries User’s Manual. Default: 0 (no wait for acknowledgment) Example: <on_delete_wait_for_ack_timeout> <sec>1</sec> <nanosec>0</nanosec> </on_delete_wait_for_ack_timeout> The example above indicates that StreamWriter will wait one second for acknowledgment of the samples.	0..1 (within <dds_output> only)
<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>	Sets a data transformation to be applied for every data sample. See Data Transformation. 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 8.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 Creation Modes.	0..1
<on_delete_wait_for_ack_timeout>	Specifies a period for which the StreamWriter will wait for acknowledgment before its elimination. See Waiting for Acknowledgments in a DataWriter, in the Connext DDS Core Libraries User’s Manual. Default: 0 (no wait for acknowledgment) Example: <on_delete_wait_for_ack_timeout> <sec>1</sec> <nanosec>0</nanosec> </on_delete_wait_for_ack_timeout> The example above indicates that StreamWriter will wait one second for acknowledgment of the samples.	0..1 (within <output> only)
<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 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 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 (within <input> only)
<transformation>`	Sets a data transformation to be applied for every data sample. See Data Transformation. 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

8.2.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 8.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.

8.2.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>

8.2.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>

8.2.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 any of the DomainParticipants or Connections in a DomainRoute.

8.2.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 XML format for type definitions. See Creating User Data Types with Extensible Markup Language (XML), in the 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.

8.2.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">
                ...
                <register_type name="Position" type_ref="PointType"/>
            </connection>
            <participant name="MyParticipant">
                ...
                <register_type name="Position" type_ref="PointType"/>
            </participant>
            ...
            <session>
                <topic_route>
                    <input participant="2">
                        <registered_type_name>Position</registered_type_name>
                    </input>
                    ...
                </topic_route>
            </session>
            ...
        </domain_route>
        ...
    </routing_service>
    ...
</dds>

8.2.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 <route_types> tag is set to true. This means that for the creation of the StreamReader and StreamWriter, the types discovered in either one of the input or output domains will be used. Setting this tag to false explicitly will cause the creation of the StreamReader to be tied only to the discovery of types in the input domain, and the creation of the StreamWriter to be tied only to the discovery of types in the output domain.

See Type Registration for more details about type registration.

8.2.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>

8.2.7.3. Data Transformation

An Input and/or 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 Library API. See Software Development Kit.

2. Instantiate a Transformation object by specifying a <transformation> tag inside a <input>, <output>`, <dds_input>` or <dds_output>.

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

Table 8.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
<output_type_name>	Available only when the transformation is set in an <input>. Specifies the registered type name of the output samples. If not specified, this tag is set to the registered type name of the first output that has no transformation.	0..1
<output_connection_name>	Available only when the transformation is set in an <input>. Name of the <connection>/<participant> from which the registered type must be obtained. If not specified, the type will be obtained from the same connection of the parent Input or the first connection that the type is available.	0..1
<input_type_name>	Available only when the transformation is set in an <output>. Specifies the registered type name of the input samples. If not specified, this tag is set to the registered type name of the first input that has no transformation.	0..1
<input_connection_name>	Available only when the transformation is set in an <output>. Name of the <connection>/<participant> from which the registered type must be obtained. If not specified, the type will be obtained from the same connection of the parent Output or the first connection that the type is available.	0..1

8.2.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 8.16 lists the tags allowed within a <auto_route>.

• Table 8.17 lists the tags allowed within a <auto_topic_route>.

Table 8.16 AutoRoute Tag

Tags within <auto_route>	Description	Multiplicity
<entity_monitoring>	Enables and configures remote monitoring for the AutoRoute. See Monitoring.	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
<periodic_action>	Specifies a period at which the installed Processor will receive notifications of the periodic event. The Session will wake up and notify the installed Processor every specified period.|br| This tag overrides the value set, if any, in the parent Session. 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
<enable_data_on_inputs>	Indicates whether this route enables the dispatch of DATA_ON_INPUTS event. Default: True	0..1
<processor>	Sets a custom Processor for handling the data forwarding process. See Software Development Kit. 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 8.17 AutoTopicRoute Tag

Tags within <auto_topic_route>	Description	Multiplicity
<entity_monitoring>	Enables and configures remote monitoring for the AutoTopicRoute. See Monitoring.	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 Topic Query Support 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 Propagating Content Filters). 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
<periodic_action>	Specifies a period at which the installed Processor will receive notifications of the periodic event. The Session will wake up and notify the installed Processor every specified period.|br| This tag overrides the value set, if any, in the parent Session. 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
<enable_data_on_inputs>	Indicates whether this route enables the dispatch of DATA_ON_INPUTS event. Default: True	0..1
<processor>	Sets a custom Processor for handling the data forwarding process. See Software Development Kit. 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 8.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 Monitoring.	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
<on_delete_wait_for_ack_timeout>	Specifies a period for which the StreamWriter will wait for acknowledgment before its elimination. See Waiting for Acknowledgments in a DataWriter, in the Connext DDS Core Libraries User’s Manual. Default: 0 (no wait for acknowledgment) Example: <on_delete_wait_for_ack_timeout> <sec>1</sec> <nanosec>0</nanosec> </on_delete_wait_for_ack_timeout> The example above indicates that StreamWriter will wait one second for acknowledgment of the samples.	0..1 (within <dds_output> only)
<creation_mode>	Specifies when to create the StreamReader/StreamWriter. Default: IMMEDIATE See Creation Modes.	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 8.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 Monitoring.	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
<on_delete_wait_for_ack_timeout>	Specifies a period for which the StreamWriter will wait for acknowledgment before its elimination. See Waiting for Acknowledgments in a DataWriter, in the Connext DDS Core Libraries User’s Manual. Default: 0 (no wait for acknowledgment) Example: <on_delete_wait_for_ack_timeout> <sec>1</sec> <nanosec>0</nanosec> </on_delete_wait_for_ack_timeout> The example above indicates that StreamWriter will wait one second for acknowledgment of the samples.	0..1 (within <output> only)
<creation_mode>	Specifies when to create the StreamReader/StreamWriter. Default: IMMEDIATE See Creation Modes.	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 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 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 (within <input> only)

8.2.9. Plugins

All the pluggable components specific to Routing Service are configured within the <plugin_library> tag. Table 8.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 Software Development Kit for further information on developing Routing Service plug-ins.

Table 8.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.18. 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 8.6.	0..*
<java_adapter_plugin>	Specifies a Java Adapter plug-in. See Table 12.19. Attributes (See <adapter_plugin>)	0..*
<transformation_plugin>	Specifies a C/C++ Transformation plug-in. See Table 12.18. 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 Route.	0..*
<processor_plugin>	Specifies a C/C++ Processor plug-in. See Table 12.18. 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 Route.	0..*

8.3. Enabling Distributed Logger

Routing Service provides integrated support for RTI Distributed Logger.

Distributed Logger is included in Connext but it is not supported on all platforms; see the RTI Connext 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. 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 Administration. For more details about Distributed Logger, see Enabling Distributed Logger in RTI Services, in the Connext DDS Core Libraries User’s Manual.

8.4. Support for Extensible Types

Routing Service includes partial support for the “Extensible and Dynamic Topic Types for DDS” specification from the Object Management Group (OMG). This section assumes that you are familiar with Extensible Types and you have read the Connext Extensible Types Guide.

• Inputs and Outputs can subscribe to and publish topics associated with final and appendable 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 Extensible Types Guide.

• 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 returned in 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.

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

struct A {
  long x;
};

struct B {
    long x;
    long y;
};

Table 8.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 8.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]

8.5. 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.

Routing Service can work with RTI FlatData and Zero Copy transfer over shared memory for discovered types and types declared in the XML configuration. If the types are declared in XML, they must be properly annotated and then registered in each DomainParticipant. You can use each of these features separately or together.

For further information about these features, see Sending Large Data in the Connext Core Libraries User’s Manual.

8.5.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">
            <domain_participant_qos>
                <discovery>
                    <initial_peers>
                        <element>shmem://</element>
                    </initial_peers>
                </discovery>
                <transport_builtin>
                    <mask>SHMEM</mask>
                </transport_builtin>
            </domain_participant_qos>
        </qos_profile>
    </qos_library>

    <routing_service name="FlatDataWithZeroCopy">

        <domain_route>
            <participant name="InputDomain">
                <domain_id>0</domain_id>
                <domain_participant_qos base_name="MyQosLib::ShmemOnly"/>
                <register_type name="Point" type_ref="Point"/>
            </participant>
            <participant name="OutputDomain">
                <domain_id>1</domain_id>
                <register_type name="Point" type_ref="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>

8.5.2. Support for Security Plugins

Routing Service supports configuring and using Security Plugins. To configure Routing Service securely, you need to configure the appropriate QoS settings in the XML configuration. For more information, see the RTI Security Plugins User’s Manual.

8.5.3. Example: Configuring a Routing Service Instance using Security

The following example in XML demonstrates how to configure Routing Service to load and use the Security Plugins. The example assumes a path where the user has created the necessary security artifacts (such as permissions files, certificates, and certificate authorities). This path is represented by the SECURITY_ARTIFACTS_PATH environment variable.

Note

The SECURITY_ARTIFACTS_PATH environment variable must include the file: prefix to make sure paths are properly loaded by the Security Plugins.

<dds>
    <qos_library name="SecureQosLibrary">
        <qos_profile name="SecureParticipantQos">
            <domain_participant_qos>
                <property>
                    <value>
                        <element>
                            <name>com.rti.serv.load_plugin</name>
                            <value>com.rti.serv.secure</value>
                        </element>
                        <element>
                            <name>com.rti.serv.secure.library</name>
                            <value>nddssecurity</value>
                        </element>
                        <element>
                            <name>com.rti.serv.secure.create_function</name>
                            <value>RTI_Security_PluginSuite_create</value>
                        </element>
                        <element>
                            <name>dds.sec.auth.identity_ca</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/ecdsa01/ca/ecdsa01RootCaCert.pem</value>
                        </element>
                        <element>
                            <name>dds.sec.auth.identity_certificate</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/ecdsa01/identities/ecdsa01RoutingServiceCert.pem</value>
                        </element>
                        <element>
                            <name>dds.sec.auth.private_key</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/ecdsa01/identities/ecdsa01RoutingServiceKey.pem</value>
                        </element>
                        <element>
                            <name>dds.sec.access.permissions_ca</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/ecdsa01/ca/ecdsa01RootCaCert.pem</value>
                        </element>
                        <element>
                            <name>dds.sec.access.governance</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/signed_Governance.p7s</value>
                        </element>
                        <element>
                            <name>dds.sec.access.permissions</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/signed_PermissionsA.p7s</value>
                        </element>
                    </value>
                </property>
            </domain_participant_qos>
        </qos_profile>
    </qos_library>

    ...

    <routing_service name="SecureToUnsecureCommunication">
        <domain_route name="DomainRoute1">
            <participant name="1">
                <domain_id>1</domain_id>
                <!-- Domain Participant in Domain 1 is secured -->
                <domain_participant_qos base_name="SecureQosLibrary::SecureParticipantQos" />
            </participant>
            <participant name="2">
                <domain_id>2</domain_id>
                <!-- Domain Participant in Domain 2 is not secured -->
                <domain_participant_qos base_name="DefaultQosLibrary::DefaultQos" />
            </participant>
            <session name="S1">
                <topic_route name="SecureToUnsecure">
                    <input participant="1">
                        <topic_name>Topic01_Secure</topic_name>
                        <registered_type_name>...</registered_type_name>
                        <datareader_qos base_name="DefaultQosLibrary::DefaultQos"/>
                    </input>
                    <output>
                        <topic_name>Topic01_Unsecure</topic_name>
                        <registered_type_name>...</registered_type_name>
                        <datawriter_qos base_name="DefaultQosLibrary::DefaultQos"/>
                    </output>
                </topic_route>
            </session>
        </domain_route>
    </routing_service>

</dds>

The above XML example configures a Domain Route that moves data from a secured DomainParticipant into an unsecure DomainParticipant. The security settings are encapsulated in a QoS Profile called SecureParticipantQos. When secured data reaches the secured endpoint, the Routing Service instance performs all security operations that will be incorporated in the cleartext sample moving into the other end of the Topic Route. The data is then published into the unsecured domain.

8.5.4. Example: Configuring Routing Service to use a Certificate Revocation List (CRL)

Routing Service can remove a DomainParticipant from the system when its certificate has been revoked. Use Security Plugins to specify a CRL (Certificate Revocation List) file to track via the authentication.crl property; when the files_poll_interval property is configured in Security Plugins, Routing Service can banish revoked participants. For more information, see Properties for Configuring Authentication in the RTI Security Plugins User’s Manual. The following example XML configuration file uses a CRL file to enable Routing Service to remove participants with revoked certificates.

<dds>
    <qos_library name="SecureQosLibrary">
        <qos_profile name="SecureParticipantQos">
            <domain_participant_qos>
                <property>
                    <value>
                        <element>
                            <name>com.rti.serv.load_plugin</name>
                            <value>com.rti.serv.secure</value>
                        </element>
                        <element>
                            <name>com.rti.serv.secure.library</name>
                            <value>nddssecurity</value>
                        </element>
                        <element>
                            <name>com.rti.serv.secure.create_function</name>
                            <value>RTI_Security_PluginSuite_create</value>
                        </element>
                        <element>
                            <name>dds.sec.auth.identity_ca</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/ecdsa01/ca/ecdsa01RootCaCert.pem</value>
                        </element>
                        <element>
                            <name>dds.sec.auth.identity_certificate</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/ecdsa01/identities/ecdsa01RoutingServiceCert.pem</value>
                        </element>
                        <element>
                            <name>dds.sec.auth.private_key</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/ecdsa01/identities/ecdsa01RoutingServiceKey.pem</value>
                        </element>
                        <element>
                            <name>dds.sec.access.permissions_ca</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/ecdsa01/ca/ecdsa01RootCaCert.pem</value>
                        </element>
                        <element>
                            <name>dds.sec.access.governance</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/signed_Governance.p7s</value>
                        </element>
                        <element>
                            <name>dds.sec.access.permissions</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/signed_PermissionsA.p7s</value>
                        </element>
                    </value>
                </property>
            </domain_participant_qos>
        </qos_profile>
        <qos_profile name="SecureParticipantQosWithCrl" base_name="SecureQosLibrary::SecureParticipantQos">
            <domain_participant_qos>
                <property>
                    <value>
                        <element>
                            <name>com.rti.serv.secure.authentication.crl</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/RoutingServiceRevoked.crl</value>
                        </element>
                        <element>
                            <name>com.rti.serv.secure.files_poll_interval</name>
                            <value>1</value>
                        </element>
                    </value>
                </property>
            </domain_participant_qos>
        </qos_profile>
    </qos_library>

    ...

    <routing_service name="SecureToUnsecureCommunication">
        <domain_route name="DomainRoute1">
            <participant name="1">
                <domain_id>1</domain_id>
                <!-- Domain Participant in Domain 1 is secured -->
                <domain_participant_qos base_name="SecureQosLibrary::SecureParticipantQosWithCrl" />
            </participant>
            <participant name="2">
                <domain_id>2</domain_id>
                <!-- Domain Participant in Domain 2 is not secured -->
                <domain_participant_qos base_name="DefaultQosLibrary::DefaultQos" />
            </participant>
            <session name="S1">
                <topic_route name="SecureToUnsecure">
                    <input participant="1">
                        <topic_name>Topic01_Secure</topic_name>
                        <registered_type_name>...</registered_type_name>
                        <datareader_qos base_name="DefaultQosLibrary::DefaultQos"/>
                    </input>
                    <output>
                        <topic_name>Topic01_Unsecure</topic_name>
                        <registered_type_name>...</registered_type_name>
                        <datawriter_qos base_name="DefaultQosLibrary::DefaultQos"/>
                    </output>
                </topic_route>
            </session>
        </domain_route>
    </routing_service>

</dds>

The above configuration in Routing Service reads the CRL file $SECURITY_ARTIFACTS_PATH/RoutingServiceRevoked.crl. In addition, the files_poll_interval element instructs the service to track the file for changes so that participants can be removed dynamically. The polling of the file happens every 1s.

Note

If the poll period is zero, Routing Service will not track the file continuously.

8.5.5. Example: Configuring Routing Service for Dynamic Certificate Renewal

Routing Service can dynamically renew its certificate if it was revoked or it expired. Use Security Plugins to specify a periodic check of the certificate file; when this property is configured in Security Plugins, Routing Service reloads the certificate if the file changes. For more information, see the RTI Security Plugins User’s Manual.

The following example XML configuration file defines a 1s period for checking the certificate file for changes.

<dds>
    <qos_library name="SecureQosLibrary">
        <qos_profile name="SecureParticipantQos">
            <domain_participant_qos>
                <property>
                    <value>
                        <element>
                            <name>com.rti.serv.load_plugin</name>
                            <value>com.rti.serv.secure</value>
                        </element>
                        <element>
                            <name>com.rti.serv.secure.library</name>
                            <value>nddssecurity</value>
                        </element>
                        <element>
                            <name>com.rti.serv.secure.create_function</name>
                            <value>RTI_Security_PluginSuite_create</value>
                        </element>
                        <element>
                            <name>dds.sec.auth.identity_ca</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/ecdsa01/ca/ecdsa01RootCaCert.pem</value>
                        </element>
                        <element>
                            <name>dds.sec.auth.identity_certificate</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/ecdsa01/identities/ecdsa01RoutingServiceCert.pem</value>
                        </element>
                        <element>
                            <name>dds.sec.auth.private_key</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/ecdsa01/identities/ecdsa01RoutingServiceKey.pem</value>
                        </element>
                        <element>
                            <name>dds.sec.access.permissions_ca</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/ecdsa01/ca/ecdsa01RootCaCert.pem</value>
                        </element>
                        <element>
                            <name>dds.sec.access.governance</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/signed_Governance.p7s</value>
                        </element>
                        <element>
                            <name>dds.sec.access.permissions</name>
                            <value>$(SECURITY_ARTIFACTS_PATH)/signed_PermissionsA.p7s</value>
                        </element>
                    </value>
                </property>
            </domain_participant_qos>
        </qos_profile>
        <qos_profile name="SecureParticipantQosDynamicCert" base_name="SecureQosLibrary::SecureParticipantQos">
            <domain_participant_qos>
                <property>
                    <value>
                        <element>
                            <name>com.rti.serv.secure.files_poll_interval</name>
                            <value>1</value>
                        </element>
                    </value>
                </property>
            </domain_participant_qos>
        </qos_profile>
    </qos_library>

    ...

    <routing_service name="SecureToUnsecureCommunication">
        <domain_route name="DomainRoute1">
            <participant name="1">
                <domain_id>1</domain_id>
                <!-- Domain Participant in Domain 1 is secured -->
                <domain_participant_qos base_name="SecureQosLibrary::SecureParticipantQosDynamicCert" />
            </participant>
            <participant name="2">
                <domain_id>2</domain_id>
                <!-- Domain Participant in Domain 2 is not secured -->
                <domain_participant_qos base_name="DefaultQosLibrary::DefaultQos" />
            </participant>
            <session name="S1">
                <topic_route name="SecureToUnsecure">
                    <input participant="1">
                        <topic_name>Topic01_Secure</topic_name>
                        <registered_type_name>...</registered_type_name>
                        <datareader_qos base_name="DefaultQosLibrary::DefaultQos"/>
                    </input>
                    <output>
                        <topic_name>Topic01_Unsecure</topic_name>
                        <registered_type_name>...</registered_type_name>
                        <datawriter_qos base_name="DefaultQosLibrary::DefaultQos"/>
                    </output>
                </topic_route>
            </session>
        </domain_route>
    </routing_service>

</dds>

The above configuration in Routing Service periodically (every 1s) checks the DomainParticipant certificate file $SECURITY_ARTIFACTS_PATH/ecdsa01/identities/ecdsa01RoutingServiceCert.pem for changes.

Note

If the poll period is zero, Routing Service will not track the file continuously.

8.6. Support for Application Acknowledgment

Routing Service offers limited support for Application Acknowledgment. For information about acknowledging DDS samples in Connext, see Application Acknowledgment in the RTI Connext Core Libraries User’s Manual.

On the input side of the Routes, Routing Service uses the default DDS_PROTOCOL_ACKNOWLEDGMENT_MODE, which is equivalent to using no application-level sample acknowledgment.

On the output side of the Routes, and only in the built-in DDS adapter, Routing Service includes a setting to wait for acknowledgments until the output is finalized. When this option is enabled, Routing Service calls the wait_for_acknowledgments() API on the DDS output’s DataWriter. The wait period can be specified in the XML as follows:

...
<topic_route>
    ...
    <output participant="domain1">
        <topic_name>MyTopic</topic_name>
        <registered_type_name>MyTopicType</registered_type_name>
        <on_delete_wait_for_ack_timeout>
            <sec>30</sec>
            <nanosec>0</nanosec>
        </on_delete_wait_for_ack_timeout>
        <datawriter_qos>
            <reliability>
                <acknowledgment_kind>
                    APPLICATION_EXPLICIT_ACKNOWLEDGMENT_MODE
                </acknowledgment_kind>
            </reliability>
        </datawriter_qos>
    </output>
</topic_route>

The above example waits 30 seconds for acknowledgements. See Input/Output for details on the <on_delete_wait_for_ack_timeout> setting.