5. Remote Administration

This section provides documentation on Routing Service remote administration.

Note

Routing Service remote administration is based on the RTI Remote Administration Platform described in Remote Administration Platform. We recommend that you read that section before using Routing Service remote administration.

Below you will find an API reference for all the supported operations.

5.1. Overview

5.1.1. Enabling Remote Administration

By default, remote administration is disabled in Routing Service. To enable remote administration, you can use the <administration> tag (see Routing Service Tag) or the -remoteAdministrationDomainId command-line parameter, which enables remote administration and sets the domain ID for remote communication (see Command-Line Executable).

5.1.2. Available Service Resources

Table 5.1 lists the public resources specific to Routing Service. Each resource identifier is expressed as a hierarchical sequence of identifiers, including parent and target resources. (See Resource Identifiers for details.)

In the table below, the elements (rs), (dr), (c), (s), (ar), (r), (i), and (o) refer to the name of an entity of the corresponding class as specified in the configuration in the name attribute. For example, in the following configuration:

<routing_service name="MyRouter">...</routing_service>

The resource identifier is:

/routing_services/MyRouter

In the table, the resource identifier is written as /routing_services/(rs), where (rs) is the Routing Service name, (dr) is the Domain Route name, and so on. This nomenclature is used in the table to give you an idea of the structure of the resource identifiers. For actual (example) resource identifier names, see the example section that follows.

Table 5.1 Resources and Their Identifiers in Routing Service

Resource

Resource Identifier

Service

/routing_services/(rs)

DomainRoute

/routing_services/(rs)/domain_routes/(dr)

Connection or Participant

/routing_services/(rs)/domain_routes/(dr)/connections/(c)

Session

/routing_services/(rs)/domain_routes/(dr)/sessions/(s)

AutoRoute or AutoTopicRoute

/routing_services/(rs)/domain_routes/(dr)/sessions/(s)/auto_routes/(ar)

Route or TopicRoute

/routing_services/(rs)/domain_routes/(dr)/sessions/(s)/routes/(r)

Route Input or DDS Input

/routing_services/(rs)/domain_routes/(dr)/sessions/(s)/routes/(r)/inputs/(i)

Route Output or DDS Output

/routing_services/(rs)/domain_routes/(dr)/sssions/(s)/routes/(r)/outputs/(i)

5.1.2.1. Example

This example shows you how to address a resource of each possible resource class in Routing Service, using the example configuration in Example: Configuration Reference as a reference. (For a complete reference of the available configuration tags used in Routing Service, see XML Tags for Configuring RTI Routing Service.)

Entity with name “MyRouter”:

<routing_service name="MyRouter">...</routing_service>

Resource identifier:

/routing_services/MyRouter

5.1.3. Resource Object Representations

Table 5.2 Resource Representations in Routing Service

Resource Representation

Format (all element type definitions are from the file rti_routing_service.xsd)

ddsObjectRepresentation

<xs:element name="dds"
            type="ddsRouter"/>

routerObjectRepresentation

<xs:element name="routing_service"
            type="routingService"/>

domainRouteObjectRepresentation

<xs:element name="domain_route"
            type="domainRoute"/>

connectionObjectRepresentation

<xs:element name="connection"
            type="domainRouteConnection"/>

participantObjectRepresentation

<xs:element name="participant"
            type="domainRouteParticipant"/>

sessionObjectRepresentation

<xs:element name="session"
            type="routerSession"/>

autoRouteObjectRepresentation

<xs:element name="auto_route"
            type="autoRoute"/>

autoTopicRouteObjectRepresentation

<xs:element name="auto_topic_route"
            type="autoTopicRoute"/>

routeObjectRepresentation

<xs:element name="route"
            type="route"/>

topicRouteObjectRepresentation

<xs:element name="topic_route"
            type="topicRoute"/>

inputObjectRepresentation

<xs:element name="input"
            type="routeStreamPort"/>

outputObjectRepresentation

<xs:element name="output"
            type="routeStreamPort"/>

ddsInputObjectRepresentation

<xs:element name="input"
            type="topicRouteInput"/>
<xs:element name="dds_input"
            type="topicRouteInput"/>

ddsOutputObjectRepresentation

<xs:element name="output"
            type="topicRouteOutput"/>
<xs:element name="dds_output"
            type="topicRouteOutput"/>

5.2. API Reference

This section documents each remote operation, organized by service resource class.

5.2.1. Remote API Overview

Note

To improve readability, <SERVICE> is sometimes used in place of the service resource portion of the resource identifier (e.g., /routing_services/(rs) or /routing_services/MyService). It does not represent valid syntax.

Table 5.3 Remote Interface Overview

Resource

Operation

Description

Service

CREATE /routing_services/(rs)/domain_route

Creates a new DomainRoute.

CREATE /routing_services/(rs)/config

Loads a full service configuration.

GET /routing_services/(rs)

Returns the Service configuration.

UPDATE /routing_services/(rs)

Updates a Service object.

UPDATE /routing_services/(rs)/state

Sets a Service state.

UPDATE /routing_services/(rs):save

Saves the Service loaded configuration.

DELETE /routing_services/(rs)/domain_routes/(dr)

