.. include:: vars.rst

.. _section-configuration:

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

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

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

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

Terms to Know
=============

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

* A |SERVICE| entity refers to an execution of |RS|.
* A |DOMAINROUTE| defines a two-way mapping between two data domains
  (DDS, MQTT, AMQP, etc.).
* A |SESSION| defines a safe, threaded context for |ROUTEs|. A |ROUTE| can be
  processed by a single thread a time. If the session defines a thread pool,
  |ROUTEs| can be processed concurrently.
* A |ROUTE| defines a mapping between *input streams* and *output streams*
  belonging to any of the data domains defined in a |DOMAINROUTE|. For example,
  in a |ROUTE| between DDS and MQTT, the input streams will be DDS topics and
  the output streams will be MQTT subscriptions.
* An |AR| defines a set of potential |ROUTEs| that can be instantiated based on
  deny/allow filters on the stream name and registered type name.
* A |TRANSF| is a pluggable component that changes data from an input stream
  to an output stream.
* An |ADAPTER| is a pluggable component that allows |RS| to consume and produce
  data for different data domains. By default, |RS| is distributed with a
  builtin DDS adapter.

.. _section-how-to-load-the-xml-configuration:

How to Load the XML Configuration
=================================

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

- ``[working directory]/USER_ROUTING_SERVICE.xml``
  This file is loaded automatically if it exists.
- ``[NDDSHOME]/resource/xml/RTI_ROUTING_SERVICE.xml``
  This file is loaded automatically if it exists.
- File specified using the command-line parameter ``-cfgFile``.

.. note::

    ``[working directory]`` indicates the path to the current working
    directory from which you run |RS|.

    The tag ``[NDDSHOME]`` indicates the path to your |CONNEXT| installation.

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

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

.. code-block:: xml

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

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

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

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

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

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

.. _section-xml-syntax-and-validation:

XML Syntax and Validation
=========================

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

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

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

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

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

.. code-block:: xml

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

.. note::

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

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

.. figure:: static/TopLevelRoutingServiceConfig.png
    :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 :litrep:`<dds>`
      - Description
      - Multiplicity
    * - :litrep:`<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..*
    * - :litrep:`<types>`
      - Defines types that can be used by |RS|. |br|
        See :numref:`section-Config-RouteTypes`.
      - 0..1
    * - :litrep:`<plugin_library>`
      - Specifies a library of |RS| plugins. |br|
        Available plug-ins are *Adapters*, *Transformations* and *Processors*.
        See :numref:`section-Config-Plugins`.
      - 0..*
    * - :litrep:`<routing_service>`
      - Specifies a |RS| configuration. |br|
        See :numref:`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>

      - 1..*

.. _section-config-routing-service:

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

A configuration file must have at least one |SERVICE_TAG| tag. This
tag is used to configure an execution of |RS|. A configuration file may
contain multiple |SERVICE_TAG| tags.

When you start |RS|, you can specify which |SERVICE_TAG| tag
to use to configure the service using the ``-cfgName`` command-line parameter.

Because a configuration file may contain multiple |SERVICE_TAG|
tags, one file can be used to configure multiple |RS| executions.

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

