.. include:: ../../../router.1.0/srcDoc/vars.rst

.. _section-replay_configuration:

Configuration
=============

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


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

How to Load the XML Configuration
---------------------------------

*Replay Service* loads its XML configuration from multiple locations.
Here are the various sources of configuration files, listed in load
order:

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

.. note::

    ``[working directory]`` indicates the path to the current working
    directory from which you run the *Replay Service*.

    ``[NDDSHOME]`` indicates the path to your *Connext DDS* installation
    (see :numref:`section-doc-paths`).

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" encoding="UTF-8"?>
    <!-- All of our files start with a dds tag -->
    <dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
         xsi:noNamespaceSchemaLocation="../schema/rti_replay_service.xsd">
        <!-- Qos Library -->
        <qos_library name="MyQosLib">
            <qos_profile name="DurableQos">
                <datawriter_qos>
                    <reliability>
                        <kind>RELIABLE_RELIABILITY_QOS</kind>
                    </reliability>
                </datawriter_qos>
            </qos_profile>
        </qos_library>

        <!-- Replay service instance -->
        <replay_service name="MyReplayService">
            <!-- Input file to use when replaying -->
            <storage>
                <sqlite>
                    <database_dir>.</database_dir>
                </sqlite>
            </storage>

            <!-- Select the begin and end time of the data to replay -->
            <data_selection>
                <time_range>
                    <begin_time>
                        <sec>200</sec>
                        <nanosec>2000000</nanosec>
                    </begin_time>
                </time_range>
            </data_selection>

            <!-- Domain Participant for replaying data -->
            <domain_participant name="Participant0">
                <domain_id>0</domain_id>
            </domain_participant>

             <!-- The session that is replaying the data.  Contains configuration
                  for publishers, threading, group of topics to replay.  -->
            <session name="Session" default_participant_ref="Participant0">
                <!-- Topics to replay in this session -->
                <topic_group name="RecordAll">
                    <!-- Topics to replay -->
                    <allow_topic_name_filter>*</allow_topic_name_filter>
                </topic_group>
            </session>
        </replay_service>    
    </dds>


.. _section-replay-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, *Replay Service* relies on an XSD
file that describes the format of the XML content. We recommend
including a reference to this document in the XML file that contains the
service’s configuration; this document provides helpful features in code
editors such as Visual Studio®, Eclipse®, and NetBeans®, including
validation and auto-completion while you are editing the XML file.

The XSD definitions of the XML elements are in
``$NDDSHOME/resource/schema/rti_replay_service.xsd``.
(See :numref:`section-doc-paths` for the path to NDDSHOME.)

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

    <dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../schema/rti_recording_service.xsd">
        <!-- ... -->
    </dds>

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

XML Tags for Configuring Replay Service
---------------------------------------

This section describes the XML tags you can use in a *Replay Service*
configuration file. :numref:`FigureReplayTopLevelTag` and
:numref:`TableReplayTopLevelTag` describe the
top-level tags allowed within the root ``<dds>`` tag.

.. figure:: ../static/ReplayTopLevelTags.png
    :alt: Top-Level Tags in Replay Service's Configuration File
    :name: FigureReplayTopLevelTag
    :align: center
    :figwidth: 50 %

    Top-level Tags in the *Replay* Configuration File

