.. include:: vars.rst

.. _section-configuration:

Configuration
*************

Configuring |RS_HEADING|
========================

This section provides a reference for the XML elements that conform a |RS|
configuration. For details on how to provide XML configurations to |RS|.
refer to :ref:`section-Common-Config`. This chapter describes how to compose
an XML configuration.

.. _section-xml-tags-for-configuring-routing-service:

XML Tags for Configuring |project|
==================================

This section describes the XML tags you can use in a |RS| configuration file.
The following diagram and :numref:`TableTopLevelTag` describe the top-level
tags allowed within the root ``<dds>`` tag.

.. warning::

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


.. figure:: static/RouterXmlDdsTag.svg
    :alt: Top-Level Tags in the Configuration File
    :name: FigureTopLevelTag
    :align: center
    :width: 300px

    Top-level Tags in the Configuration File

.. list-table:: Top-Level Tags in the Configuration File
    :name: TableTopLevelTag
    :widths: 30 60 10
    :header-rows: 1
    :class: longtable

    * - Tags within <dds>
      - Description
      - Multiplicity
    * - <user_environment>
      - Assigns default values to XML variables.
      - 0..*
    * - <qos_library>
      - Specifies a QoS library and profiles. |br|
        The contents of this tag are specified in the same manner as for a
        |CONNEXT| application. |br|
        See :link_configuring_qos_xml:`Configuring QoS with XML, in the Connext
        DDS Core Libraries User's Manual <>`.
      - 0..*
    * - <types>
      - Defines types that can be used by |RS|. |br|
        See :ref:`section-Config-StreamPort-Types`.
      - 0..1
    * - <plugin_library>
      - Specifies a library of |RS| plugins. |br|
        Available plug-ins are *Adapters*, *Transformations* and *Processors*.
        See :ref:`section-Config-Plugins`.
      - 0..*
    * - <routing_service>
      - Specifies a |RS| configuration. |br|
        See :ref:`section-config-routing-service`.

        Attributes
            - ``name``: Uniquely identifies a |RS| 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. |br|
              Default: true.
            - ``group_name``: A name that can be used to implement a specific
              policy when the communication happens between |RS| of the same
              group.
              For example, in the builtin DDS adapter, a |DP| will
              ignore other |DPs| in the same group, as a way to avoid circular
              communication. Optional. |br|
              Default:
              RTI_RoutingService\ _\ ``[Host Name]``\ _ \ ``[Process ID]``\ |br|


        Example
            .. code-block:: xml

                <routing_service name="ExampleService">
                    <!-- your service settings ... -->
                </routing_service>

      - 0..*

.. _section-config-routing-service:

Routing Service Tag
-------------------

The |SERVICE_TAG| tag is used to configure an execution of |RS|. Configurations may
contain multiple |SERVICE_TAG| tags, so you will need to select which |SERVICE|
configuration to run (for example with ``-cfgName`` command-line parameter).

Note that the |SERVICE_TAG| 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.

:numref:`TableRoutingServiceTag` describes the tags allowed within a
|SERVICE_TAG| tag.

.. list-table:: |RS| Tag
    :name: TableRoutingServiceTag
    :widths: 30 60 10
    :header-rows: 1
    :class: longtable

    * - 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. |br|
        See :ref:`section-config-administration` and
        :ref:`section-Admin`.
      - 0..1
    * - <monitoring>
      - Enables and configures general remote monitoring. |br|
        General monitoring settings are applicable to all the |RS| entities
        unless they are explicitly overridden. |br|
        See :ref:`section-config-monitoring` and :ref:`section-monitoring`.
      - 0..1
    * - <entity_monitoring>
      - Enables and configures remote monitoring for the service entity. |br|
        See :ref:`section-config-monitoring-inheritance` and
        :ref:`section-monitoring`.
      - 0..1
    * - <jvm>
      - Configures the Java JVM used to load and run Java adapters.
        For example: |br|

        Example
            .. code-block:: xml

               <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. |br|
        See :ref:`section-config-DomainRoute`.

        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. |br|
              Default: true.
      - 0..*

Example: Specifying a configuration in XML
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: xml

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

Starting |RS| with the following command will use the
|SERVICE_TAG| tag with the name ``EmptyConfiguration``.

.. code-block:: bash

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


.. _section-config-administration:

Administration
--------------

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

When remote administration is enabled, |RS| will create a |DP|, |PUB|, |SUB|,
|DW|, and |DR|. 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 :ref:`section-Admin`.

.. note::
    The command-line options used to configure remote administration take
    precedence over the XML configuration (see :ref:`section-usage`).