.. figure:: static/RoutingServiceTagStructure.png
    :alt: |RS| Tag
    :name: FigureRoutingServiceTag
    :align: center
    :width: 300px

    |RS| Tag Structure

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

    * - Tags within :litrep:`<routing_service>`
      - Description
      - Multiplicity
    * - :litrep:`<annotation>`
      - Contains a <documentation> tag that can be used to provide a
        configuration description.
      - 0..1
    * - :litrep:`<administration>`
      - Enables and configures remote administration. |br|
        See :numref:`section-config-administration` and
        :numref:`section-Admin`.
      - 0..1
    * - :litrep:`<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 :numref:`section-config-monitoring` and :numref:`section-monitoring`.
      - 0..1
    * - :litrep:`<entity_monitoring>`
      - Enables and configures remote monitoring for the service entity. |br|
        See :numref:`section-config-monitoring-inheritance` and
        :numref:`section-monitoring`.
      - 0..1
    * - :litrep:`<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
    * - :litrep:`<domain_route>`
      - Defines a mapping between two or more data domains. |br|
        See :numref:`section-config-DomainRoute`.

        Attributes

            - ``name``: uniquely identifies a |DR| 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..1

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 :numref:`section-Admin`.

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

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

    * - Tags within :litrep:`<administration>`
      - Description
      - Multiplicity
    * - :litrep:`<enabled>`
      - Enables/disables administration. |br|
        **Default:** true
      - 0..1
    * - :litrep:`<domain_id>`
      - Specifies which domain ID |RS| will use to enable remote
        administration. |br|
      - 0..1
    * - :litrep:`<participant_qos>`
      - Configures the |DP| QoS for remote administration. |br|
        If the tag is not defined, |RS| will use the |CONNEXT|
        defaults.
      - 0..1
    * - :litrep:`<publisher_qos>`
      - Configures the |PUB| QoS for remote administration. |br|
        If the tag is not defined, |RS| will use the |CONNEXT|
        defaults.
      - 0..1
    * - :litrep:`<subscriber_qos>`
      - Configures the |SUB| QoS for remote administration. |br|
        If the tag is not defined, |RS| will use the |CONNEXT|
        defaults.
      - 0..1
    * - :litrep:`<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
    * - :litrep:`<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
    * - :litrep:`<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
    * - :litrep:`<autosave_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
    * - :litrep:`<save_path>`
      - Specifies the file that will contain the saved configuration. |br|
        A ``<save_path>`` must be specified if you want to use the save
        command. If the  specified file already exists, the file will be
        overwritten when save is executed. |br|
        **Default:** [CURRENT DIRECTORY].
      - 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 :numref:`section-monitoring`.

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

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

    * - Tags within :litrep:`<monitoring>`
      - Description
      - Multiplicity
    * - :litrep:`<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.
        **Default:** true
      - 0..1
    * - :litrep:`<domain_id>`
      - Specifies which domain ID |RS| will use to enable remote
        monitoring. |br|
      - 1
    * - :litrep:`<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
    * - :litrep:`<publisher_qos>`
      - Configures the |PUB| QoS for remote monitoring. |br|
        If the tag is not defined, |RS| will use the |CONNEXT|
        defaults.
      - 0..1
    * - :litrep:`<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
    * - :litrep:`<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
    * - :litrep:`<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 :litrep:`<entity_monitoring>`
      - Description
      - Multiplicity
    * - :litrep:`<enabled>`
      - Enables/disables remote monitoring for a given entity. |br|
        If general monitoring is disabled, this value is ignored. |br|

        **Default:** true
      - 0..1
    * - :litrep:`<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
    * - :litrep:`<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.


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

    * - Tags within :litrep:`<domain_route>`
      - Description
      - Multiplicity
    * - :litrep:`<entity_monitoring>`
      - Enables and configures remote monitoring for the |DOMAINROUTE|. |br|
        See :numref:`section-monitoring`.
      - 0..1
    * - :litrep:`<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..*
    * - :litrep:`<participant>`
      - Applicable to DDS domains. |br|
        Configures a DDS adapter |DP|. |br|
        See :numref:`TableParticipantTag`.
      - 0..*
    * - :litrep:`<session>`
      - Defines a multi-threaded context in which data is routed according to
        specified routes. See :numref:`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 :litrep:`<connection>`
      - Description
      - Multiplicity
    * - :litrep:`<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
    * - :litrep:`<registered_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 :numref:`section-Config-Route`.
      - 0..*


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

    * - Tags within :litrep:`<participant>`
      - Description
      - Multiplicity
    * - :litrep:`<domain_id>`
      - Sets the domain ID associated with the |DP|. |br|
        **Default:** 0 |br| |br|
      - 0..1
    * - :litrep:`<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|: <service name>.<domain route name>#[1|2]"
        (for example "RTI |RS_HEADING|: MyService.MyDomainRoute#1").

        .. note::

            Changing the default participant name may prevent
            |RS| from being detected by Admin Console.

        You can use a
        ``<participant_qos>`` tag inside a ``<qos_library>/<qos_profile>``
        previously defined in your configuration file by referring to it, and
        also override any value:

        Example:
            .. code-block:: xml

                <participant_qos base_name="MyLibrary::MyProfile">
                    <discovery>
                        <initial_peers>
                           <element>udpv4://192.168.1..12</element>
                           <element>shmem://</element>
                        </initial_peers>
                    </discovery>
                </participant_qos>

        See :link_configuring_qos_xml:`Configuring QoS with XML, in the Connext
        DDS Core Libraries User's Manual <>`.
      - 0..1
    * - :litrep:`<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
    * - :litrep:`<registered_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 :numref:`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>

        <articipant 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 :litrep:`<session>`
      - Description
      - Multiplicity
    * - :litrep:`<entity_monitoring>`
      - Enables and configures remote monitoring for the |SESSION|. |br|
        See :numref:`section-monitoring`.
      - 0..1
    * - :litrep:`<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
    * - :litrep:`<periodic_action>`
      - Enables the periodic event dispatching to Processors. |br|
        If enabled, the |SESSION| will wake up and notify the installed Processor
        specified period. |br|
        **Default:** INFINITE (no periodic notification)
      - 0..1
    * - :litrep:`<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
    * - :litrep:`<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
    * - :litrep:`<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..*
    * - :litrep:`<topic_route>` or :litrep:`<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 :numref:`section-Config-Route`.
      - 0..*
    * - :litrep:`<auto_topic_route>` or :litrep:`<auto_route>`
      - Defines a factory for |ROUTE| based on type and stream filters. |br|
        See :numref:`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 :litrep:`<route>`
      - Description
      - Multiplicity
    * - :litrep:`<entity_monitoring>`
      - Enables and configures remote monitoring for the |ROUTE|. |br|
        See :numref:`section-monitoring`.
      - 0..1
    * - :litrep:`<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 :numref:`section-Config-TypeDiscovery`. |br|
        **Default:** false
      - 0..1
    * - :litrep:`<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
    * - :litrep:`<processor>`
      - Sets a custom Processor for handling the data forwarding process. |br|
        See :numref:`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
    * - :litrep:`<dds_input>`
      - Only applicable to DDS inputs. Defines an input topic.
        See :numref:`section-Config-StreamPort`.

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

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

        Attributes
            - ``name``: uniquely identifies an input configuration. Optional.
      - 0..*
    * - :litrep:`<output>`
      - Only applicable to non-DDS outputs. Defines an output stream.
        See :numref:`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 :litrep:`<topic_route>`
      - Description
      - Multiplicity
    * - :litrep:`<entity_monitoring>`
      - Enables and configures remote monitoring for the |TR|.
        See :numref:`section-monitoring`.
      - 0..1
    * - :litrep:`<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 :numref:`section-Config-TypeDiscovery`.
        |br|
        **Default:** false
      - 0..1
    * - :litrep:`<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
    * - :litrep:`<publish_with_original_timestamp>`
      - Indicates if the data samples are written with their original source
        timestamp. |br|
        **Default**: false
      - 0..1
    * - :litrep:`<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
    * - :litrep:`<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
    * - :litrep:`<topic_query_proxy>`
      - Configures the forwarding of |TQs|. See :numref:`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
    * - :litrep:`<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 :numref:`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
    * - :litrep:`<processor>`
      - Sets a custom Processor for handling the data forwarding process.
        See :numref:`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
    * - :litrep:`<input>`
      - Defines an input topic.
        See :numref:`section-Config-StreamPort`.

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

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

      - 0..*


.. _section-Config-RouteTypes:

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

.. _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 RTI Connext DDS
  Core Libraries User's Manual <>`.