.. list-table:: Top-Level Tags in Replay Service's Configuration File
    :name: TableReplayTopLevelTag
    :widths: 20 50 10
    :header-rows: 1
    :class: longtable

    * - Tags within :litrep:`<dds>`
      - Description
      - Multiplicity
    * - :litrep:`<qos_library>`
      - Specifies a QoS library and profiles. The contents of this tag are
        specified in the same manner as for a *Connext DDS* QoS profile
        file — see :link_xml_qos_config:`Configuring QoS with XML, in
        the RTI Connext DDS Core Libraries User's Manual <>`.
      - 0..*
    * - :litrep:`<types>`
      - Defines types that can be used by *Replay Service*. This tag is needed
        if data types are not available through discovery, or when using a
        transformation. The type description is done using the
        *Connext DDS* 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 <>`.
      - 0..*
    * - :litrep:`<plugin_library>`
      - Contains a list of libraries that can be used to:

         - Plug in custom storage, such as custom databases. For more
           information, see :numref:`section-replay-custom-storage`.
         - Transform data after it is received from *Connext DDS* and before
           it is placed in storage. For more information, see
           :link_router_manual_config_transformation:`Data Transformation,
           in the RTI Routing Service User’s Manual. <>`.

           See  :numref:`section-Record-Config-Plugins`

      - 0..*
    * - :litrep:`<replay_service>`
      - **Required.** |br|
        Specifies a *Replay Service* configuration.
        See :numref:`section-replay_config_replay_service_tag`.

        Attributes
            - ``name``: uniquely identifies a service configuration. **Required**.

        Example
            .. code-block:: xml

                <replay_service name="ReplayAll">
                    <!-- your service settings ... -->
                </replay_service>

      - 1..*



.. _section-replay_config_replay_service_tag:

Replay Service Tag
------------------

A configuration file must have at least one ``<replay_service>`` tag. This
tag is used to configure an execution of *Replay Service*.

A configuration file may contain multiple ``<replay_service>`` tags. When
you start *Replay Service*, you can specify which ``<replay_service>``
tag to use to configure the service using the -cfgName command-line
parameter. This means one file can be used to configure multiple
*Replay Service* executions.

:numref:`FigureConfigureReplayServiceTag` and :numref:`ReplayServiceTag`
describe the tags allowed within a ``<replay_service>`` tag.

.. figure:: ../static/ReplayServiceTags.png
    :alt: Tags used to configure a *Replay Service* instance
    :name: FigureConfigureReplayServiceTag
    :align: center
    :figwidth: 50 %

    Tags used to configure a *Replay Service* instance


.. list-table:: Replay Service Tags in Replay Service's Configuration File
    :name: ReplayServiceTag
    :widths: 20 50 10
    :header-rows: 1
    :class: longtable

    * - Tags within :litrep:`<replay_service>`
      - Description
      - Multiplicity
    * - :litrep:`<administration>`
      - Enables remote administration. |br|
        When administration is enabled, monitoring is also enabled by
        default. |br|
        See :numref:`section-replay_config_administration_tag`.
      - 0..1
    * - :litrep:`<monitoring>`
      - Enables monitoring for *Replay Service*, including statistics.
        See :numref:`section-replay_config_monitoring_tag`.
      - 0..1
    * - :litrep:`<storage>`
      - Describes how the data will be loaded from storage. |br|
        See :numref:`section-replay_config_storage_tag`. |br|
        If this is not specified, data will be loaded from the current
        working directory.
      - 0..1
    * - :litrep:`<playback>`
      - Specifies the timing rules for how data is played back.
        See :numref:`section-replay_config_playback_tag`.
      - 0..1
    * - :litrep:`<data_selection>`
      - Enables selection of a subset of data to replay. Supports selecting
        replay data by time (or tagged time).
        See :numref:`section-replay_config_dataselection_tag`.
      - 0..1
    * - :litrep:`<domain_participant>`
      - **Required**. |br|
        Specifies a DomainParticipant to use to replay data. The domain ID
        specified for the DomainParticipant will be used to determine which
        domains to select from the database and (combined with the domainIdBase)
        which domains to replay the data into. For example, if data was originally
        recorded in domains 0 and 1, and you want to replay in domains 50 and 51,
        you must:

            - Specify ``<domain_participant>`` tags with ``<domain_id>``
              tags set to 0 and 1 in your configuration file.
            - Use ``-domainIdBase 50`` to specify that the domain IDs the
              data will actually be written into is offset by 50.

        See :numref:`section-replay_config_domainparticipant_tag`.

        Attributes:
            - ``name``: Uniquely defines a DomainParticipant. **Required**.

        Example
            .. code-block:: xml

                <domain_participant name="Participant3">
                    <domain_id>3</domain_id>
                    <!-- Participant QoS -->
                </domain_participant>
      - 1..*

    * - :litrep:`<session>`
      - **Required**. |br|
        Active component of *Replay Service* for replaying data. Contains
        one or more threads that can be used for replay.
        See :numref:`section-replay_config_session_tag`.

        Attributes
            - ``name``: Uniquely defines a replay session. **Required**.
            - ``default_participant_ref``: Specifies a default
              DomainParticipant to be used by topics and topic groups
              belonging to this replay session. Children can override this by
              specifying their own participant.

        Example
            .. code-block:: xml

              <session name="Session" default_participant_ref="Participant3">
                  <!-- ... topics /   groups of topics to record -->
              </session>
      - 1..*


Example:  Specify a Replay Service Configuration in XML
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: xml

    <dds>
        <replay_service name="MyReplayService">
            <!-- ... Required entities -->
        </replay_service>
    </dds>

Starting a *Replay Service* with the following command will use the
``<replay_service>`` tag with the name "MyReplayService".

.. code-block:: bash

    $NDDSHOME/bin/rtireplayservice -cfgFile file.xml -cfgName MyReplayService


*Replay Service* uses the Topic names and domain IDs specified in the
configuration file to determine which data to replay. To replay data into
a different domain than the one it was recorded from, use the
``-domainIdBase`` command-line parameter to change the output domain ID.  

.. figure:: ../static/ReplayDomainUsage.png
    :alt: Domain ID Mapping Between the XML, the Database, and the DDS Domain
    :name: FigureDomainXMLDatabaseReplay
    :align: center

    The domain ID specified inside a DomainParticipant, in combination with
    the Topic name, is used to load data from recorded tables. In this case,
    the DomainParticipant’s domain ID is set to 3.
    The ``topic_group`` specifies all topics.

.. figure:: ../static/ReplayDomainUsageWithBase.png
    :alt: -domainIdBase on Command Line Affects Output DDS Domain
    :name: FigureDomainIdBaseReplay
    :align: center

    To replay data in a different domain than where it was
    recorded, use the ``-domainIdBase`` command-line parameter to
    specify a base ID for the replay domain. Here, by specifying
    a domainIdBase of 2, all Topics will be replayed in their original
    domain, plus 2.


.. _section-replay_config_administration_tag:

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

The ``<administration>`` tag allows you to enable and configure remote
administration of *Replay Service*, including stopping, starting, and
pausing replay.

See :numref:`section-replay_administration` for details on using
remote administration.

.. list-table:: Administration Tags in Replay Service's Configuration File
    :name: ReplayTableAdministrationTag
    :widths: 20 50 10
    :header-rows: 1
    :class: longtable

    * - Tags within :litrep:`<administration>`
      - Description
      - Multiplicity
    * - :litrep:`<domain_id>`
      - Domain ID used for remote administration.  Also used for monitoring
        by default.
      - 0..1
    * - :litrep:`<participant_qos>`
      - QoS used by the administration DomainParticipant.
        If the tag is not defined, *Connext DDS* defaults will be used.
      - 0..1
    * - :litrep:`<publisher_qos>`
      - QoS used by the administration Publisher.
        If the tag is not defined, *Connext DDS* defaults will be used.
      - 0..1
    * - :litrep:`<subscriber_qos>`
      - QoS used by the administration Subscriber.
        If the tag is not defined, *Connext DDS* defaults will be used.
      - 0..1
    * - :litrep:`<datawriter_qos>`
      - QoS used by administration DataWriter(s).
        If the tag is not defined, *Connext DDS* defaults will be used,
        with the following changes:

          - history.kind = DDS_KEEP_ALL_HISTORY_QOS
          - resource_limits.max_samples = 32

      - 0..1
    * - :litrep:`<datareader_qos>`
      - Quality of Service (QoS) used by administration DataReader(s).
        If the tag is not defined, the *Connext DDS* defaults will be used,
        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>`
      - When you enable *Distributed Logger*, *Replay Service*
        will publish its Log messages to *Connext DDS*.
        See :numref:`section-config-enabling-distributed-logger`.
      - 0..1