.. list-table:: Administration Tag
    :name: TableAdministrationTag
    :widths: 30 60 10
    :header-rows: 1
    :class: longtable

    * - Tags within <administration>
      - Description
      - Multiplicity
    * - <enabled>
      - Enables/disables administration. |br|
        **Default:** true
      - 0..1
    * - <domain_id>
      - Specifies which domain ID |RS| will use to enable remote
        administration. |br|
      - 0..1
    * - <distributed_logger>
      - Configures |RTI_DISTLOG|. |br|
        When you enable it, |RS| will publish its log messages to |CONNEXT|.

        Example:
            .. code-block:: xml

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

      - 0..1
    * - <participant_qos>
      - Configures the |DP| QoS for remote administration. |br|
        If the tag is not defined, |RS| will use the |CONNEXT|
        defaults.
      - 0..1
    * - <publisher_qos>
      - Configures the |PUB| QoS for remote administration. |br|
        If the tag is not defined, |RS| will use the |CONNEXT|
        defaults.
      - 0..1
    * - <subscriber_qos>
      - Configures the |SUB| QoS for remote administration. |br|
        If the tag is not defined, |RS| will use the |CONNEXT|
        defaults.
      - 0..1
    * - <datareader_qos>
      - Configures the |DR| QoS for remote administration. |br|
        If the tag is not defined, |RS| 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 |DW| QoS for remote administration. |br|
        If the tag is not defined, |RS| 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 |DP| and therefore affects all the contained
        DDS entities. |br|

        Example:
            .. code-block:: xml

                <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 |DRs| and |DWs|, the way
                |CONNEXT| allocates memory for samples is as follows:
                |CONNEXT| pre-allocates space for samples up to size X in the
                |DR| and |DW| 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. |br|
        A ``<save_path>`` must be specified if you want to use the remote save
        command (:ref:`section-Admin-ApiReference`). If the specified
        file already exists, the file will be overwritten when save is executed. |br|
        **Default:** [CURRENT DIRECTORY].
      - 0..1
    * - <save_on_update>
      - A boolean that, if true, automatically triggers a save command when
        configuration updates are received. |br|
        This value is sent as part of the monitoring configuration data for the
        |RS|. |br|
        **Default:** false.
      - 0..1
    * - <reuse_monitoring_participant>
      - Indicates whether the Monitoring participant is reused as the
        administration participant. |br|
        If this tag is set to true *and* Monitoring is enabled, the tags
        ``domain_id`` and ``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

.. _section-config-monitoring:

Monitoring
----------

You can create a |CONNEXT| application that can remotely monitor the status of
|RS|. To enable remote monitoring and configure its behavior, use the
``<monitoring>`` and ``<entity_monitoring>`` tags.

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

When remote monitoring is enabled, |RS| will create one |DP|, one |PUB|, five
|DWs| for data publication (one for each kind of entity), and five |DWs| for
status publication (one for each kind of entity). You can configure the QoS of
these entities with the ``<monitoring>`` tag defined under |SERVICE_TAG|.
The general remote monitoring parameters specified using the ``<monitoring>``
tag in |SERVICE_TAG| can be overwritten on a per entity basis using the
``<entity_monitoring>`` tag.

For more details, please see :ref:`section-monitoring`.

.. note::
    The command-line options used to configure remote monitoring take
    precedence over the XML configuration (See :ref:`section-usage`).

.. list-table:: Monitoring Tag
    :name: TableMonitoringTag
    :widths: 30 60 10
    :header-rows: 1
    :class: longtable

    * - Tags within <monitoring>
      - Description
      - Multiplicity
    * - <enabled>
      - Enables/disables general remote monitoring. |br|
        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. |br|

        Setting this tag to false disables monitoring in all the entities. In
        this case, any monitoring configuration settings in the entities are
        ignored. |br|
        **Default:** true
      - 0..1
    * - <domain_id>
      - Specifies which domain ID |RS| will use to enable remote
        monitoring. |br|
      - 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. |br|
        **Default:** false
      - 0..1
    * - <participant_qos>
      - Configures the |DP| QoS for remote monitoring. |br|
        If the tag is not defined, |RS| will use the |CONNEXT|
        defaults, with the following change:

            - resource_limits.type_code_max_serialized_length = 4096
      - 0..1
    * - <publisher_qos>
      - Configures the |PUB| QoS for remote monitoring. |br|
        If the tag is not defined, |RS| will use the |CONNEXT|
        defaults.
      - 0..1
    * - <datawriter_qos>
      - Configures the |DW| QoS for remote monitoring. |br|
        If the tag is not defined, |RS| 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. |br|
        Statistical variables such as latency are part of the entity status. |br|

        Example:
            .. code-block:: xml

                <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. |br|
        The statistics sampling period defined in |SERVICE_TAG| is
        inherited by all the entities.
        An entity can overwrite the period. |br|
        **Default:** 1
      - 0..1
    * - <statistics_publication_period>
      - Specifies the frequency, in seconds, at which the status of an entity is published. |br|

        Example:
            .. code-block:: xml

                <statistics_publication_period>
                    <sec>5</sec>
                    <nanosec>0</nanosec>
                </statistics_publication_period>

        The statistics sampling period defined in |SERVICE_TAG| is inherited by
        all the entities.
        An entity can overwrite the period. |br|
        **Default:** 5
      - 0..1


