10.3. Remote Administration Platform

This section describes details of the RTI Remote Administration Platform, which represents the foundation of the remote access capabilities available in RTI Routing Service, RTI Recording Service, and RTI Queuing Service. The RTI Remote Administration Platform provides a common infrastructure that unifies and consolidates the remote interface to all RTI Services.

Note

Remote administration of RTI Services requires an understanding of the application resource model. We recommend that you read Application Resource Model (Application Resource Model) before continuing with this section.

The RTI Remote Administration Platform addresses two areas:

  • Resource Interface: How to perform operations on a set of resource objects that are available as part of the public interface of the remote service.

  • Communication: How the remote service receives and sends information.

The combination of these two areas provides the general view of the RTI Remote Administration Platform, as shown in Figure 10.3. The RTI Remote Administration Platform is defined as a request/reply architecture. In this architecture, the service is modeled as a set of resources upon which the requester client can perform operations. Resources represent objects that have both state and behavior.

Routing Service Adapter Overview

Figure 10.3 General View of the RTI Remote Administration Platform Architecture

Clients issue requests indicating the desired operation and receive replies from the service with the result of the requests. If multiple clients issue multiple requests to one or more services, the client will receive only replies to its own requests.

10.3.1. Remote Interface

Services offer their available functionality through their set of resources. The RTI Remote Administration Platform defines a Representational State Transfer (REST)-like interface to address service resources and perform operations on them. A resource operation is determined by a REST request and the associated result by a REST reply.

Table 10.2 REST Interface

Element

Description

REST Request

[method] + [resource_identifier] + [body]
  • method: Specifies the action to be performed on a service resource. There is only a small subset of methods, known as standard methods (see Standard Methods).

  • resource_identifier: Addresses a concrete service resource. Each concrete service has its own set of resources (see Resource Identifiers).

  • body: Optional request data that contains necessary information to complete the operation.

REST Reply

[return code] + [body]
  • return code: Integer indicating the result of the operation.

  • body: Optional reply data that contains information associated with the processing of the request.

10.3.1.1. Standard Methods

The RTI Remote Administration Platform defines the methods listed in Table 10.3.

Table 10.3 Standard Methods

Method

URI

Request Body

Reply Body

CREATE

Parent collection resource identifier

Resource representation

N/A

GET

Resource identifier

N/A

Resource representation

UPDATE

Resource identifier

Resource representation

N/A

DELETE

Resource identifier

Undefined

N/A

10.3.1.2. Custom Methods

There are certain cases in which an operation on a service resource cannot be mapped intuitively to a standard method and resource identifier. Custom methods address this limitation.

A custom method can be specified as part of the resource identifier, after the resource path, separated by a :.

UPDATE + [resource_identifier] : [custom_verb]

It is up to each service implementation to define which custom methods are available and on what resources they apply. Custom methods follow these conventions:

  • They are invoked through the UPDATE standard method.

  • They are named using lower snake_case.

  • They may use the request body and reply body if necessary.

10.3.1.2.1. Example: Database Rollover

This example shows the REST request to perform a file rollover operation on a file-based database:

UPDATE /databases/MyDatabase:rollover

10.3.2. Communication

The information exchange between client and server is based on the DDS request-reply pattern, as shown in Figure 10.4. The client maps to a Requester, whereas the server maps to a Replier.

Routing Service Adapter Overview

Figure 10.4 Communication in RTI Remote Administration Platform is Based on DDS Request-Reply

The communication is performed over a single request-reply channel, composed of two topics:

  • Command Request Topic: Topic through which the client sends the requests to the server.

  • Command Reply Topic: Topic through which the server sends the replies to the received requests.

The definition of these topics is shown in Table 10.4:

Table 10.4 Remote Administration Topics

Topic

Name

Top-level Type Name

CommandRequestTopic

rti/service/administration/command_request

rti::service::admin::CommandRequest

CommandReplyTopic

rti/service/administration/command_reply