The contents of the tags for configuring QoS are specified in the same
manner as for the *Connext DDS* QoS profile file. See
:link_xml_qos_config:`Configuring QoS with XML, in the RTI Connext
DDS Core Libraries User's Manual <>`.



.. _section-replay_config_monitoring_tag:

Monitoring
----------

The ``<monitoring>`` tag allows you to enable and configure remote
monitoring of *Replay Service*.

.. list-table:: Monitoring Tags in Replay Service's Configuration File
    :name: ReplayTableMonitoringTag
    :widths: 20 50 10
    :header-rows: 1
    :class: longtable

    * - Tags within :litrep:`<monitoring>`
      - Description
      - Multiplicity
    * - :litrep:`<enabled>`
      - Whether to enable monitoring of the service.

        Default: Disabled unless administration is enabled
      - 0..1
    * - :litrep:`<domain_id>`
      - Domain ID used for monitoring.

        Default: Use the domain ID specified for monitoring
      - 0..1
    * - :litrep:`<datawriter_qos>`
      - QoS used by monitoring DataWriter(s)
      - 0..1
    * - :litrep:`<publisher_qos>`
      - QoS used by monitoring Publisher(s)
      - 0..1
    * - :litrep:`<participant_qos>`
      - QoS used by monitoring DomainParticipant
      - 0..1
    * - :litrep:`<statistics_sampling_period>`
      - How frequently to sample the service's statistics, using the tags <sec>
        or <nanosec>. For example, <sec>1</sec> samples the service's
        statistics every second.
      - 0..1
    * - :litrep:`<status_publication_period>`
      - How frequently to publish the service status, using the tags <sec>
        or <nanosec>. For example, <sec>1</sec> publishes the service's status
        every second.
      - 0..1