Deletes a DomainRoute object.

DELETE /routing_services/(rs)/config

Deletes the Service configuration.

DELETE /routing_services/(rs)

Shuts down the running Service.

DomainRoute

CREATE /routing_services/(rs)/domain_route/(dr)/sessions

Creates a new Session.

UPDATE /routing_services/(rs)/domain_route/(dr)

Updates a DomainRoute.

UPDATE /routing_services/(rs)/domain_route/(dr)/state

Sets a DomainRoute state.

DELETE /routing_services/(rs)/domain_route/(dr)/sessions/(s)

Deletes a Session.

Connection

UPDATE <SERVICE>/domain_route/connections(c):add_peer

Adds a list of peers in a Connection (a Participant in DDS adapter).

UPDATE <SERVICE>/domain_route/(dr)/connections(c)

Updates a Connection.

DELETE <SERVICE>/domain_route/(dr)/connections(c):remove_peer

Removes a list of peers in a Connection (a Participant in DDS adapter).

Session

CREATE <SERVICE>/domain_route/(dr)/sessions/(s)/auto_routes

Creates a new AutoRoute.

CREATE <SERVICE>/domain_route/(dr)/sessions/(s)/routes

Creates a new Route.

UPDATE <SERVICE>/domain_route/(dr)/sessions(s)

Updates a Session.

UPDATE <SERVICE>/domain_route/(dr)/sessions(s)/state

Sets a Session state.

DELETE <SERVICE>/domain_route/(dr)/sessions/(s)/auto_routes/(ar)

Deletes an AutoRoute.

DELETE <SERVICE>/domain_route/(dr)/sessions/(s)/routes/(r)

Deletes a Route.

AutoRoute or AutoTopicRoute

UPDATE <SERVICE>/domain_route/(dr)/sessions/(s)/auto_routes(ar)

Updates an AutoRoute.

UPDATE <SERVICE>/domain_route/(dr)/sessions/(s)/auto_routes(ar)/state

Sets an AutoRoute state.

Route or TopicRoute

UPDATE <SERVICE>/domain_route/(dr)/sessions/(s)/routes(r)

Updates a Route.

UPDATE <SERVICE>/domain_route/(dr)/sessions/(s)/routes(r)/state

Sets a Route state.

Input

UPDATE <SERVICE>/domain_route/(dr)/sessions/(s)/routes(r)/inputs/(i)

Updates an Input (Connext and non-Connext).

Output

UPDATE <SERVICE>/domain_route/(dr)/sessions/(s)/routes(r)/outputs/(o)

Updates an Output (Connext and non-Connext).

5.2.2. Service

CREATE /routing_services/(rs)/domain_routes

Operation create_domain_route

Creates a DomainRoute object from its domainRouteObjectRepresentation (see Table 5.2).

See Create Resource (Create Resource).

Example

Create a DomainRoute with name “NewDomainRoute” under Service “MyRouter”, with its configuration provided as a str:// scheme.

Request Field

Value

action

CREATE

resource_identifier

/routing_services/MyRouter/domain_routes

string_body

str\://\"<domain_route name=\"NewDomainRoute\">
    ...
</domain_route>"

The newly created object has the resource identifier:

/routing_services/MyRouter/domain_routes/NewDomainRoute


CREATE /routing_services/(rs)/config

Operation load

Loads a new configuration for the service from its ddsObjectRepresentation (see Table 5.2).

If the Service is already loaded, this operation will unload it first.

The provided configuration must contain a valid Service configuration with the same name that the initial configuration used when the service was first instantiated.

If the operation fails, the service will remain in an unloaded state.

Request body

  • string_body: a valid Service XML configuration document provided as file:// or str://.

Reply body

  • Empty.

Example

Load a new configuration in Service “MyRouter”.

Request Field

Value

action

CREATE

resource_identifier

/routing_services/MyRouter/config

string_body

str://"<dds>
    ...
    <qos_library name="QosLibrary">
       ...
    </qos_library>

    ...
    <routing_service name="MyRouter">
        ...
    </routing_service>
</dds>"

GET /routing_services/(rs)

Operation: get

Returns a snapshot of the currently loaded full XML configuration as ddsObjectRepresentation (see Table 5.2).

See Get Resource (Get Resource).

Example reply body:
<routing_service name="MyRouter>
    <administration>...</administration>
    ...
</routing_service>

UPDATE /routing_services/(rs)

Operation: update

Updates the specified Service object.

See Update Resource (Update Resource).

The expected XML configuration is a subset of routerObjectRepresentation and only contains the properties that are mutable and whose values have changed.

Example

Update a Service with the name “MyRouter”.

Request Field

Value

action

UPDATE

resource_identifier

/routing_services/MyRouter

string_body

str://\"<routing_service>
    <save_path>./service_snapshot.xml</save_path>
</routing_service>"

UPDATE /routing_services/(rs)/state

Operation: set_state

Sets the state of a Service object.

See Set Resource State (Set Resource State).

Valid requested states:

  • ENABLED

  • DISABLED

  • PAUSED

  • RUNNING

Example

Enable a Service with the name “MyRouter”.

Request Field

Value

action

UPDATE

resource_identifier

/routing_services/MyRouter/state