- Register it in the ``<connection>``/``<participant>`` where you will use it.
- Refer to it in the domain route(s) that will use it.

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

.. code-block:: xml

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

.. _section-Config-TypeDiscovery:

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

If a |ROUTE| refers to types that are not defined in the configuration file,
|RS| has to discover their type representation (e.g. typecode). A |ROUTE|
cannot be created without the type representation information.

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.


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-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 :litrep:`<input>` and :litrep:`<output>` of
        :litrep:`<route>`
      - Description
      - Multiplicity
    * - :litrep:`<entity_monitoring>`
      - Enables and configures remote monitoring for the |INPUT|/|OUTPUT|. |br|
        See :numref:`section-monitoring`.
      - 0..1
    * - :litrep:`<stream_name>`
      - Specifies the stream name.
      - 1
    * - :litrep:`<registered_type_name>`
      - Specifies the registered type name of the stream.
      - 1
    * - :litrep:`<creation_mode>`
      - Specifies when to create the StreamReader/StreamWriter. |br|
        **Default:** IMMEDIATE |br|
        See :numref:`section-Config-StreamPort-CreationMode`.
      - 0..1
    * - :litrep:`<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
    * - :litrep:`<transformation>` (within :litrep:`<output>` only)
      - Sets a data transformation to be applied for every data sample. |br|
        See :numref:`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 :litrep:`<input>` and :litrep:`<output>` 
        (in :litrep:`<topic_route>`) and :litrep:`<dds_input>` and
        :litrep:`<dds_output>` (in :litrep:`<route>`)
      - Description
      - Multiplicity
    * - :litrep:`<topic_name>`
      - Specifies the topic name.
      - 1
    * - :litrep:`<registered_type_name>`
      - Specifies the registered type name of the topic.
      - 1
    * - :litrep:`<creation_mode>`
      - Specifies when to create the StreamReader/StreamWriter. |br|
        **Default:** IMMEDIATE |br|
        See :numref:`section-Config-StreamPort-CreationMode`.
      - 0..1
    * - :litrep:`<datareader_qos>` or :litrep:`<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
    * - :litrep:`<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
    * - :litrep:`<transformation>`` (within :litrep:`<output>` only)
      - Sets a data transformation to be applied for every data sample. |br|
        See :numref:`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

    * - :litrep:`<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-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
   :numref:`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 :litrep:`<transformation>`
      - Description
      - Multiplicity
    * - :litrep:`<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


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

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 :litrep:`<auto_route>`
      - Description
      - Multiplicity
    * - :litrep:`<entity_monitoring>`
      - Enables and configures remote monitoring for the |SESSION|. |br|
        See :numref:`section-monitoring`.
      - 0..1
    * - :litrep:`<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
    * - :litrep:`<processor>`
      - Sets a custom Processor for handling the data forwarding process. |br|
        See :numref:`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
    * - :litrep:`<dds_input>`
      - Only applicable to DDS inputs. Defines an input topic.
      - 0..*
    * - :litrep:`<dds_output>`
      - Only applicable to DDS outputs. Defines an output topic.
      - 0..*
    * - :litrep:`<input>`
      - Only applicable to non-DDS inputs. Defines an input stream.
      - 0..*
    * - :litrep:`<output>`
      - Only applicable to non-DDS outputs. Defines an output stream.
      - 0..*

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

    * - Tags within :litrep:`<auto_topic_route>`
      - Description
      - Multiplicity
    * - :litrep:`<entity_monitoring>`
      - Enables and configures remote monitoring for the |SESSION|. |br|
        See :numref:`section-monitoring`.
      - 0..1
    * - :litrep:`<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
    * - :litrep:`<publish_with_original_timestamp>`
      - Indicates if the data samples are written with their original source
        timestamp. |br|
        **Default**: false
      - 0..1
    * - :litrep:`<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
    * - :litrep:`<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
    * - :litrep:`<topic_query_proxy>`
      - Configures the forwarding of |TQs|. See :numref:`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
    * - :litrep:`<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 :numref:`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
    * - :litrep:`<processor>`
      - Sets a custom Processor for handling the data forwarding process. |br|
        See :numref:`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
    * - :litrep:`<input>`
      - Defines an input topic.
      - 0..*
    * - :litrep:`<output>`
      - Defines an output topic.
      - 0..*


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

    * - Tags within :litrep:`<input>` and :litrep:`<output>` of
        :litrep:`<auto_route>`
      - Description
      - Multiplicity
    * - :litrep:`<entity_monitoring>`
      - Enables and configures remote monitoring for the |INPUT|/|OUTPUT|. |br|
        See :numref:`section-monitoring`.
      - 0..1
    * - :litrep:`<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
    * - :litrep:`<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
    * - :litrep:`<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
    * - :litrep:`<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
    * - :litrep:`<creation_mode>`
      - Specifies when to create the StreamReader/StreamWriter. |br|
        **Default:** IMMEDIATE |br|
        See :numref:`section-Config-StreamPort-CreationMode`.
      - 0..1
    * - :litrep:`<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 :litrep:`<input>` and :litrep:`<output>`
        (in :litrep:`<auto_topic_route>`) :litrep:`<dds_input>` and
        :litrep:`<dds_output>` (in :litrep:`<auto_route>`)
      - Description
      - Multiplicity
    * - :litrep:`<entity_monitoring>`
      - Enables and configures remote monitoring for the |INPUT|/|OUTPUT|. |br|
        See :numref:`section-monitoring`.
      - 0..1
    * - :litrep:`<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
    * - :litrep:`<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
    * - :litrep:`<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
    * - :litrep:`<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
    * - :litrep:`<creation_mode>`
      - Specifies when to create the StreamReader/StreamWriter. |br|
        **Default:** IMMEDIATE |br|
        See :numref:`section-Config-StreamPort-CreationMode`.
      - 0..1
    * - :litrep:`<datareader_qos>` or :litrep:`<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
    * - :litrep:`<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

.. _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 :numref:`section-sdk` for further infomration 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 :litrep:`<plugin_library>`
      - Description
      - Multiplicity
    * - :litrep:`<adapter_plugin>`
      - Specifies a C/C++ |ADAPTER| plug-in.

        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..*
    * - :litrep:`<java_adapter_plugin>`
      - Specifies a Java |ADAPTER| plug-in.

        Attributes (See ``<adapter_plugin>``).

      - 0..*
    * - :litrep:`<transformation_plugin>`
      - Specifies a C/C++ |TRANSF| plug-in.

        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 :numref:`section-Config-Route`.
      - 0..*
    * - :litrep:`<processor_plugin>`
      - Specifies a C/C++ |PROCESSOR| plug-in.

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


:numref:`TableNativePluginTag` and :numref:`TableJavaPluginTag` describe the
configuration of each different type of plug-in.


.. list-table:: Configuration tags for C/C++ plug-ins.
    :name: TableNativePluginTag
    :widths: 30 60 10
    :header-rows: 1
    :class: longtable

    * - Tags within :litrep:`<adapter_plugin>`,
        ``<transformation_plugin>``,
        ``<processor_plugin>``
      - Description
      - Multiplicity
    * - :litrep:`<dll>`
      - Shared library containing the implementation of the adapter plugin. |br|
        This tag may specify the exact name of the file (for example,
        lib/libmyadapter.so) or a general name (no file extension).

        If no extension is provided, the path will be completed based on the
        running platform. For example, assuming a value for this tag of
        dir/myplugin:

            - UNIX-based systems: **dir/libmyplugin.so**
            - Windows systems: **dir/myplugin.dll**

        If the library specified in this tag cannot be loaded (because the
        environment library path is not pointing to the path where the library
        is located), |RS| will look for the library in <NDDSHOME>/lib/<architecture>.
      - 1
    * - :litrep:`<create_function>`
      - This tag must contain the name of the function used to create the
        plugin instance. The function synmbol must be present in the shared
        library specified in ``<dll>``.
      - 1
    * - :litrep:`<property>`
      - A sequence of name-value string pairs that allows you to configure the
        plug-in instance. |br|

        Example:
            .. code-block:: xml

                <property>
                    <value>
                        <element>
                            <name>myplugin.user_name</name>
                            <value>myusername</value>
                        </element>
                    </value>
                </property>
      - 0..1

.. list-table:: Configuration tags for Java plug-ins.
    :name: TableJavaPluginTag
    :widths: 30 60 10
    :header-rows: 1
    :class: longtable

    * - Tags within :litrep:`<java_adapter_plugin>`
      - Description
      - Multiplicity
    * - :litrep:`<class_name>`
      - Name of the class that implements the plugin. |br|

        For example: com.myadapters.CustomAdapter |br|

        The classpath required to run the Java plugin must be part of the
        |RS| JVM configuration. See :numref:`TableRoutingServiceTag` for
        additional information on JVM creation and configuration.
      - 1
    * - :litrep:`<property>`
      - A sequence of name-value string pairs that allows you to configure the
        plug-in instance. |br|

        Example:
            .. code-block:: xml

                <property>
                    <value>
                        <element>
                            <name>myplugin.user_name</name>
                            <value>myusername</value>
                        </element>
                    </value>
                </property>
      - 0..1


.. _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
:numref:`section-Config-Administration`. For more details about |DISTLOG|, see
:link_distlog_services:`Enabling Distributed Logger in RTI Services <>`.


.. _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| *Core Libraries Getting Started Guide Addendum for Extensible Types*.

- |TRs| 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| *Getting Started Guide Addendum for Extensible
  Types*.
- The TypeConsistencyEnforcementQosPolicy can be specified on a per-topic-route
  basis, in the same way as other QoS policies.
- Within a |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 a |TR| input is the version that is passed to the output
(or to a transformation). The |TR| can subscribe to different-but-compatible
types, but those samples are translated to the |TR| input type.

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 the
:link_userman_largedata:`Sending Large Data <>` section in the
|RTI_CONNEXT| *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">
                <participant_qos>
                    <discovery>
                        <initial_peers>
                            <element>shmem://</element>
                        </initial_peers>
                    </discovery>
                    <transport_builtin>
                        <mask>SHMEM</mask>
                    </transport_builtin>
                </participant_qos>
            </qos_profile>
        </qos_library>

        <routing_service name="FlatDataWithZeroCopy">

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

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