The contents of the tags for configuring QoS are specified in the same
manner as for the *Connext DDS* QoS profile file. See
:link_xml_qos_config:`Configuring QoS with XML, in the RTI Connext
DDS Core Libraries User's Manual <>`.



.. _section-replay_config_storage_tag:

Storage
-------

The ``<storage>`` tag allows you to configure the storage from which data will
be read. You can choose between using the builtin SQLite storage or
implementing your own storage plugin.

.. list-table:: Storage Tags in Replay Service's Configuration File
    :name: TableReplayStorageTag
    :widths: 20 70 10
    :header-rows: 1

    * - Tags within :litrep:`<storage>`
      - Description
      - Multiplicity
    * - :litrep:`<sqlite>`
      - Enables replaying data from an SQLite database file
        See :numref:`section-replay_config_sqlite_tag`.
      - 0..1
    * - :litrep:`<plugin>`
      - Enables storing data in an external library that you specify.

        Attributes

            - ``plugin_name``: Name of the plugin that creates a storage
              plugin object. This name shall refer to a registered storage plugin.
              See :numref:`section-Common-PluginManagement` for details on how
              to register plugins).

        See :numref:`section-Replay-Config-Storage-Plugin-Tag` for more about using
        this tag.

        See :numref:`section-replay-custom-storage` for a tutorial on
        plugging in custom storage.
      - 0..1


.. _section-replay_config_sqlite_tag:

SQLite
^^^^^^

The ``<sqlite>`` tag allows you to specify a SQLite formatted file to read
data from for replay.  

.. list-table:: SQLite Tags in Replay Service's Configuration File
    :name: ReplayTableSqliteTag
    :widths: 20 50 10
    :header-rows: 1
    :class: longtable

    * - Tags within :litrep:`<sqlite>`
      - Description
      - Multiplicity
    * - :litrep:`<storage_format>`
      - The storage format of the user data files found in the
        database directory. If not specified, XCDR_AUTO is assumed.

        The options are:

        - XCDR_AUTO: This is the binary format used by *Connext DDS* when
          sending data over the network. This has the highest performance
          for recording, but
          can only be viewed by using *Converter* to convert the data to a
          readable format, or by using *Replay* to replay the data.  This will
          internally store data in XCDR or XCDR2 depending on the format received.

        - JSON_SQLITE: This format can be queried, but recording in this format has
          lower performance because data must be deserialized before it can be
          stored.

        - XCDR: The format to use when communicating with *Connext DDS* before 6.0.0.

        - XCDR2: More efficient than XCDR, used by *Connext DDS* 6.0.0 and later.

        Default: XCDR_AUTO.
      - 0..1
    * - :litrep:`<database_dir>`
      - The directory where to look for a recorded database.
        The directory must contain a valid metadata file, as
        well as a discovery file and one or many user data
        files. |br|
        This field is optional. When not included, the
        current directory will be used.

        Default: the current directory.
      - 0..1
    * - :litrep:`<sql_initialization_string>`
      - Allows configuring an SQLite SQL expression to use when
        establishing SQLite connections using this plugin.
        You can add an index to a table to speed up replay, but this must be
        done for each table you want to index.  Note that you can perform this
        step using an SQLite client.

        Example:
            .. code-block:: xml

              <sql_initialization_string>
                  CREATE INDEX IF NOT EXISTS pingtopic_0_by_rcp_timestamp
                  ON 'PingTopic@0' (SampleInfo_reception_timestamp);
              </sql_initialization_string>

        **Note**: when using Recorder and Replay at the same time for the same DB
        file(s), or for that matter, any other SQLite application accessing the
        data, we recommend using SQLite's WAL (write-ahead logging) mode. This
        can be done by adding ``PRAGMA JOURNAL_MODE = WAL;`` to this configuration
        setting. More information about SQLite's WAL mode can be found `here
        <http://www.sqlite.org/wal.html>`_.

        Default:
        ``PRAGMA SYNCHRONOUS = OFF; PRAGMA JOURNAL_MODE = MEMORY;``
      - 0..1