octet_body

to_cdr_buffer(RTI::Service::EntityStateKind::ENABLED)

UPDATE /routing_services/(rs):save

Operation: save

Dumps the currently loaded XML configuration into a file.

The output file is specified by the save_path configuration tag. The save operation will fail if the save_path has not been configured.

Request body

  • Empty.

Reply body

  • Empty.


DELETE /routing_services/(rs)/domain_routes/(dr)

Operation delete_domain_route

Deletes the specified DomainRoute.

See Delete Resource (Delete Resource).


DELETE /routing_services/(rs)/config

Operation unload

Unloads the current configuration of the service. If the Service is enabled, this operation will disable it first. Upon a successful request, the service will remain in an unloaded state and no other operations can be made until a configuration is loaded.

Request body

  • Empty.

Reply body

  • Empty.


DELETE /routing_services/(rs)

Operation shutdown

Initiates the shutdown sequence on the process where the Service object runs.

  • If Service runs as a process executed by the shipped executable in the RTI Connext installation, the process will exit upon receipt of the command.

  • If Service is instantiated as a library in your application, the service instance will notify the installed remote shutdown hook.

In both cases, right before executing the shutdown sequence, Service will send a reply indicating the result of the operation. Note that if the operation returns successfully, the reply may be lost and never received by remote clients, since all the contained entities are deleted, including the RTI Remote Administration Platform entities.

This operation can be invoked at any time during the lifecycle of the service.

Request body

  • Empty.

Reply body

  • Empty.

5.2.3. DomainRoute

CREATE /routing_services/(rs)/domain_routes/(dr)/sessions

Operation: create_session

Creates a Session object from its sessionObjectRepresentation (see Table 5.2).

See Create Resource (Create Resource).

Example

Create a Session with the name “NewSession” under the DomainRoute “MyDomainRoute”, with its configuration provided as a str:// scheme.

Request Field

Value

action

CREATE

resource_identifier

/routing_services/MyRouter/domain_routes/MyDomainRoute/sessions

string_body

str://"<session name="NewSession">
...
</session>"

The newly created object has the resource identifier:

<SERVICE>/domain_routes/NewDomainRoute/sessions/NewSession


UPDATE /routing_services/(rs)/domain_routes/(dr)

Operation: update

Updates the specified DomainRoute object.

See Update Resource (Update Resource).

The expected XML configuration is a subset of domainRouteObjectRepresentation and only contains the properties that are mutable and whose values have changed.

Example

Update a DomainRoute with the name “MyDomainRoute” under the Service “MyRouter”, with its configuration provided as a str:// scheme.

Request Field

Value

action

UPDATE

resource_identifier

/routing_services/MyRouter/domain_routes/MyDomainRoute

string_body

str://"<domain_route>
...
</domain_route>"

UPDATE /routing_services/(rs)/domain_routes/(dr)/state

Operation: set_state

Sets the state of a DomainRoute object.

See Set Resource State (Set Resource State).

Valid requested states:

  • ENABLED

  • DISABLED

Example

Enable a DomainRoute with the name “MyDomainRoute” under the Service “MyRouter”.

Request Field

Value

action

UPDATE

resource_identifier

/routing_services/MyRouter/domain_routers/MyDomainRoute/state

octet_body

to_cdr_buffer(RTI::Service::EntityStateKind::ENABLED)

DELETE /routing_services/(rs)/domain_routes/(dr)/sessions/(s)

Operation delete_session

Deletes the specified Session.

See Delete Resource (Delete Resource).

Request body

  • Empty.

Reply body

  • Empty.

5.2.4. Connection

UPDATE \<SERVICE\>/domain_routes/(dr)/connections/(c):add_peer

Operation add_peer

Adds a list of peers to the specified Connection.

The Connection implementation shall refer to a <participant> object.

Request body

  • string_body: A comma-separated list of peer descriptors, as described in peer descriptor format.

  • Example peer descriptor list:

    updv4://10.2.0.1,udpv4://239.255.0.1
    

Reply body

  • Empty.


UPDATE \<SERVICE\>/domain_routes/(dr)/connections/(c)

Operation: update

Updates the specified Connection object.

See Update Resource (Update Resource).

The expected XML configuration is a subset of participantObjectRepresentation or connectionObjectRepresentation and only contains the properties that are mutable and whose value is changed.

Example

Update a Connection with the name “MyParticipant” under the DomainRoute “MyDomainRoute”, with its configuration provided as a str:// scheme.

Request Field

Value

action

UPDATE

resource_identifier

/routing_services/MyRouter/domain_routes/MyDomainRoute/ connections/MyParticipant

string_body

str://"<participant>
     <domain_participant_qos>
        <property>
            <value>
                <element>
                    <name>property_name</name>
                    <value>property_new_value</value>
                </element>
            </value>
        </property>
     </domain_participant_qos>
</participant>"
Example

Update a Connection with the name “MyConnection” under the DomainRoute “MyDomainRoute”, with its configuration provided as a str:// scheme.

Request Field

Value

action

UPDATE

resource_identifier

/routing_services/MyRouter/domain_routes/MyDomainRoute/ connections/MyConnection

string_body