.. _section-config-monitoring-inheritance:

Monitoring Configuration Inheritance
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The monitoring configuration defined in |SERVICE_TAG| 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.

.. list-table:: Entity Monitoring Tag
    :name: TableEntityMonitoringTag
    :widths: 30 60 10
    :header-rows: 1
    :class: longtable

    * - Tags within <entity_monitoring>
      - Description
      - Multiplicity
    * - <enabled>
      - Enables/disables remote monitoring for a given entity. |br|
        If general monitoring is disabled, this value is ignored. |br|

        **Default:** true
      - 0..1
    * - <statistics_sampling_period>
      - Specifies the frequency at which status statistics are gathered. |br|
        Statistical variables such as latency are part of the entity status. |br|

        Example:
            .. code-block:: xml

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

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

        Example:
            .. code-block:: xml

                <statistics_publication_period>
                    <sec>5</sec>
                    <nanosec>0</nanosec>
                </statistics_publication_period>

        If this tag is not defined, historical statistics are inherited from
        the general monitoring settings.

        **Default:** 5 seconds.
      - 0..1


Example: Overriding Publication Period
''''''''''''''''''''''''''''''''''''''

.. code-block:: xml

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

.. _section-Config-DomainRoute:

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

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

:numref:`TableDomainRouteTag` describes the tags allowed within a
``<domain_route>`` tag.



.. list-table:: Domain Route Tag
    :name: TableDomainRouteTag
    :widths: 30 60 10
    :header-rows: 1
    :class: longtable

    * - Tags within <domain_route>
      - Description
      - Multiplicity
    * - <entity_monitoring>
      - Enables and configures remote monitoring for the |DOMAINROUTE|. |br|
        See :ref:`section-monitoring`.
      - 0..1
    * - <connection>
      - Applicable to non-DDS domains. |br|
        Configures a custom, adapter-based connection. |br|

        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 :numref:`TableConnectionTag`.
      - 0..*
    * - <participant>
      - Applicable to DDS domains. |br|
        Configures a DDS adapter |DP|. |br|
        See :numref:`TableParticipantTag`.
      - 0..*
    * - <session>
      - Defines a multi-threaded context in which data is routed according to
        specified routes. See :ref:`section-config-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. |br|
              Default: true.
      - 0..*

.. list-table:: Connection Tag
    :name: TableConnectionTag
    :widths: 30 60 10
    :header-rows: 1
    :class: longtable

    * - Tags within <connection>
      - Description
      - Multiplicity
    * - <property>
      - A sequence of name-value string pairs that allows you to configure the
        |CONNECTION| instance.

        Example:
            .. code-block:: xml

                <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. |br|
        When you define a type in the configuration file, you have to register
        the type in order to use it in |ROUTEs|. |br|
        See :ref:`section-Config-Route`.
      - 0..*


.. list-table:: Participant Tag
    :name: TableParticipantTag
    :widths: 30 60 10
    :header-rows: 1
    :class: longtable

    * - Tags within <participant>
      - Description
      - Multiplicity
    * - <domain_id>
      - Sets the domain ID associated with the |DP|. |br|
        **Default:** 0 |br| |br|
      - 0..1
    * - <participant_qos>
      - Sets the participant QoS. |br|
        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 |RS_HEADING|: <app name>.<domain route name>#<participant name>"

        where:
        - ``app name``: The application name of the running |RS|
        - ``domain route route``:  the configuration name of the parent |DOMAINROUTE|
        - ``participant name``: the configuration name of the |DP|

        For example:

            "RTI |RS_HEADING|: MyService.MyDomainRoute#domain1"

        .. note::

            Changing the default participant name may prevent |RS| 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:
            .. code-block:: xml

                <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 :link_configuring_qos_xml:`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 |DP| and therefore affects all the contained
        DDS entities. |br|

        Example:
            .. code-block:: xml

                <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 |DRs| and |DWs|, the way
                |CONNEXT| allocates memory for samples is as follows:
                |CONNEXT|  pre-allocates space for samples up to size X in the
                |DR| and |DW| 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. |br|
        When you define a type in the configuration file, you have to register
        the type in order to use it in |ROUTEs|. |br|
        See :ref:`section-Config-Route`.
      - 0..*

Example: Mapping between Two DDS Domains
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: xml

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

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

        ...
    </domain_route>

Example: Mapping between a DDS Domain and raw Sockets
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: xml

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

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

        ...
    </domain_route>

.. _section-config-session:

Session
-------

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

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 |PUB| and a |SUB| from the |DPs|
associated with the domains. :numref:`TableSessionTag` lists the tags
allowed within a ``<session>`` tag.