.. _section-Replay-Config-Storage-Plugin-Tag:


Plugin
^^^^^^

.. list-table::  Storage plugin Tag in the Configuration File
    :name: ReplayTablePluginTag
    :widths: 20 70 10
    :header-rows: 1

    * - Tags within :litrep:`<plugin>`
      - Description
      - Multiplicity
    * - :litrep:`<property>`
      - Name/value pairs of properties to pass to a storage plugin.
      - 0 or 1


.. _section-replay_config_legacy_tag:

Legacy
------

.. list-table:: Legacy Tags in the Configuration File
    :name: ReplayTableLegacyTag
    :widths: 20 50 10
    :header-rows: 1

    * - Tags within :litrep:`<legacy>`
      - Description
      - Multiplicity
    * - :litrep:`<file_path>`
      - Path to the legacy format recorded file. File set and
        version properties will be obtained automatically from
        the file itself.
      - 0..1
    * - :litrep:`<domain_mapping>`
      - This tag allows you to link legacy domain names with domain IDs.
        See :numref:`section-replay_config_domainmapping_tag`.
      - 0..1


.. _section-replay_config_domainmapping_tag:

Domain Mapping
--------------
When converting a legacy database, the domain may not have been recorded.
This tag provides a way to map a table with a domain ID.

Later versions of the old Recorder database allowed you to use field filters.
By default, the domain ID field was not recorded (it was filtered out by
default). Thus, there is no information available in these legacy databases
to relate the domain name used to record the data with a domain ID. This
tag allows you to link legacy domain names with domain IDs.

.. list-table:: Domain Mapping Tags in the Configuration File
    :name: ReplayTableDomainMappingTag
    :widths: 20 50 10
    :header-rows: 1

    * - Tags within :litrep:`<domain_mapping>`
      - Description
      - Multiplicity
    * - :litrep:`<domain_map>`
      - **Required**. |br|
        A link between a recorded legacy domain name and a domain ID.

        Attributes:
          - ``legacy_domain_name``: Name of the recorded domain name as
            specified in the old Recording Service domain tag, for example: |br|
            <domain name="domain0">.
          - ``participant_ref``: The name of a DomainParticipant specified
            below using a ``<domain_participant>`` tag. This DomainParticipant
            will be used to replay data specified by the legacy domain name.
      - 1..*


.. _section-replay_config_domainparticipant_tag:

DomainParticipant
-----------------

The ``<domain_participant>`` tag allows you to specify the
DomainParticipants and domain IDs you want to query from the database
for replay.  You can replay in the same domain you used to record, or
you can use the ``-domainIdBase`` command-line parameter to replay in a
different domain.

The contents of the tags for configuring QoS are specified in the same
manner as for the *Connext DDS* QoS profile file. See
:link_xml_qos_config:`Configuring QoS with XML, in the RTI Connext
DDS Core Libraries User's Manual <>`.