str://"<connection>
    <property>
       <value>
           <element>
               <name>property_name</name>
               <value>property_new_value</value>
           </element>
       </value>
    </property>
</connection>

DELETE \<SERVICE\>/domain_routes/(dr)/connections/(c):remove_peer

Operation remove_peer

Removes a list of peers from the specified Connection.

The Connection implementation shall refer to a <participant> object.

Request body

  • string_body: A comma-separated list of peer descriptors, as described in peer descriptor format.

  • Example peer descriptor list:

    updv4://10.2.0.1,udpv4://239.255.0.1
    

Reply body

  • Empty.

5.2.5. Session

CREATE \<SERVICE\>/domain_routes/(dr)/sessions/(s)/auto_routes

Operation: create_auto_route

Creates an AutoRoute or AutoTopicRoute object from its autoRouteObjectRepresentation or autoTopicRouteObjectRepresentation (see Table 5.2).

See Create Resource (Create Resource).

Example

Create an AutoRoute with the name “NewAutoRoute” under the Session “MySession”, with its configuration provided as a str:// scheme.

Request Field

Value

action

CREATE

resource_identifier

/routing_services/MyRouter/domain_routes/MyDomainRoute/ sessions/MySession/auto_routes

string_body

str://"<auto_route name="NewAutoRoute">
...
</auto_route>"

The newly created object has the resource identifier:

/routing_services/MyRouter/domain_routes/MyDomainRoute/ sessions/MySession/auto_routes/NewAutoRoute


CREATE \<SERVICE\>/domain_routes/(dr)/sessions/(s)/routes

Operation: create_route

Creates a Route or TopicRoute object from its routeObjectRepresentation or topicRouteObjectRepresentation (see Table 5.2).

See Create Resource (Create Resource).

Example

Create a Route with the name “NewRoute” under the Session “MySession”, with its configuration provided as a str:// scheme.

Request Field

Value

action

CREATE

resource_identifier

/routing_services/MyRouter/domain_routes/MyDomainRoute/ sessions/MySession/routes

string_body

str://"<route name="NewRoute">
...
</route>"

The newly created object has the resource identifier:

/routing_services/MyRouter/domain_routes/MyDomainRoute/ sessions/MySession/routes/NewRoute


UPDATE \<SERVICE\>/domain_routes/(dr)/sessions/(s)

Operation: update

Updates the specified Session object.

See Update Resource (Update Resource).

The expected XML configuration is a subset of sessionObjectRepresentation and only contains the properties that are mutable and whose values have changed.

Example

Update a Session with the name “MySession” under the DomainRoute “MyDomainRoute”, with its configuration provided as a str:// scheme.

Request Field

Value

action

UPDATE

resource_identifier

/routing_services/MyRouter/domain_routes/MyDomainRoute/ sessions/MySession

string_body

str://"<session>
    <publisher_qos>
        <partition>
            <name>
                <element>MyNewPartition</element>
            </name>
        </partition>
    </publisher_qos>
</session>"

UPDATE \<SERVICE\>/domain_routes/(dr)/sessions/(s)/state

Operation: set_state

Sets the state of a Session object.

See Set Resource State (Set Resource State).

Valid requested states:

  • ENABLED

  • DISABLED

Example

Enable a Session with the name “MySession” under the DomainRoute “MyDomainRoute”.

Request Field

Value

action

UPDATE

resource_identifier

/routing_services/MyRouter/domain_routers/MyDomainRoute/ sessions/MySession/state

octet_body

to_cdr_buffer(RTI::Service::EntityStateKind::ENABLED)

DELETE \<SERVICE\>/domain_routes/(dr)/sessions/(s)/auto_routes/(ar)

Operation delete_auto_route

Deletes the specified AutoRoute.

See Delete Resource (Delete Resource).


DELETE \<SERVICE\>/domain_routes/(dr)/sessions/(s)/routes/(r)

Operation delete_route

Deletes the specified Route.

See Delete Resource (Delete Resource).

5.2.6. AutoRoute

UPDATE \<SERVICE\>/domain_routes/(dr)/sessions/(s)/auto_routes/(ar)

Operation: update

Updates the specified AutoRoute or AutoTopicRoute object.

See Update Resource (Update Resource).

The expected XML configuration is a subset of autoRouteObjectRepresentation or autoTopicRouteObjectRepresentation and only contains the properties that are mutable and whose value is changed.

Note that AutoRoute or AutoTopicRoute don’t have any children resources. All the properties defined for the XML representation can be used for the update operation. Also the Route or TopicRoute created as part of an AutoRoute or AutoTopicRoute can be updated independently.

Example

Update an AutoRoute with the name “MyAutoRoute” under the Session “MySession”, with its configuration provided as a str:// scheme.

Request Field

Value

action

UPDATE

resource_identifier

/routing_services/MyRouter/domain_routes/MyDomainRoute/ sessions/MySession/auto_routes/MyAutoRoute

string_body

str://"<auto_route>
    <dds_input>
        <datareader_qos>
            <period>
                <sec>1</sec>
                <nanosec>0</nanosec>
            </period>
        </datareader_qos>
    </dds_input>
</auto_route>"