rti::service::admin::CommandReply

The definition for each Topic type is described below.

Listing 10.1 CommandRequest Type
            @appendable
            struct CommandRequest {
                @key int32 instance_id;
                @optional string<BOUNDED_STRING_LENGTH_MAX> application_name;
                CommandActionKind action;
                ResourceIdentifier resource_identifier;
                StringBody string_body;
                OctetBody octet_body;
            };

Table 10.5 CommandRequest

Field Name

Description

instance_id

Associates a request with a given instance in the CommandRequestTopic.

This can be used if your requester application model wants to leverage outstanding requests. In general, this member is always set to zero, so all requests belong to the same CommandRequestTopic instance.

application_name

Optional member that indicates the target service instance where the request is sent. If NULL, the request will be sent to all services.

action

Indicates the resource operation.

resource_identifier

Addresses a service resource.

string_body

Contains content represented as a string.

octet_body

Contains content represented as binary.

Listing 10.2 CommandReply Type
            @appendable
            struct CommandReply {
                CommandReplyRetcode retcode;
                int32 native_retcode;
                StringBody string_body;
                OctetBody octet_body;
            };

Table 10.6 CommandReply

Field Name

Description

retcode

Indicates the result of the operation.

native_retcode

Provides extra information about the result of the operation.

string_body

Return value of the operation, represented as a string.

octet_body

Return value of the operation, represented as binary.

The type definitions for both the CommandRequestTopic and CommandReplyTopic are in the file [NDDSHOME]/resource/idl/ServiceAdmin.idl.

The definition of the request and reply topics is independent of any specific service implementation. In fact, the topic names are fixed, unique, and shared across all services that rely on the RTI Remote Administration Platform. Clients can target specific services through two mechanisms:

  • Specifying a concrete service instance by providing its application name. The application name is a service attribute and can be set at service creation time.

  • Specifying the configuration name loaded by the target services. The target service configuration shall be present in the service resource part of the resource_identifier.

10.3.2.1. Reply Sequence

Usually a request is expected to generate a single reply. Sometimes, however, a request may trigger the generation of multiple replies, all associated with the same request.

The RTI Remote Administration Platform communication architecture allows services to respond to certain requests with a reply sequence. All the samples in a reply sequence use the the metadata SampleFlagBits to indicate whether it belongs to a reply sequence and whether there are more replies pending.

The SampleFlagBits may contain different flags that indicate the status of the reply procedure. For a given reply sequence, the associated sample flags for each reply may contain:

  • SEQUENTIAL_REPLY: If present, this indicates that the sample is the first reply of a reply sequence and there are more on the way.

  • FINAL_REPLY: If present, this indicates that the sample is the last one belonging to a reply sequence. This flag is valid only if the SEQUENTIAL_REPLY is also set.

For more on SampleFlagBits, see documentation on the DDS_SampleInfo structure in the Connext DDS API Reference HTML documentation.

10.3.2.2. Example: Controlling services remotely from a Connext DDS Application

The Connext DDS GitHub examples repository includes an example that shows how to build and run a requester application that can send commands to a running RTI Routing Service instance.

10.3.3. Common Operations

The set of services that use the RTI Remote Administration Platform to implement remote administration also share a base remote interface that consolidates and unifies the semantics and behavior of certain common operations.

Services containing resources that implement the common operations conform to the base remote interface, making sure that signatures, semantics, behavior, and conditions are respected.

The following sections describe each of these common operations.

10.3.3.1. Create Resource

CREATE [resource_identifier]

Creates a resource object from its configuration in XML representation.

This operation creates a resource object and its contained entities. The created object becomes a child of the parent specified in the resource_identifier.

After successful creation, the resource object is fully addressable for additional remote access, and the associated object configuration is inserted into the currently loaded full XML configuration.