.. list-table:: DomainParticipant Tags in Replay Service's Configuration File
    :name: TableDomainParticipantReplayTag
    :widths: 20 50 10
    :header-rows: 1
    :class: longtable

    * - Tags within :litrep:`<domain_participant>`
      - Description
      - Multiplicity
    * - :litrep:`<domain_id>`
      - The domain ID of tables loaded from the database.  This is used
        (in conjunction with the ``-domainIdBase`` command-line parameter) to
        choose which domain to replay into.
      - 1
    * - :litrep:`<participant_qos>`
      - QoS used by this DomainParticipant.
      - 0..1
    * - :litrep:`<memory_management>`
      - Configures certain aspects of how *Connext DDS* allocates internal
        memory. The configuration is per DomainParticipant and therefore
        affects all the contained DDS entities. |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:
            -   :litrep:`<sample_buffer_min_size>`:  For all DataWriters and
                DataReaders, the way *Connext DDS* allocates memory for samples
                is as follows:
                *Connext DDS* pre-allocates space for samples up to size X in the
                DataWriter and DataReader 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.
            -   :litrep:`<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:`<register_type>`
      - Registers a type name and associates it with a type representation.
        When you define a type in the configuration file, you have to
        register the type in order to use it in a ``<topic>``.

        Attributes:
          - ``name``: Name that the data type is registered with if no
            :litrep:`<registered_name>`  is specified. The same data type may be
            registered with different names. **Required**.
          - ``type_ref``: Definition of this data type. It must refer to one of
            the defined types in the ``<types>`` section by specifying the fully
            qualified name.

        Tags within this tag:
          - :litrep:`<registered_name>`: Name the data type is registered with.
            The same data type may be registered with different names. Not required.

      - 0..*

.. _section-replay_config_playback_tag:

Playback
--------

The ``<playback>`` tag allows you to specify the timing rules for how the
data is played back, such as the time on the local machine to start the
replay, if it is not started immediately.

.. list-table:: Playback Tags in Replay Service's Configuration File
    :name: TablePlaybackTag
    :widths: 20 50 10
    :header-rows: 1
    :class: longtable

    * - Tags within :litrep:`<playback>`
      - Description
      - Multiplicity
    * - :litrep:`<start_replay_local_time>`
      - Selects the local time when *Replay Service* should start
        publishing samples. |br|
        Specified in hours, minutes, and seconds. |br|
        Specifying a full date is not currently supported, so if you specify
        a time that happened in the past (which *Replay Service* interprets as
        in the past *today*), replay will start immediately.
        Default: Replay will start immediately
      - 0..1
    * - :litrep:`<fidelity>`
      - Specifies the fidelity of the replayed data. Samples whose timestamp
        distance is less than the fidelity period may be published together
        in the same batch. For example, if your fidelity is 100 ms, data
        stored in your database within a 100 ms time period may be
        published together.

        Tags within this tag:
          - :litrep:`<sampling_period>`: the duration (in seconds and
            nanoseconds) that represents the maximum time period during which
            samples with different timestamps may be published together.
            Default: 1 ms

      - 0..1
    * - :litrep:`<rate>`
      - Specifies the rate to replay data, as a double. For example, to
        play data at half speed, use 0.5.
        Default: 1 (normal speed)
      - 0..1
    * - :litrep:`<enable_looping>`
      - Plays the data in a repeating loop, until *Replay Service* is stopped.
        Note that this means that only a termination signal or a remote shutdown
        command will make it stop replaying data. |br|
        When no time range data selection has been specified
        (see :numref:`section-replay_config_dataselection_tag`) then Replay will
        replay the whole contents of the database file(s) and when it's time to
        loop, it will start from the very beginning of the file or files.
        However, when a specific time range has been specified for replay, the
        looping will respect the time range and will restart at the specified
        start time and end at the specified end time. |br|
        **Note**: in our default SQLite implementation, Replay is able to check
        if new data has been written by Recorder (or any application) for every
        given stream being replayed, since the start of the service. This
        feature is generally not supported when looping without specifying a
        time range and may yield unexpected results.
        Default: false.
      - 0..1


.. _section-replay_config_dataselection_tag:

Data Selection
--------------

Selection of data to replay from the database. Currently only supports
selection using a time range.

.. list-table:: Data Selection Tags in Replay Service's Configuration File
    :name: TableDataSelectionTag
    :widths: 20 50 10
    :header-rows: 1

    * - Tags within :litrep:`<data_selection>`
      - Description
      - Multiplicity
    * - :litrep:`<time_range>`
      - Select data to replay from the database, based on start and end times.
        See :numref:`section-replay_config_timerange_tag`.
      - 0..1


.. _section-replay_config_timerange_tag:

Time Range
----------

The ``<time_range>`` tag allows you to specify the begin and end times
of the data you want to replay.  This can be specified either as timestamps
or as symbolic timestamps called "timestamp tags."  These tags may have
been added to the recording through remote administration, and can be viewed
using the script ``rtirecordingservice_list_tags``
(see :numref:`section-record-list-tags`).

.. list-table:: Time Range Tags in Replay Service's Configuration File
    :name: TableTimeRangeTag
    :widths: 20 50 10
    :header-rows: 1
    :class: longtable

    * - Tags within :litrep:`<time_range>`
      - Description
      - Multiplicity
    * - :litrep:`<begin_time>`
      - Select data to replay from the database, with a timestamp beginning at
        this time.  Specify the time in seconds and nanoseconds. |br|
        Default: 0, start at beginning of the file.
      - 0..1
    * - :litrep:`<begin_tag>`
      - Can be used instead of begin_time. Select data to start replaying
        from the database by specifying the string name of a timestamp tag.
        Timestamp tags associate a timestamp with a name. Then you
        can refer to a timestamp by that name.
        The timestamp must have been tagged with that name during recording.
        See :numref:`section-record-tags`. |br|
        Default: Start at beginning of the file.
      - 0..1
    * - :litrep:`<end_time>`
      - Select data to replay from the database, with a timestamp ending at this
        time.  Specify the time in seconds and nanoseconds. |br|
        Default: Stop at end of file.
      - 0..1
    * - :litrep:`<end_tag>`
      - Can be used instead of end_time. Select when to stop replaying data
        by specifying the string name of a timestamp tag.
        Timestamp tags associate a timestamp with a name. Then you
        can refer to a timestamp by that name.
        The timestamp must have been tagged with that name during recording.
        See :numref:`section-record-tags`. |br|
        Default: Stop at end of file.
      - 0..1


.. _section-replay_config_session_tag:

Session
-------

The ``<session>`` tag configures the threads that will be used to replay
data.  You also specify the Topics and groups of Topics to replay inside the
<session> tag.

.. list-table:: Session Tags in Replay Service's Configuration File
    :name: TableReplaySessionTag
    :widths: 20 50 10
    :header-rows: 1
    :class: longtable

    * - Tags within :litrep:`<session>`
      - Description
      - Multiplicity
    * - :litrep:`<publisher_qos>`
      - Specifies the QoS of the Publisher that will be used by the
        contained ``<topic>`` and ``<topic_group>``.  For information on
        configuring Pubscriber QoS with XML, see
        :link_xml_qos_config:`Configuring QoS with XML, in the
        RTI Connext DDS Core Libraries User's Manual <>`.
      - 0..1
    * - :litrep:`<thread_pool>`
      - Defines the number of threads used by this session
        to process Topics and Topic Groups
        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:`<topic>`
      - Specifies an individual Topic to replay.
        See :numref:`section-replay_config_topic_tag`.

        Attributes:
          - ``name``: The name of the Topic to replay. This name is also
            used when monitoring and administering each Topic.
          - ``participant_ref``: A DomainParticipant to use when
            replaying this Topic.  If the parent ``<session>``
            specifies a ``default_participant_ref``, this attribute is optional.
      - 0..*
    * - :litrep:`<topic_group>`
      - Specifies a group of Topics to replay.
        See :numref:`section-replay_config_topicgroup_tag`.

        Attributes:
          - ``name``: The name of the topic group. This name is used when
            monitoring and administering each topic group.
          - ``participant_ref``: A DomainParticipant to use when
            replaying this topic group.  If the parent
            ``<session>`` specifies a ``default_participant_ref``, this
            attribute is optional.
      - 0..*