UPDATE \<SERVICE\>/domain_routes/(dr)/sessions/(s)/auto_routes/(ar)/state

Operation: set_state

Sets the state of an AutoRoute object.

See Set Resource State (Set Resource State).

Valid requested states:

  • ENABLED

  • DISABLED

  • RUNNING

  • PAUSED

Example

Pause an AutoRoute with the name “MyAutoRoute” under the Session “MySession”.

Request Field

Value

action

UPDATE

resource_identifier

/routing_services/MyRouter/domain_routers/MyDomainRoute/ sessions/MySession/auto_routes/MyAutoRoutestate

octet_body

to_cdr_buffer(RTI::Service::EntityStateKind::PAUSED)

5.2.7. Route

UPDATE \<SERVICE\>/domain_routes/(dr)/sessions/(s)/routes/(r)

Operation: update

See Update Resource (Update Resource).

The expected XML configuration is a subset of routeObjectRepresentation or topicRouteObjectRepresentation and only contains the properties that are mutable and whose value is changed.

Example

Update a Route with the name “MyRoute” under the Session “MySession”, with its configuration provided as a str:// scheme.

Request Field

Value

action

UPDATE

resource_identifier

/routing_services/MyRouter/domain_routes/MyDomainRoute/ sessions/MySession/routes/MyRoute

string_body

str://"<route>
    <processor>
        <property>
            <value>
                <element>
                    <name>property_name</name>
                    <value>property_new_value</value>
                </element>
            </value>
        </property>
    </processor>
</route>"

UPDATE \<SERVICE\>/domain_routes/(dr)/sessions/(s)/routes/(r)/state

Operation: set_state

Sets the state of a Route object.

See Set Resource State (Set Resource State).

Valid requested states:

  • ENABLED

  • DISABLED

  • RUNNING

  • PAUSED

Example

Pause a Route with the name “MyRoute” under the Session “MySession”.

Request Field

Value

action

UPDATE

resource_identifier

/routing_services/MyRouter/domain_routers/MyDomainRoute/ sessions/MySession/routes/MyRoutestate

octet_body

to_cdr_buffer(RTI::Service::EntityStateKind::PAUSED)

5.2.8. Input/Output

UPDATE \<SERVICE\>/domain_routes/(dr)/sessions/(s)/routes/(r)/inputs(i)

Operation: update

See Update Resource (Update Resource).

The expected XML configuration is a subset of routeInputObjectRepresentation or topicRouteInputObjectRepresentation and only contains the properties that are mutable and whose value is changed.

Example

Update Input with the name “MyInput” under the TopicRoute “MyRoute”, with its configuration provided as a str:// scheme.

Request Field

Value

action

UPDATE

resource_identifier

/routing_services/MyRouter/domain_routes/MyDomainRoute/ sessions/MySession/routes/MyRoute/inputs/MyInput

string_body

str://"<input>
    <datareader_qos>
          <period>
              <sec>1</sec>
              <nanosec>0</nanosec>
          </period>
     </datareader_qos>
</input>"
Example

Update Input with the name “MyInput” under the Route “MyRoute”, with its configuration provided as a str:// scheme.

Request Field

Value

action

UPDATE

resource_identifier

/routing_services/MyRouter/domain_routes/MyDomainRoute/ sessions/MySession/routes/MyRoute/inputs/MyInput

string_body

str://"<input>
     <property>
         <value>
             <element>
                 <name>property_name</name>
                 <value>property_new_value</value>
             </element>
         </value>
     </property>
</input>"

UPDATE \<SERVICE\>/domain_routes/(dr)/sessions/(s)/routes/(r)/outputs(i)

Operation: update

See Update Resource (Update Resource).

The expected XML configuration is a subset of routeOutputObjectRepresentation or topicRouteOutputObjectRepresentation and only contains the properties that are mutable and whose value is changed.

Example

Update Output with the name “MyOutput” under the TopicRoute “MyRoute”, with its configuration provided as a str:// scheme.

Request Field

Value

action

UPDATE

resource_identifier

/routing_services/MyRouter/domain_routes/MyDomainRoute/ sessions/MySession/routes/MyRoute/inputs/MyInput

string_body

str://"<output>
    <datawriter_qos>
          <period>
              <sec>1</sec>
              <nanosec>0</nanosec>
          </period>
     </datawriter_qos>
</output>"
Example

Update Output with the name “MyOutput” under the Route “MyRoute”, with its configuration provided as a str:// scheme.

Request Field

Value

action

UPDATE

resource_identifier

/routing_services/MyRouter/domain_routes/MyDomainRoute/ sessions/MySession/routes/MyRoute/outputs/MyOutput

string_body

str://"<output>
     <property>
         <value>
             <element>
                 <name>property_name</name>
                 <value>property_new_value</value>
             </element>
         </value>
     </output>
</input>"

5.3. Example: Configuration Reference

This configuration example shows how individual commands would apply to a valid Routing Service configuration.