.. list-table:: Session Tag
    :name: TableSessionTag
    :widths: 30 60 10
    :header-rows: 1
    :class: longtable

    * - Tags within <session>
      - Description
      - Multiplicity
    * - <entity_monitoring>
      - Enables and configures remote monitoring for the |SESSION|. |br|
        See :ref:`section-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:
            .. code-block:: xml

                <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|. |br|
        **Default:** INFINITE (no periodic notification)

        Example:
            .. code-block:: xml

                <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:
            .. code-block:: xml

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

        Sets the QoS associated with the session |SUBs|. There is one
        |SUB| per |DP|. The contents of this tag are specified in the same
        manner as a |CONNEXT| QoS profile. See
        :link_configuring_qos_xml:`Configuring QoS with XML, in the Connext
        DDS Core Libraries User's Manual <>`.

        If the tag is not defined, |RS| will use the |CONNEXT|
        defaults.
      - 0..1
    * - <publisher_qos>
      - Only applicable to |ROUTEs| that are |CONNEXT| |ROUTEs|. |br|

        Sets the QoS associated with the session |PUBs|. There is one
        |PUB| per |DP|. The contents of this tag are specified in the same
        manner as a |CONNEXT| QoS profile. See
        :link_configuring_qos_xml:`Configuring QoS with XML, in the Connext
        DDS Core Libraries User's Manual <>`.

        If the tag is not defined, |RS| will use the |CONNEXT|
        defaults.
      - 0..*
    * - <topic_route> or <route>
      - Defines a mapping between multiple input and output streams. |br|

        Attributes
            - ``name``: uniquely identifies a |TR| 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. |br|
              Default: true.

        See :ref:`section-Config-Route`.
      - 0..*
    * - <auto_topic_route> or <auto_route>
      - Defines a factory for |ROUTE| based on type and stream filters. |br|
        See :ref:`section-Config-AutoRoute`.

        Attributes
            - ``name``: uniquely identifies an |ATR| or |AR| 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. |br|
              Default: true.

      - 0..*

.. _section-Config-Route:

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
|SR| read and |SW| write operations.

:numref:`TableRouteTag` lists the tags allowed within a ``<route>``.
:numref:`TableTopicRouteTag` lists the tags allowed within a ``<topic_route>``.