.. _section-replay_config_topicgroup_tag:

Topic Group
-----------

The ``<topic_group>`` tag allows you to replay a group of Topics,
using regular expressions to describe which Topics to replay.

.. list-table:: Topic Group Tags in Replay Service's Configuration File
    :name: ReplayTableTopicGroupTag
    :widths: 20 70 10
    :header-rows: 1
    :class: longtable

    * - Tags within :litrep:`<topic_group>`
      - Description
      - Multiplicity
    * - :litrep:`<allow_topic_name_filter>`
      - A regular expression (fnmatch) describing which Topics are allowed to be
        replayed.
        You may use a comma-separated list to specify more than one filter. |br|

        Example:
            .. code-block:: xml

              <topic_group name="ReplayAll">
                  <allow_topic_name_filter>CONTROL_*,DATA_*</allow_topic_name_filter>
              </topic_group>
      - 0..1
    * - :litrep:`<deny_topic_name_filter>`
      - A regular expression (fnmatch) describing which Topics are not allowed to be
        replayed. This is applied after the ``allow_topic_name_filter``.
        You may use a comma-separated list to specify more than one filter.
      - 0..1
    * - :litrep:`<allow_type_name_filter>`
      - A regular expression (fnmatch) describing the names of data types that are
        allowed to be replayed.
        You may use a comma-separated list to specify more than one filter.
      - 0..1
    * - :litrep:`<deny_type_name_filter>`
      - A regular expression (fnmatch) describing the names of data types that are
        not allowed to be replayed. This is applied after the
        ``allow_type_name_filter``.
        You may use a comma-separated list to specify more than one filter.
      - 0..1
    * - :litrep:`<datawriter_qos>`
      - The DataWriter's QoS to use when replaying this data.
        For information on configuring QoS with XML, see
        :link_xml_qos_config:`Configuring QoS with XML <>`, in the
        *RTI Connext DDS Core Libraries User's Manual.*
      - 0..1