<?xml version="1.0"?>
<dds>
    <routing_service name="MyRouter">
        <domain_route name="MyDomainRoute">
            <participant name="MyParticipant">
               <domain_id>0</domain_id>
            </participant>
            <connection name="MyConnection">
            </connection>
            ... <!-- other connections/participants -->

            <session name="MySession">
                <auto_route name="MyAutoRoute">
                <publish_with_original_timestamp>true</publish_with_original_timestamp>
                    ...
                    <input name="MyInput">
                        ...
                        <property>
                            ...
                        </property>
                    </input>
                    <output name="MyOutput">
                        ...
                        <property>
                            ...
                        </property>
                    </output>
                </auto_route>
                <auto_topic_route name="MyAutoTopicRoute">
                    <publish_with_original_info>true</publish_with_original_info>
                    ...
                    <input name="MyInput">
                        ...
                        <datareader_qos>
                            ...
                        </datareader_qos>
                    </input>
                    <output name="MyOutput">
                        ...
                        <datawriter_qos>
                            ...
                        </datawriter_qos>
                    </output>
                </auto_topic_route>
                ... <!-- other auto (Topic) routes -->
                <route name="MyRoute">
                    <route_types>true</route_types>
                    <input name="MyInput">
                        ...
                        <property>
                            ...
                        </property>
                    </input>
                    ... <!-- other inputs -->
                    <output name="MyOutput">
                        ...
                        <property>
                            ...
                        </property>
                    </output>
                    ... <!-- other outputs -->
                </route>
                ... <!-- other (Topic) routes -->
                <topic_route name="MyTopicRoute">
                    <route_types>true</route_types>
                    ...
                    <input name="MyInput">
                        ...
                        <datareader_qos>
                            ...
                        </datareader_qos>
                    </input>
                    ... <!-- other inputs -->
                    <output name="MyOutput">
                        ...
                        <datawriter_qos>
                            ...
                        </datawriter_qos>
                    </output>
                    ... <!-- other outputs -->
                </topic_route>
            </session>
            ... <!-- other sessions -->
        </domain_route>
        ... <!-- other domain routes -->
    </routing_service>
</dds>

5.4. The Remote Administration Shell

Any Connext application can be implemented to send remote administration commands and receive the corresponding responses. A shell application that sends/receives these commands is provided with Routing Service.

The script for the shell application is in <NDDSHOME>/bin/rtirssh.

Entering rtirssh -help will show you the command-line options:

RTI Routing Service Shell
Usage: rtirssh [options]...
Options:
 -domainId  <integer>   Domain ID for the remote configuration
 -timeout   <seconds>   Max time to wait for a remote response
 -cmdFile   <file>      Run commands in this file
 -help                  Displays this information

5.4.1. Remote Shell Commands

This section describes the remote commands using the shell interface. The available remote commands are:

Command

Parameters

add_peer

<target_routing_service> <domain_route_name> p1|p2 <peer_list>

create

<target_routing_service> domain_route|session|topic_route|auto_route [<parent_entity_name>] <xml_url> [remote|local]

delete

<target_routing_service> [<entity_name>]

disable

<target_routing_service> [<entity_name>]

enable

<target_routing_service> [<entity_name>]

get

<target_routing_service>

load

<target_routing_service> <cfg_name><xml_url> [remote|local]

pause

<target_routing_service> [<entity_name>]

resume

<target_routing_service> [<entity_name>]

save

<target_routing_service>

shutdown

<target_routing_service>

unload

<target_routing_service>

update

<target_routing_service> [<entity_name>] [<xml_url>|<assignment_expr>] [remote|local]

5.4.2. Command: add_peer

add_peer <target_routing_service> <domain_route_name> p1|p2 <peer_list>

The add_peer command passes the peer_list to the underlying DomainParticipant’s add_peer() function. It is only valid for DomainParticipants in a Domain Route. Parameter <domain_route_name> is like <entity_name>, but must be a Domain Route entity. Parameter p1|p2 specifies if the DomainParticipant associated with <participant_1> or <participant_2> configuration is selected. Parameter <peer_list> is a comma-separated list of peers.

5.4.3. Command: create

create <target_routing_service> domain_route|session|topic_route|auto_route
        [<parent_entity_name>] <xml_url> [remote|local]

The create command is similar to update, but the configuration is applied to a newly created entity instead of an existing one. The second parameter (domain_route|session|topic_route|auto_route) is the kind of entity to be created. If the kind is a domain_route, there will be no parent. For the other kinds (session, topic_route, or auto_route), a <parent_entity_name> must be specified. Parameters <xml_url> and [remote|local] are the same as those used in update, except that only XML snippets matching the entity kind are allowed. A full file (starting with <dds>…) is not valid.

For example (this would be entered as a single command, with no line-breaks):

create example topic_route DomainRoute::Session
    str://"<topic_route name="TrianglesToTriangles">
    <input participant="1"><registered_type_name>ShapeType
    </registered_type_name><topic_name>Triangle</topic_name></input>
    <output><registered_type_name>ShapeType</registered_type_name>
    <topic_name>Triangle</topic_name></output></topic_route>"

5.4.4. Command: delete

delete <target_routing_service> [<entity_name>]

You can invoke the delete command on Domain Routes, Routes and Auto Routes. It acts like the disable command, but also purges the configuration data for the target entity.

For example:

delete example DomainRoute::Session::CirclesToCircles

