11.2. 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 (Section 11.1) 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 11.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.

Figure 11.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.

11.2.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 11.1 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 Section 11.2.1.1). resource_identifier: Addresses a concrete service resource. Each concrete service has its own set of resources (see Section 11.1.1.1). 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.

11.2.1.1. Standard Methods

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

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

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

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

11.2.2. Communication

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

Figure 11.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 11.3:

Table 11.3 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 11.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 11.4 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 11.2 CommandReply Type

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

Table 11.5 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.

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

11.2.2.2. Example: Accessing from Connext DDS Application

This example shows a Modern C++ snippet on how to use Connext DDS Request-Reply to disable a Routing Service instance.

using namespace rti::request;
using namespace dds::core;
using namespace RTI::Service;
using namespace RTI::Service::Admin;

const unsigned int WAIT_TIMEOUT_SEC_MAX = 10;
const unsigned int ADMIN_DOMAIN_ID = 55;

int main(int, char *[]) {

    try {

        dds::domain::DomainParticipant participant(ADMIN_DOMAIN_ID);

        // create requester params
        rti::request::RequesterParams requester_params(participant);
        requester_params.request_topic_name(COMMAND_REQUEST_TOPIC_NAME);
        requester_params.reply_topic_name(COMMAND_REPLY_TOPIC_NAME);

        // Wait for Routing Service Discovery
        dds::core::status::PublicationMatchedStatus matched_status;
        unsigned int wait_count = 0;

        std::cout << "Waiting for a matching replier..." << std::endl;
        int wait_count = 0;
        while (matched_status.current_count() < 1
                && wait_count < WAIT_TIMEOUT_SEC_MAX) {
            matched_status = requester.request_datawriter().publication_matched_status();
            wait_count++;
            rti::util::sleep(Duration(1));
        }

        if (matched_status.current_count() < 1) {
            throw dds::core::Error("No matching replier found.");
        }

        /*
         * Setup command
         */
        CommandRequest request;
        request.action(CommandActionKind::RTI_SERVICE_COMMAND_ACTION_UPDATE);
        request.resource_identifier("/routing_services/MyRouter/state");
        dds::topic::topic_type_support<EntityState>::to_cdr_buffer(
                static_cast< std::vector<char> &>(request.octet_body()),
                EntityState(RTI_SERVICE_DISABLED_ENTITY_STATE));

        /*
         * Send disable
         */
        requester.send_request(request);
        CommandReply reply = requester.receive_reply(
                Duration(WAIT_TIMEOUT_SEC_MAX));
        if (reply.retcode() ==
                CommandReplyRetcode::RTI_SERVICE_COMMAND_REPLY_OK) {
            std::cout << "Command returned: " << reply.string_body() << std::endl;
        } else {
            std::cout << "Unsuccessful command returned value "
                      << reply.retcode() << "." << std::endl;
            throw dds::core::Error("Error in replier");
        }

    } catch (const std::exception& ex) {
        std::cout << "Exception: " << ex.what() << std::endl;
        return -1;
    }

    return 0;
}

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

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

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

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

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

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.

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

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