.. _section-replay_config_topic_tag:

Topic
-----

The ``<topic>`` tag specifies an individual Topic to replay.

.. list-table:: Topic Tags in Replay Service's Configuration File
    :name: ReplayTableTopicTag
    :widths: 20 70 10
    :header-rows: 1
    :class: longtable

    * - Tags within :litrep:`<topic>`
      - Description
      - Multiplicity
    * - :litrep:`<topic_name>`
      - The name of the DDS topic to be replayed. If this tag is not present,
        the name attribute of the `<topic>` will be used. |br|

        *Note*: we recommend using this tag to define the topic name. There may
        be characters that cause the XML validation to fail if they are part of
        the topic name attribute. Also, the '/' character and '::' separator may
        cause Replay to fail when found in the topic name attribute.
      - 0..1
    * - :litrep:`<registered_type_name>`
      - The name of the data type that will be replayed for this topic.
        **Required**.
      - 1
    * - :litrep:`<transformation>`
      - The transformation library to be applied to this Topic's data when
        replaying. This is a user library that can modify the data after
        it is received from storage and before it is sent via *Connext DDS*.

        Transformations implement APIs identical to *Routing Service's*
        transformations. For more on using transformations,
        see these sections in the *RTI Routing Service User's Manual*:

        - :link_router_manual_config_transformation:`Data Transformation <>`
        - :link_router_manual_tutorials:`Tutorials <>`

        Attributes:
          - ``plugin_name``: The name of the plugin to load, qualified by the
            plugin library name.

        Example:
            .. code-block:: xml

              <dds>
                  <plugin_library name="ReplayTransformations">
                      <transformation_plugin name="ModifyTestID">
                          <create_function>ModifyTestID_create</create_function>
                          <dll>modify_test_id_library</dll>
                      </transformation_plugin>
                  </plugin_library>
                  <!-- ... -->
                  <replay_service>
                      <!-- ... -->
                      <topic name="TestTopic">
                          <transformation plugin_name="ReplayTransformations::ModifyTestID" />
                      </topic>
                  </replay_service>
              </dds>
      - 0..1
    * - :litrep:`<datawriter_qos>`
      - The DataWriter QoS to use when replaying this data.
        For information on configuring QoS with XML, see
        :link_xml_qos_config:`Configuring QoS with XML <>`, in the
        *RTI Connext DDS Core Libraries User's Manual.*
      - 0..1

.. _section-Replay-Config-Plugins:

Plugins
-------

All the pluggable components specific to *Recording Service* are configured
within the ``<plugin_library>`` tag. :numref:`TableReplayPluginLibraryTag` describes the
available tags.

Plug-ins are categorized and configured based on the
source language. *Replay Service* supports C/C++ plugins.


.. list-table:: Configuration tags for plugin libraries
    :name: TableReplayPluginLibraryTag
    :widths: 30 60 10
    :header-rows: 1
    :class: longtable

    * - Tags within :litrep:`<plugin_library>`
      - Description
      - Multiplicity
    * - :litrep:`<storage_plugin>`
      - Specifies a C/C++ *Storage* plugin. |br|
        See :numref:`TableNativePluginTag` and :numref:`section-record-config-storage-tag`.
      - 0..*
    * - :litrep:`<transformation_plugin>`
      - Specifies a C/C++ |TRANSF| plugin. |br|
        See :numref:`TableNativePluginTag` and :numref:`section-config-topic-tag`.
      - 0..*