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.
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¶
Tags within <dds> |
Description |
Multiplicity |
|---|---|---|
<user_environment> |
Assigns default values to XML variables. |
0..* |
<qos_library> |
Specifies a QoS library and profiles. |
0..* |
<types> |
Defines types that can be used by Routing Service. |
0..1 |
<plugin_library> |
Specifies a library of Routing Service plugins. |
0..* |
<routing_service> |
Specifies a Routing Service configuration.
|
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.
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. |
0..1 |
<monitoring> |
Enables and configures general remote monitoring. |
0..1 |
<entity_monitoring> |
Enables and configures remote monitoring for the service entity. |
0..1 |
<jvm> |
Configures the Java JVM used to load and run Java adapters.
For example:
You can use the |
0..1 |
<domain_route> |
Defines a mapping between two or more data domains.
|
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 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 Remote Administration.
Note
The command-line options used to configure remote administration take precedence over the XML configuration (see Usage).
Tags within <administration> |
Description |
Multiplicity |
|---|---|---|
<enabled> |
Enables/disables administration. |
0..1 |
<domain_id> |
Specifies which domain ID Routing Service will use to enable remote
administration. |
0..1 |
<distributed_logger> |
Configures RTI Distributed Logger.
|
0..1 |
<participant_qos> |
Configures the DomainParticipant QoS for remote administration. |
0..1 |
<publisher_qos> |
Configures the Publisher QoS for remote administration. |
0..1 |
<subscriber_qos> |
Configures the Subscriber QoS for remote administration. |
0..1 |
<datareader_qos> |
Configures the DataReader QoS for remote administration.
|
0..1 |
<datawriter_qos> |
Configures the DataWriter QoS for remote administration.
|
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.
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. |
0..1 |
<save_on_update> |
A boolean that, if true, automatically triggers a save command when
configuration updates are received. |
0..1 |
<reuse_monitoring_participant> |
Indicates whether the Monitoring participant is reused as the
administration participant. Default: false. |
0..1 |
8.2.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 Monitoring.
Note
The command-line options used to configure remote monitoring take precedence over the XML configuration (See Usage).
Tags within <monitoring> |
Description |
Multiplicity |
|---|---|---|
<enabled> |
Enables/disables general remote monitoring. Setting this tag to false disables monitoring in all the entities. In
this case, any monitoring configuration settings in the entities are
ignored. |
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. |
0..1 |
<participant_qos> |
Configures the DomainParticipant QoS for remote monitoring.
|
0..1 |
<publisher_qos> |
Configures the Publisher QoS for remote monitoring. |
0..1 |
<datawriter_qos> |
Configures the DataWriter QoS for remote monitoring.
|
0..1 |
<statistics_sampling_period> |
Specifies the frequency, in seconds, at which status statistics are gathered.
The statistics period for a given entity should be smaller than the
publication period. |
0..1 |
<statistics_publication_period> |
Specifies the frequency, in seconds, at which the status of an entity is published.
The statistics sampling period defined in |
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.
Tags within <entity_monitoring> |
Description |
Multiplicity |
|---|---|---|
<enabled> |
Enables/disables remote monitoring for a given entity. Default: true |
0..1 |
<statistics_sampling_period> |
Specifies the frequency at which status statistics are gathered.
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.
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
<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 8.6 describes the tags allowed within a
<domain_route> tag.
Tags within <domain_route> |
Description |
Multiplicity |
|---|---|---|
<entity_monitoring> |
Enables and configures remote monitoring for the DomainRoute. |
0..1 |
<connection> |
Applicable to non-DDS domains.
See Table 8.7. |
0..* |
<participant> |
Applicable to DDS domains. |
0..* |
<session> |
Defines a multi-threaded context in which data is routed according to specified routes. See Session.
|
0..* |
Tags within <connection> |
Description |
Multiplicity |
|---|---|---|
<property> |
A sequence of name-value string pairs that allows you to configure the Connection instance.
|
0..1 |
<register_type> |
Registers a type name and associates it with a type representation. |
0..* |
Tags within <participant> |
Description |
Multiplicity |
|---|---|---|
<domain_id> |
Sets the domain ID associated with the DomainParticipant. |
0..1 |
<participant_qos> |
Sets the participant QoS.
where:
- For example:
Note Changing the default participant name may prevent Routing Service from being detected by Admin Console. You can use a
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.
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. |
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.
Tags within <session> |
Description |
Multiplicity |
|---|---|---|
<entity_monitoring> |
Enables and configures remote monitoring for the Session. |
0..1 |
<thread_pool> |
Defines the number of threads to process Routes and sets the mask, priority, and stack size of each thread.
|
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|.
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.
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.
See Route. |
0..* |
<auto_topic_route> or <auto_route> |
Defines a factory for Route based on type and stream filters.
|
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>.
Tags within <route> |
Description |
Multiplicity |
|---|---|---|
<entity_monitoring> |
Enables and configures remote monitoring for the Route. |
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. |
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. |
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.
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 |
0..1 |
<processor> |
Sets a custom Processor for handling the data forwarding process.
|
0..1 |
<dds_input> |
Only applicable to DDS inputs. Defines an input topic. See Input/Output.
|
0..* |
<dds_output> |
Only applicable to DDS outputs. Defines an output topic. See Input/Output.
|
0..* |
<input> |
Only applicable to non-DDS inputs. Defines an input stream. See Input/Output.
|
0..* |
<output> |
Only applicable to non-DDS outputs. Defines an output stream. See Input/Output.
|
0..* |
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. |
0..1 |
<publish_with_original_info> |
Writes the data sample as if they came from its original writer. |
0..1 |
<publish_with_original_timestamp> |
Indicates if the data samples are written with their original source
timestamp. |
0..1 |
<propagate_dispose> |
Indicates whether or not disposed samples (NOT_ALIVE_DISPOSE) must be
propagated by the TopicRoute. |
0..1 |
<propagate_unregister> |
Indicates whether or not disposed samples (NOT_ALIVE_NO_WRITERS) must be
propagated by the TopicRoute. |
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.
|
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:
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).
|
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.
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 |
0..1 |
<processor> |
Sets a custom Processor for handling the data forwarding process. See Software Development Kit.
|
0..1 |
<input> |
Defines an input topic. See Input/Output.
|
0..* |
<output> |
Defines an output topic. See Input/Output.
|
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.
Tags within <input> and <output> of <route> |
Description |
Multiplicity |
|---|---|---|
<entity_monitoring> |
Enables and configures remote monitoring for the Input/Output. |
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. |
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)
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.
|
0..1 |
<transformation> (within <output> only) |
Sets a data transformation to be applied for every data sample.
|
0..1 |
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. |
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)
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 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.
|
0..1 (within <input> only) |
<transformation>` |
Sets a data transformation to be applied for every data sample.
|
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.
<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 DDS 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 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.
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 Output can transform the incoming data using a Transformation. To instantiate a Transformation:
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 Software Development Kit.
Instantiate a Transformation object by specifying a
<transformation>tag inside a<output>or<dds_output>.
Table 8.15 lists the tags allowed within a
<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.
|
0..1 |
<output_type_name> |
Available only when the transformation is set in an <input>.
Specifies the registered type name of the output samples. |
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. |
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>.
Tags within <auto_route> |
Description |
Multiplicity |
|---|---|---|
<entity_monitoring> |
Enables and configures remote monitoring for the AutoRoute. |
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. |
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.
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 |
0..1 |
<processor> |
Sets a custom Processor for handling the data forwarding process.
|
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 |
Tags within <auto_topic_route> |
Description |
Multiplicity |
|---|---|---|
<entity_monitoring> |
Enables and configures remote monitoring for the AutoTopicRoute. |
0..1 |
<publish_with_original_info> |
Writes the data sample as if they came from its original writer. |
0..1 |
<publish_with_original_timestamp> |
Indicates if the data samples are written with their original source
timestamp. |
0..1 |
<propagate_dispose> |
Indicates whether or not disposed samples (NOT_ALIVE_DISPOSE) must be
propagated by the TopicRoute. |
0..1 |
<propagate_unregister> |
Indicates whether or not disposed samples (NOT_ALIVE_NO_WRITERS) must be
propagated by the TopicRoute. |
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.
|
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).
|
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.
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 |
0..1 |
<processor> |
Sets a custom Processor for handling the data forwarding process.
|
0..1 |
<input> |
Defines an input topic. |
0..1 |
<output> |
Defines an output topic. |
0..1 |
Tags within <input> and <output> of <auto_route> |
Description |
Multiplicity |
|---|---|---|
<entity_monitoring> |
Enables and configures remote monitoring for the Input/Output. |
0..1 |
<allow_stream_name_filter> |
A stream name filter. |
0..1 |
<allow_registered_type_name_filter> |
A registered type name filter. |
0..1 |
<deny_stream_name_filter> |
A stream name filter that should be denied (excluded). This is applied
after the |
1 |
<deny_registered_type_filter> |
A registered type name filter that should be denied (excluded). This is applied
after the |
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)
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. |
0..1 |
<property> |
A sequence of name-value string pairs that allows you to configure the
StreamReader/StreamWriter.
|
0..1 |
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. |
0..1 |
<allow_topic_name_filter> |
A Topic name filter. |
0..1 |
<allow_registered_type_name_filter> |
A registered type name filter. |
0..1 |
<deny_topic_name_filter> |
A Topic name filter that should be denied (excluded). This is applied
after the |
1 |
<deny_registered_type_filter> |
A registered type name filter that should be denied (excluded). This is applied
after the |
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)
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. |
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.
|
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.
Tags within <plugin_library> |
Description |
Multiplicity |
|---|---|---|
<adapter_plugin> |
Specifies a C/C++ Adapter plug-in.
|
0..* |
<java_adapter_plugin> |
Specifies a Java Adapter plug-in.
|
0..* |
<transformation_plugin> |
Specifies a C/C++ Transformation plug-in.
|
0..* |
<processor_plugin> |
Specifies a C/C++ Processor plug-in.
|
0..* |
8.3. 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 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 DDS Extensible Types Guide.
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 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;
};
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] |
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] |