.. list-table:: Route Tag
    :name: TableRouteTag
    :widths: 30 60 10
    :header-rows: 1
    :class: longtable

    * - Tags within <route>
      - Description
      - Multiplicity
    * - <entity_monitoring>
      - Enables and configures remote monitoring for the |ROUTE|. |br|
        See :ref:`section-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 |SWs| and |SRs| in the
        |ROUTE|. |br|
        See :ref:`section-Config-TypeDiscovery`. |br|
        **Default:** false
      - 0..1
    * - <publish_with_original_timestamp>
      - When this tag is true, the data samples read from the input stream are
        written into the output stream with the same timestamp that was
        associated with them when they were made available in the input domain. |br|

        This option may not be applicable in some adapter implementations in
        which the concept of timestamp is unsupported. |br|
        **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|. |br|
        **Default:** INFINITE (no periodic notification)

        Example:
            .. code-block:: xml

                <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. |br|
        **Default**: True
      - 0..1
    * - <processor>
      - Sets a custom Processor for handling the data forwarding process. |br|
        See :ref:`section-Sdk`.

        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 :ref:`section-Config-StreamPort`.

        Attributes
            - ``name``: uniquely identifies an input configuration. Optional.
      - 0..*
    * - <dds_output>
      - Only applicable to DDS outputs. Defines an output topic.
        See :ref:`section-Config-StreamPort`.

        Attributes
            - ``name``: uniquely identifies an output configuration. Optional.
      - 0..*
    * - <input>
      - Only applicable to non-DDS inputs. Defines an input stream.
        See :ref:`section-Config-StreamPort`.

        Attributes
            - ``name``: uniquely identifies an input configuration. Optional.
      - 0..*
    * - <output>
      - Only applicable to non-DDS outputs. Defines an output stream.
        See :ref:`section-Config-StreamPort`.

        Attributes
            - ``name``: uniquely identifies an output configuration. Optional.

      - 0..*


.. list-table:: Topic Route Tag
    :name: TableTopicRouteTag
    :widths: 30 60 10
    :header-rows: 1
    :class: longtable

    * - Tags within <topic_route>
      - Description
      - Multiplicity
    * - <entity_monitoring>
      - Enables and configures remote monitoring for the |TR|.
        See :ref:`section-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 |DRs| and |DWs| in the
        |ROUTE|. |br|
        See :ref:`section-Config-TypeDiscovery`.
        |br|
        **Default:** false
      - 0..1
    * - <publish_with_original_info>
      - Writes the data sample as if they came from its original writer. |br|
        Setting this option to true allows having redundant routing services
        and prevents the applications from receiving duplicate samples. |br|
        **Default**: false
      - 0..1
    * - <publish_with_original_timestamp>
      - Indicates if the data samples are written with their original source
        timestamp. |br|
        **Default**: false
      - 0..1
    * - <propagate_dispose>
      - Indicates whether or not disposed samples (NOT_ALIVE_DISPOSE) must be
        propagated by the |TR|. |br|
        This action may be overwritten by the execution of a transformation. |br|
        **Default**: true
      - 0..1
    * - <propagate_unregister>
      - Indicates whether or not disposed samples (NOT_ALIVE_NO_WRITERS) must be
        propagated by the |TR|. |br|
        This action may be overwritten by the execution of a transformation. |br|
        **Default**: true
      - 0..1
    * - <topic_query_proxy>
      - Configures the forwarding of |TQs|. See :ref:`section-TopicQuerySupport`
        for detailed information on how |RS| processes |TQs|.

        The snippet below shows that topic query proxy is enabled in propagation
        mode, which causes the creation of a |TQ| on the route's input for
        each |TQ| that an output's matching |DR| creates.

        Example:
            .. code-block:: xml

                <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
        (:ref:`section-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 |SR| only after the occurrence of
        every three filter events (see :ref:`section-filters`).

        Example:
            .. code-block:: xml

                <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|. |br|
        **Default:** INFINITE (no periodic notification)

        Example:
            .. code-block:: xml

                <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. |br|
        **Default**: True
      - 0..1
    * - <processor>
      - Sets a custom Processor for handling the data forwarding process.
        See :ref:`section-Sdk`.

        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 :ref:`section-Config-StreamPort`.

        Attributes
            - ``name``: uniquely identifies an input configuration. Optional.
      - 0..*
    * - <output>
      - Defines an output topic.
        See :ref:`section-Config-StreamPort`.

        Attributes
            - ``name``: uniquely identifies an output configuration. Optional.

      - 0..*


.. _section-Config-StreamPort:

Input/Output
------------

Inputs and outputs in a |ROUTE| or |TR| have an associated |SR| and |SW|,
respectively. For DDS domains, the |SR| will contain a |DR| and the |SW| will
contain a |DW|. The |DRs| and |DWs| belong to the corresponding |SESSION| |SUB|
and |PUB|.


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 |TR| is a special kind
of |ROUTE| that allows defining mapping between DDS topics only.


.. list-table:: Route Input/Output Tags
    :name: TableInputOutputRouteTags
    :widths: 30 60 10
    :header-rows: 1
    :class: longtable

    * - Tags within <input> and <output> of
        <route>
      - Description
      - Multiplicity
    * - <entity_monitoring>
      - Enables and configures remote monitoring for the |INPUT|/|OUTPUT|. |br|
        See :ref:`section-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. |br|
        **Default:** IMMEDIATE |br|
        See :ref:`section-Config-StreamPort-CreationMode`.
      - 0..1
    * - <on_delete_wait_for_ack_timeout>
      - Specifies a period for which the StreamWriter will wait for acknowledgment
        before its elimination. See
        :link_wait_for_ack:`Waiting for Acknowledgments in a DataWriter, in the Connext
        DDS Core Libraries User's Manual <>`.
        **Default:** 0 (no wait for acknowledgment)

        Example:
            .. code-block:: xml

                <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
        |SR|/|SW|. |br|

        Example:
            .. code-block:: xml

                <property>
                    <value>
                        <element>
                            <name>com.rti.socket.port</name>
                            <value>16556</value>
                        </element>
                    </value>
                </property>
      - 0..1
    * - <transformation> (within <output> only)
      - Sets a data transformation to be applied for every data sample. |br|
        See :ref:`section-Config-DataTransformation`.

        Attributes
            - ``plugin_name``: Name of the plug-in that creates a |TRANSF| 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

.. list-table:: TopicRoute Input/Output Tags
    :name: TableInputOutputTopicRouteTags
    :widths: 30 60 10
    :header-rows: 1
    :class: longtable

    * - 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. |br|
        **Default:** IMMEDIATE |br|
        See :ref:`section-Config-StreamPort-CreationMode`.
      - 0..1
    * - <on_delete_wait_for_ack_timeout>
      - Specifies a period for which the StreamWriter will wait for acknowledgment
        before its elimination. See
        :link_wait_for_ack:`Waiting for Acknowledgments in a DataWriter, in the Connext
        DDS Core Libraries User's Manual <>`.
        **Default:** 0 (no wait for acknowledgment)

        Example:
            .. code-block:: xml

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

        The contents of this tag are specified in the same manner as a
        |CONNEXT| QoS profile. See
        :link_configuring_qos_xml:`Configuring QoS with XML, in the Connext
        DDS Core Libraries User's Manual <>`.

        If the tag is not defined, |RS| will use the |CONNEXT| defaults.
      - 0..1
    * - <content_filter>
      - Defines a SQL content filter for the |DR|.

        Example:
            .. code-block:: xml

                <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. |br|
        See :ref:`section-Config-DataTransformation`.

        Attributes
            - ``plugin_name``: Name of the plug-in that creates a |TRANSF| 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


.. _section-Config-StreamPort-CreationMode:

Creation Modes
^^^^^^^^^^^^^^

The way a |ROUTE| creates its |SRs| and |SWs| and starts reading and writing
data can be configured.

The ``<creation_mode>`` tag in a |ROUTE|'s ``<input>`` and ``<output>`` tags
controls when |SRs|/|SWs| are created.

.. list-table:: Route Creation Mode
    :name: TableRouteCreationMode
    :widths: 40 60
    :header-rows: 1
    :class: longtable

    * - <creation_mode> values
      - Description
    * - IMMEDIATE
      - The |SR|/|SW| 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 |SR| 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. |br|

        For example, a DDS input will not create a |DR| until a
        |DW| for the same topic and partition is discovered on the same
        domain.

        The |SW| 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. |br|

        For example, a DDS output will not create a |DW| until a
        |DR| for the same topic and partition is discovered on the same
        domain.
    * - ON_ROUTE_MATCH
      - The |SR|/|SW| 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 |SR|/|SW| 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 |DWs| in the input domain are deleted, the input
|DR| is deleted.

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

.. code-block:: xml

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

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

.. code-block:: xml

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


.. _section-Config-StreamPort-Types:

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 |DPs| or |CONNECTIONs| in a |DOMAINROUTE|.

.. _section-Config-XmlTypes:

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 :link_userman_types_in_xml:`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.

Example: Type Registration in XML
+++++++++++++++++++++++++++++++++

.. code-block:: 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>

.. _section-Config-TypeDiscovery:

Discovering Types
'''''''''''''''''

If the registered type name is not defined in the configuration file,
|RS| 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 |SR| creation will be tied to the discovery of types in the
input domain and the |SW| 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 |SR| and |SW|, you must set the
``<route_types>`` tag to true.


See :ref:`section-CoreConcepts-Rm-Connection-TypeReg` for more details about
type registration.

Example: Route Creation with Type Obtained from Discovery
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++

.. code-block:: xml

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



.. _section-Config-DataTransformation:

Data Transformation
^^^^^^^^^^^^^^^^^^^

An |OUTPUT| can transform the incoming data using a |TRANSF|. To instantiate a
|TRANSF|:

#. 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
   :ref:`section-Sdk`.

#. Instantiate a |TRANSF| object by specifying a ``<transformation>`` tag inside
   a ``<output>`` or ``<dds_output>``.

:numref:`TableTransformationTag` lists the tags allowed within a
``<transformation>`` tag.

.. list-table:: Transformation Tag
    :name: TableTransformationTag
    :widths: 30 60 10
    :header-rows: 1

    * - Tags within <transformation>
      - Description
      - Multiplicity
    * - <property>
      - A sequence of name-value string pairs that allows you to configure the
        custom |TRANSF| plug-in object. |br|

        Example:
            .. code-block:: xml

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


.. _section-Config-AutoRoute:

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 |AR|. When this happens,
a |ROUTE| is created with the configuration defined by the |AR|.

The generated |ROUTE| has a name constructed as follows:

.. code:: bash

        [auto_route_name]@[stream_name]

where ``[auto_route_name]`` represents the name of the |AR| and ``[stream_name]``
the name of the matching *stream*.

DDS inputs and outputs within an |AR| 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 |ATR| is a special kind of |AR| that defines a mapping between two DDS
domains.

See the following tables for more information on allowable tags:

  - :numref:`TableAutoRouteTag` lists the tags allowed within a ``<auto_route>``.
  - :numref:`TableAutoTopicRouteTag` lists the tags allowed within a ``<auto_topic_route>``.

.. list-table:: AutoRoute Tag
    :name: TableAutoRouteTag
    :widths: 30 60 10
    :header-rows: 1
    :class: longtable

    * - Tags within <auto_route>
      - Description
      - Multiplicity
    * - <entity_monitoring>
      - Enables and configures remote monitoring for the |AR|. |br|
        See :ref:`section-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. |br|

        This option may not be applicable in some adapter implementations in
        which the concept of timestamp is unsupported. |br|
        **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|. |br|
        **Default:** INFINITE (no periodic notification)

        Example:
            .. code-block:: xml

                <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. |br|
        **Default**: True
      - 0..1
    * - <processor>
      - Sets a custom Processor for handling the data forwarding process. |br|
        See :ref:`section-Sdk`.

        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

.. list-table:: AutoTopicRoute Tag
    :name: TableAutoTopicRouteTag
    :widths: 30 60 10
    :header-rows: 1
    :class: longtable

    * - Tags within <auto_topic_route>
      - Description
      - Multiplicity
    * - <entity_monitoring>
      - Enables and configures remote monitoring for the |ATR|. |br|
        See :ref:`section-monitoring`.
      - 0..1
    * - <publish_with_original_info>
      - Writes the data sample as if they came from its original writer. |br|
        Setting this option to true allows having redundant routing services
        and prevents the applications from receiving duplicate samples. |br|
        **Default**: false
      - 0..1
    * - <publish_with_original_timestamp>
      - Indicates if the data samples are written with their original source
        timestamp. |br|
        **Default**: false
      - 0..1
    * - <propagate_dispose>
      - Indicates whether or not disposed samples (NOT_ALIVE_DISPOSE) must be
        propagated by the |TR|. |br|
        This action may be overwritten by the execution of a transformation. |br|
        **Default**: true
      - 0..1
    * - <propagate_unregister>
      - Indicates whether or not disposed samples (NOT_ALIVE_NO_WRITERS) must be
        propagated by the |TR|. |br|
        This action may be overwritten by the execution of a transformation. |br|
        **Default**: true
      - 0..1
    * - <topic_query_proxy>
      - Configures the forwarding of |TQs|. See :ref:`section-TopicQuerySupport`
        for detailed information on how |RS| processes |TQs|.

        The snippet below shows that topic query proxy is enabled in propagation
        mode, which causes the creation of a |TQ| on the route's input for
        each |TQ| that an output's matching |DR| creates.

        Example:
            .. code-block:: xml

                <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 |SR| only after the occurrence of
        every three filter events (see :ref:`section-filters`).

        Example:
            .. code-block:: xml

                <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|. |br|
        **Default:** INFINITE (no periodic notification)

        Example:
            .. code-block:: xml

                <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. |br|
        **Default**: True
      - 0..1
    * - <processor>
      - Sets a custom Processor for handling the data forwarding process. |br|
        See :ref:`section-Sdk`.

        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


.. list-table:: AutoRoute Input/Output Tags
    :name: TableInputOutputAutoRouteTags
    :widths: 30 60 10
    :header-rows: 1
    :class: longtable

    * - Tags within <input> and <output> of
        <auto_route>
      - Description
      - Multiplicity
    * - <entity_monitoring>
      - Enables and configures remote monitoring for the |INPUT|/|OUTPUT|. |br|
        See :ref:`section-monitoring`.
      - 0..1
    * - <allow_stream_name_filter>
      - A stream name filter. |br|
        You may use a comma-separated list to specify more than one filter. |br|
        **Default:** * (allow all)
      - 0..1
    * - <allow_registered_type_name_filter>
      - A registered type name filter. |br|
        You may use a comma-separated list to specify more than one filter. |br|
        **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>``. |br|
        **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>``. |br|
        **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
        :link_wait_for_ack:`Waiting for Acknowledgments in a DataWriter, in the Connext
        DDS Core Libraries User's Manual <>`.
        **Default:** 0 (no wait for acknowledgment)

        Example:
            .. code-block:: xml

                <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. |br|
        **Default:** IMMEDIATE |br|
        See :ref:`section-Config-StreamPort-CreationMode`.
      - 0..1
    * - <property>
      - A sequence of name-value string pairs that allows you to configure the
        |SR|/|SW|. |br|

        Example:
            .. code-block:: xml

                <property>
                    <value>
                        <element>
                            <name>com.rti.socket.port</name>
                            <value>16556</value>
                        </element>
                    </value>
                </property>
      - 0..1

.. list-table:: AutoTopicRoute Input/Output Tags
    :name: TableInputOutputAutoTopicRouteTags
    :widths: 30 60 10
    :header-rows: 1
    :class: longtable

    * - 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|. |br|
        See :ref:`section-monitoring`.
      - 0..1
    * - <allow_topic_name_filter>
      - A |TOPIC| name filter. |br|
        You may use a comma-separated list to specify more than one filter. |br|
        **Default:** * (allow all)
      - 0..1
    * - <allow_registered_type_name_filter>
      - A registered type name filter. |br|
        You may use a comma-separated list to specify more than one filter. |br|
        **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>``. |br|
        **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>``. |br|
        **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
        :link_wait_for_ack:`Waiting for Acknowledgments in a DataWriter, in the Connext
        DDS Core Libraries User's Manual <>`.
        **Default:** 0 (no wait for acknowledgment)

        Example:
            .. code-block:: xml

                <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. |br|
        **Default:** IMMEDIATE |br|
        See :ref:`section-Config-StreamPort-CreationMode`.
      - 0..1
    * - <datareader_qos> or <datawriter_qos>
      - Sets the *DataReader* or *DataWriter* QoS. |br|

        The contents of this tag are specified in the same manner as a
        |CONNEXT| QoS profile. See
        :link_configuring_qos_xml:`Configuring QoS with XML, in the Connext
        DDS Core Libraries User's Manual <>`.

        If the tag is not defined, |RS| will use the |CONNEXT| defaults.
      - 0..1
    * - <content_filter>
      - Defines a SQL content filter for the |DR|.

        Example:
            .. code-block:: xml

                <content_filter>
                    <expression>
                        x &gt; 100
                    </expression>
                </content_filter>
      - 0..1 (within <input> only)

.. _section-Config-Plugins:

Plugins
-------

All the pluggable components specific to |RS| are configured within the
``<plugin_library>`` tag. :numref:`TablePluginLibraryTag` describes the
available tags.

Plug-ins are categorized and configured based on the
source language. |RS| supports C/C++ and  Java plug-ins.
See :ref:`section-sdk` for further information on developing |RS| plug-ins.


.. list-table:: Configuration tags for plug-in libraries
    :name: TablePluginLibraryTag
    :widths: 30 60 10
    :header-rows: 1
    :class: longtable

    * - Tags within <plugin_library>
      - Description
      - Multiplicity
    * - <adapter_plugin>
      - Specifies a C/C++ |ADAPTER| plug-in. |br|
        See :numref:`TableNativePluginTag`.

        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 :numref:`TableDomainRouteTag`.
      - 0..*
    * - <java_adapter_plugin>
      - Specifies a Java |ADAPTER| plug-in. |br|
        See :numref:`TableJavaPluginTag`.

        Attributes
            (See ``<adapter_plugin>``)

      - 0..*
    * - <transformation_plugin>
      - Specifies a C/C++ |TRANSF| plug-in. |br|
        See :numref:`TableNativePluginTag`.

        Attributes
            - ``name``: uniquely identifies an |TRANSF| 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 :ref:`section-Config-Route`.
      - 0..*
    * - <processor_plugin>
      - Specifies a C/C++ |PROCESSOR| plug-in. |br|
        See :numref:`TableNativePluginTag`.

        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 :ref:`section-Config-Route`.
      - 0..*

.. _section-Config-EnableDistLog:

Enabling Distributed Logger
===========================

|RS| provides integrated support for |RTI_DISTLOG|.

|DISTLOG| is included in |CONNEXT| but it is not supported on all platforms;
see the :link_platform_notes:`Connext DDS Core Libraries Platform Notes <>`
to see which platforms support |DISTLOG|.

When you enable |DISTLOG|, |RS| 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 |DISTLOG|, use the tag ``<distributed_logger>`` within
``<adminstration>``. For example:

.. code-block:: xml

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

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

For the list of elements that configure |DISTLOG| see
:ref:`section-Config-Administration`. For more details about |DISTLOG|, see
:link_distlog_services:`Enabling Distributed Logger in RTI Services,
in the Connext DDS Core Libraries User's Manual <>`.


.. _section-Config-ExtensibleTypes:

Support for Extensible Types
============================

|RS| includes partial support for the
`"Extensible and Dynamic Topic Types for DDS" specification
<http://www.omg.org/spec/DDS-XTypes>`_ from the Object Management Group (OMG).
This section assumes that you are familiar with Extensible Types and you have read
the |CONNEXT| *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| *Extensible Types Guide*.
- The TypeConsistencyEnforcementQosPolicy can be specified on a per-topic-route
  basis, in the same way as other QoS policies.
- Within a |DP|, a topic cannot be associated with more than one type version.
  This prevents the same |DP| from having two |ROUTE| |DR| or |DW| with
  different versions of a type for the same *Topic*. To achieve this behavior,
  create two different |DP|, 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 |TRANSF| 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|.

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

.. code-block:: c

        struct A {
          long x;
        };

        struct B {
            long x;
            long y;
        };

.. list-table:: Forwarded data when type in |TR| is not extended
    :name: TableExampleExtTypes1
    :widths: 20 40 20
    :header-rows: 1

    * - Samples published by two |DWs| of types A and B, respectively
      - Samples forwarded by a |TR| 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]

.. list-table:: Forwarded data when type in |TR| is extended
    :name: TableExampleExtTypes2
    :widths: 20 40 20
    :header-rows: 1

    * - Samples published by two |DWs| of types A and B, respectively
      - Samples forwarded by a |TR| 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]

.. _section-Config-EnablingLargedataFeatures:

Support for RTI FlatData and Zero Copy Transfer Over Shared Memory
==================================================================

|RS| 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, |RS| will ignore the type annotations for these
    capabilities and will communicate through the regular serialization and
    deserialization paths.

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

For further information about these capabilities, see
:link_userman_largedata:`Sending Large Data, in the Connext DDS User Libraries User's Manual <>`.


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


.. code-block:: xml

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