Request body

  • string_body: XML representation of the resource object provided as file:// or str://.

  • Example str:// request body:

    str://"<my_resource name="NewResourceObject">
        ...
    </my_resource>"
    
  • Example file:// request body:

    file:///home/rti/config/service_my_resource.xml
    

Reply body

  • Empty.

Return codes

The operation may return a reply with error if:

  • The specified resource identifier does not exist.

  • The specified configuration is schematically invalid.

  • There was an error creating the resource object.

10.3.3.2. Get Resource

GET [resource_identifier]

Returns an equivalent XML string that represents the current state of the resource object configuration, including any updates performed during its lifecycle.

Request body

  • Empty.

Reply body

  • string_body: XML representation of the resource object.

  • Example reply body:

    <my_resource name="MyObject">
        ...
    </my_resource>
    

Return codes

The operation may return a reply with error if:

  • The specified resource identifier does not exist.

10.3.3.3. Update Resource

UPDATE [resource_identifier]

Updates the specified resource object from its configuration in XML representation.

This operation modifies the properties of the resource object, including the associated configuration. Only the mutable properties of the resource class can be updated while the object is enabled. To update immutable properties, the resource object must be disabled first.

Note

Properties of a child resource cannot be updated as part of a parent resource. Instead, child resources must be addressed and updated independently.

Implementations may validate the received configuration against a scheme (DTD or XSD) that defines the valid set of accepted parameters (for example, only mutable elements).

The update content should only include only the properties to be updated or changed. You are not required to provide the full representation of the object being updated.

For example, consider the XML full representation of an object as follows:

<my_resource>
  <nested_resource_A>initial_A</nested_resource_A>
  <nested_resource_B>initial_B</nested_resource_B>
  <nested_resource_C>initial_C</nested_resource_C>
  ...
</my_resource>

The update should only contain the content for the properties you want to modify. For example, the following will only update nested_resource_B to a new value, leaving the other nested resources unchanged:

<my_resource>
  <nested_resource_B>updated_B</nested_resource_B>
  ...
</my_resource>

Request body

  • string_body: XML representation of the resource object provided as file:// or str://.

  • Example str:// request body:

    str://"<my_resource name="MyResourceObject">
        ...
    </my_resource>"
    
  • Example file:// request body:

    file:///home/rti/config/service_update_my_resource.xml
    

Reply body

  • Empty.

Return codes

The operation may return a reply with error if:

  • The specified resource identifier does not exist.

  • The specified configuration is schematically invalid.

  • The specified configuration contains changes in immutable properties.

  • There was an error updating the resource object.

10.3.3.4. Set Resource State

UPDATE [resource_identifier]/state

Sends a state change request to the specified resource object.

This operation attempts to change the state of the specified resource object and propagates the request to the resource object’s contained entities.

The target state must be one of the resource class’s valid accepted states.

Request body

  • octet_body: CDR representation of an entity state.

Reply body

  • Empty.

Return codes

The operation may return a reply with error if:

  • The specified resource identifier does not exist.

  • The target request is invalid.

  • The resource object reported an error while performing the state transition.

10.3.3.5. Get Resource State

GET [resource_identifier]/state

Gets the current state of the specified resource object.

This operation attempts to fetch the state of the specified resource object.

The target’s state is returned as a part of the reply.

Request body

  • Empty

Reply body

  • octet_body: CDR representation of an entity’s current state.

Return codes

The operation may return a reply with error if:

  • The specified resource identifier does not exist.

  • The target request is invalid.

  • The resource object reported an error while fetching its current state.

10.3.3.6. Delete Resource

DELETE [resource_identifier]

Deletes the specified resource object.

This operation deletes a resource object and its contained entities. The deleted object is removed from its parent resource object.

The associated object configuration is removed from the currently loaded full XML configuration.

After a successful deletion, the resource object is no longer addressable for additional remote access.

Request body

  • Empty.

Reply body

  • Empty.

Return codes

The operation may return a reply with error if:

  • The specified resource identifier does not exist.

  • There was an error deleting the resource object.