A deleted entity cannot be re-enabled, but a new one can be created. `

5.4.5. Command: disable

disable <target_routing_service> [<entity_name>]

The disable command disables a Routing Service entity by destroying its sub-entities and corresponding DDS objects:

  • Routing service: When a Routing Service is disabled, all of its Domain Routes are destroyed. You do not need to specify the entity_name to disable a Routing Service.

  • Domain Route: When a Domain Route is disabled, all its Routes, Topic Routes, Auto Routes, and Auto Topic Routes are destroyed, as well as both Connections (DomainParticipants for DDS). All the session threads are stopped and their corresponding adapter sessions (Publisher and Subscriber for DDS) are also deleted.

  • Route, Topic Route, Auto Route and Auto Topic Route: When a Route, Topic Route, Auto Route, or Auto Topic Route is disabled, its StreamReaders and StreamWriters are destroyed, so data will no longer be routed.

5.4.6. Command: enable

enable <target_routing_service> [<entity_name>]

The enable command enables an entity that has been disabled or marked as ‘enabled=false’ in the configuration file.

This command can be used to enable the following entities:

  • Routing service: When a Routing Service is enabled, it uses the currently loaded configuration and starts. You don’t need to specify the entity_name to enable a Routing Service.

  • Domain Route: When a Domain Route is enabled, it creates the Participants, Routes, Topic Routes, Auto Routes, and Auto Topic Routes that it contains. The Routes, Topic Routes, Auto Routes, and Auto Topic Routes will be created enabled or disabled depending on their current configuration. Enabling a Domain Route is required to start routing data from the input domain to the output domain.

  • Route, Topic Route, Auto Route, and Auto Topic Route: Enabling a Route, Topic Route, Auto Route or Auto Topic Route is a necessary condition to start routing data between input and output streams. However, data routing will not start until the StreamWriter and StreamReader associated with a Route are created (see Creation Modes for additional information).

5.4.7. Command: get

get <target_routing_service>

The get command retrieves the current configuration.

The retrieved configuration, provided in an XML string format, is functionally equivalent to the loaded XML file, plus any updates (either from an update command or other remote commands that change the configuration, such as add_peer). However, the retrieved configuration may not be textually equivalent. For example, the retrieved configuration may explicitly contain default values that were not in the initial XML.

5.4.8. Command: load

load <target_routing_service> <cfg_name> <xml_url> [remote|local]

The load command loads specific XML configuration code. The target_routing_service must be disabled. For more information, see How to Load the XML Configuration here.

The XML code received must represent a valid Routing Service configuration file. The name of the <routing_service> tag to load is identified with <cfg_name>.

5.4.9. Command: pause

pause <target_routing_service> <entity_name>

When the pause command is called for a Route, the session thread containing this Route will stop reading data from the Route’s StreamReader.

For Routing Service, Domain Routes, Auto Routes, and Auto Topic Routes, the execution of this command will pause the contained Topic Routes and Routes.

5.4.10. Command: resume

resume <target_routing_service> <entity_name>

When the resume command is called for a Route, the session thread containing this Route will continue reading data from the Route’s StreamReader.

For Routing Service, Domain Routes, Auto Routes and Auto Topic Routes, the execution of this command will resume the contained Topic Routes and Routes.

5.4.11. Command: save

save <target_routing_service>

This command writes the current configuration to a file. The file itself is specified with <save_path> (see tag within the Administration Tag table). If <save_path> has not been specified, the save command will fail. If the file specified by <save_path> already exists, the file will be overwritten.

The saved configuration is functionally equivalent to the loaded XML file plus any updates (either from an update command or other remote commands that change the configuration, such as add_peer). However it may not be textually equivalent. For example, the saved XML configuration may explicitly contain default values that were not in the initial XML.

Note

If the <autosave_on_update> tag (see tag within the Administration Tag table) is set to TRUE, this will automatically trigger a save command when configuration updates are received.

5.4.12. Command: shutdown

shutdown <target_routing_service>

The shutdown command initiates the shutdown sequence on the process where the target_routing_service runs. The result of the remote shutdown command depends on how Routing Service is instantiated:

  • If Routing Service runs as a process executed by the shipped executable in your RTI Connext installation, the process will exit upon command reception.

  • If Routing Service is instantiated as a library in your application, the service instance will notify the installed remote shutdown hook. In this case, the application creating the Routing Service instance is responsible to handle the shutdown sequence. If the shutdown hook is not set, the command request will fail with a response indicating an error.

On a successful shutdown request, Routing Service will send a reply with RTI_ROUTING_SERVICE_COMMAND_RESPONSE_OK, or RTI_ROUTING_SERVICE_COMMAND_RESPONSE_ERROR and an error message indicating the problem.

This command will take effect regardless of the target_routing_service’s enabled state.

5.4.13. Command: unload

unload <target_routing_service>

The unload command unloads the current configuration that the target_routing_service is using, so you can change it with a subsequent load command.

The target_routing_service must be disabled for this command to succeed.

5.4.14. Command: update

update <target_routing_service> [<entity_name>] [<xml_url>|<assignment_expr> [remote|local]

The update command changes the configuration of a specific entity. The following table shows the parameters that can be changed for each entity:

Entity

Mutable (can be changed at any time)

Immutable (can only be changed when disabled)

Routing Service

  • <monitoring><enabled>

  • <monitoring><status_publication_period>

  • <entity_monitoring><enabled>

  • <entity_monitoring><status_publication_period>

  • <administration><save_path>

  • <administration><autosave_on_update>

  • <monitoring><statistics_sampling_period>

  • <monitoring><historical_statistics>

  • <monitoring><domain_id>

  • <entity_monitoring><statistics_sampling_period>

  • <entity_monitoring><historical_statistics>

  • <administration>

Domain Route

  • <connection>: Mutable properties in <property> (adapter-specific)

  • <participant>: Mutable QoS policies in <domain_participant_qos>

  • <entity_monitoring><enabled>

  • <entity_monitoring><status_publication_period>

  • <connection>: Immutable properties in <property> (adapter-specific)

  • <domain_participant_qos>: Immutable QoS policies in <domain_participant_qos>

  • <entity_monitoring><statistics_sampling_period>

  • <entity_monitoring><historical_statistics>

Session

  • (Non-DDS) Mutable properties in <property> (adapter-specific)

  • (DDS) Mutable QoS policies in <publisher_qos> and <subscriber_qos>

  • <entity_monitoring><enabled>

  • <entity_monitoring><status_publication_period>

  • (Non-DDS) Immutable properties in <property> (adapter-specific)

  • (DDS) Immutable QoS policies in <publisher_qos> and <subscriber_qos>

  • <entity_monitoring><statistics_sampling_period>

  • <entity_monitoring><historical_statistics>

Route

  • Mutable properties in <property> (adapter-specific)

  • Mutable properties in <transformation><property> (transformation-specific)

  • Immutable properties in <property> (adapter-specific)

  • Immutable properties in <transformation><property> (transformation-specific)

Auto Route

  • Mutable properties in <property> (adapter-specific)

  • Immutable properties in <property> (adapter-specific)

Topic Route

  • Mutable QoS policies in <datawriter_qos> and <datareader_qos>

  • Mutable properties in <transformation><property> (transformation-specific)

  • <route_types>

  • <propagate_dispose>

  • <propagate_unregister>

  • <publish_with_original_info>

  • <content_filter><parameter>

  • <entity_monitoring><enabled>

  • <entity_monitoring><status_publication_period>

  • Immutable properties in <datawriter_qos> and <datareader_qos>

  • <creation_mode>

  • <content_filter>/<expression>

  • <entity_monitoring><statistics_sampling_period>

  • <entity_monitoring><historical_statistics>

Auto Topic Route

  • Mutable QoS policies in <datawriter_qos> and <datareader_qos>

  • Mutable properties in <transformation><property> (transformation-specific)

  • <propagate_dispose>

  • <propagate_unregister>

  • <publish_with_original_info>

  • <content_filter><parameter>

  • <entity_monitoring><enabled>

  • <entity_monitoring><status_publication_period>

  • Immutable properties in <datawriter_qos> and <datareader_qos>

  • <creation_mode>

  • <content_filter>/<expression>

  • <creation_mode>

  • <allow_topic_name_filter>

  • <allow_registered_type_name_filter>

  • <deny_topic_name_filter>

  • <deny_registered_type_name_filter>

  • <content_filter><expression>

  • <entity_monitoring><statistics_sampling_period>

  • <entity_monitoring><historical_statistics>

If you try to change an immutable parameter in an entity that is enabled, you will receive an error message. To change an immutable parameter, you must disable the Routing Service entity, change the parameter, and then enable the Routing Service entity again.

You can send an XML snippet (or an assignment expression) that only contains the values you want to change for that entity, or you can send a whole well-formed configuration file:

  • If you send an XML snippet (or an assignment expression), only the changes you specify will take effect. For example, suppose you send this command:

    update ShapeRouter DomainRoute1::Session1::SquareToCircles
        str://"<topic_route><input><datareader_qos><deadline><period>
        <sec>1</sec></period></deadline></datareader_qos></input>
        </topic_route>"
    

    or

    update ShapeRouter DomainRoute1::Session1::SquareToCircles
        topic_route.input.datareader_qos.deadline.period.sec = 1
    

    The Topic Route DomainRoute1::Session1::SquareToCircles will only change the period value in the Deadline QoS for that particular DataReader.

    Now suppose that later on you send this command:

    update ShapeRouter DomainRoute1::Session1::SquareToCircles
        str://"<topic_route><input><datareader_qos><property>
        <value><element><name>MyProp</name><value>MyValueRemote</value>
        </element></value></property><datareader_qos></input>
        </topic_route>"
    

    This would only change the Property QoS; the Deadline QoS would keep the setting from the prior command. In both cases, an update command can only reconfigure one entity at a time and Routing Service will ignore all contained entities. For example, a command to update a session will not modify the configuration of its contained Routes. If you need to reconfigure several entities at the same time, consider using the load command.

  • If you send a well-formed configuration file (starting with <dds><routing_service>), the properties in the Route (QoS values in the Topic Route) will be completely replaced with the properties (QoS values) defined in the XML code. If a QoS value for a Topic Route is not defined in the XML code, Routing Service will use the Connext default.