DDS API Reference

RTI Connext modules following the DDS module definitions. More...

Modules
	Domain Module
	Contains the com.rti.dds.domain.DomainParticipant class that acts as an entrypoint of RTI Connext and acts as a factory for many of the classes. The com.rti.dds.domain.DomainParticipant also acts as a container for the other objects that make up RTI Connext.
	Topic Module
	Contains the com.rti.dds.topic.Topic, com.rti.dds.topic.ContentFilteredTopic, and com.rti.dds.topic.MultiTopic classes, the com.rti.dds.topic.TopicListener interface, and more generally, all that is needed by an application to define com.rti.dds.topic.Topic objects and attach QoS policies to them.
	Publication Module
	Contains the com.rti.dds.publication.FlowController, com.rti.dds.publication.Publisher, and com.rti.dds.publication.DataWriter classes as well as the com.rti.dds.publication.PublisherListener and com.rti.dds.publication.DataWriterListener interfaces, and more generally, all that is needed on the publication side.
	Subscription Module
	Contains the com.rti.dds.subscription.Subscriber, com.rti.dds.subscription.DataReader, com.rti.dds.subscription.ReadCondition, and com.rti.dds.subscription.QueryCondition classes, as well as the com.rti.dds.subscription.SubscriberListener and com.rti.dds.subscription.DataReaderListener interfaces, and more generally, all that is needed on the subscription side.
	Infrastructure Module
	Defines the abstract classes and the interfaces that are refined by the other modules. Contains common definitions such as return codes, status values, and QoS policies.
	Queries and Filters Syntax

---

Detailed Description

RTI Connext modules following the DDS module definitions.

Overview

DDS Dissemination Overview

Information flows with the aid of the following constructs: com.rti.dds.publication.Publisher and com.rti.dds.publication.DataWriter on the sending side, com.rti.dds.subscription.Subscriber and com.rti.dds.subscription.DataReader on the receiving side.

• A com.rti.dds.publication.Publisher is an object responsible for data distribution. It may publish data of different data types. A TDataWriter acts as a typed (i.e. each com.rti.dds.publication.DataWriter object is dedicated to one application data type) accessor to a publisher. A com.rti.dds.publication.DataWriter is the object the application must use to communicate to a publisher the existence and value of data objects of a given type. When data object values have been communicated to the publisher through the appropriate data-writer, it is the publisher's responsibility to perform the distribution (the publisher will do this according to its own QoS, or the QoS attached to the corresponding data-writer). A publication is defined by the association of a data-writer to a publisher. This association expresses the intent of the application to publish the data described by the data-writer in the context provided by the publisher.

• A com.rti.dds.subscription.Subscriber is an object responsible for receiving published data and making it available (according to the Subscriber's QoS) to the receiving application. It may receive and dispatch data of different specified types. To access the received data, the application must use a typed TDataReader attached to the subscriber. Thus, a subscription is defined by the association of a data-reader with a subscriber. This association expresses the intent of the application to subscribe to the data described by the data-reader in the context provided by the subscriber.

com.rti.dds.topic.Topic objects conceptually fit between publications and subscriptions. Publications must be known in such a way that subscriptions can refer to them unambiguously. A com.rti.dds.topic.Topic is meant to fulfill that purpose: it associates a name (unique in the domain i.e. the set of applications that are communicating with each other), a data type, and QoS related to the data itself. In addition to the topic QoS, the QoS of the com.rti.dds.publication.DataWriter associated with that Topic and the QoS of the com.rti.dds.publication.Publisher associated to the com.rti.dds.publication.DataWriter control the behavior on the publisher's side, while the corresponding com.rti.dds.topic.Topic, com.rti.dds.subscription.DataReader and com.rti.dds.subscription.Subscriber QoS control the behavior on the subscriber's side.

When an application wishes to publish data of a given type, it must create a com.rti.dds.publication.Publisher (or reuse an already created one) and a com.rti.dds.publication.DataWriter with all the characteristics of the desired publication. Similarly, when an application wishes to receive data, it must create a com.rti.dds.subscription.Subscriber (or reuse an already created one) and a com.rti.dds.subscription.DataReader to define the subscription.

Conceptual Model

The overall conceptual model is shown below.

DCPS conceptual model

Notice that all the main communication objects (the specializations of Entity) follow unified patterns of:

• Supporting QoS (made up of several QosPolicy); QoS provides a generic mechanism for the application to control the behavior of the Service and tailor it to its needs. Each com.rti.dds.infrastructure.Entity supports its own specialized kind of QoS policies (see QoS Policies).

• Accepting a com.rti.dds.infrastructure.Listener; listeners provide a generic mechanism for the middleware to notify the application of relevant asynchronous events, such as arrival of data corresponding to a subscription, violation of a QoS setting, etc. Each com.rti.dds.infrastructure.Entity supports its own specialized kind of listener. Listeners are related to changes in status conditions (see Status Kinds).
  
  Note that only one Listener per entity is allowed (instead of a list of them). The reason for that choice is that this allows a much simpler (and, thus, more efficient) implementation as far as the middleware is concerned. Moreover, if it were required, the application could easily implement a listener that, when triggered, triggers in return attached 'sub-listeners'.

• Accepting a com.rti.dds.infrastructure.StatusCondition (and a set of com.rti.dds.subscription.ReadCondition objects for the com.rti.dds.subscription.DataReader); conditions (in conjunction with com.rti.dds.infrastructure.WaitSet objects) provide support for an alternate communication style between the middleware and the application (i.e., wait-based rather than notification-based).

All DCPS entities are attached to a com.rti.dds.domain.DomainParticipant. A domain participant represents the local membership of the application in a domain. A domain is a distributed concept that links all the applications able to communicate with each other. It represents a communication plane: only the publishers and the subscribers attached to the same domain may interact.

com.rti.dds.infrastructure.DomainEntity is an intermediate object whose only purpose is to state that a DomainParticipant cannot contain other domain participants.

At the DCPS level, data types represent information that is sent atomically. For performance reasons, only plain data structures are handled by this level.

By default, each data modification is propagated individually, independently, and uncorrelated with other modifications. However, an application may request that several modifications be sent as a whole and interpreted as such at the recipient side. This functionality is offered on a Publisher/Subscriber basis. That is, these relationships can only be specified among com.rti.dds.publication.DataWriter objects attached to the same com.rti.dds.publication.Publisher and retrieved among com.rti.dds.subscription.DataReader objects attached to the same com.rti.dds.subscription.Subscriber.

By definition, a com.rti.dds.topic.Topic corresponds to a single data type. However, several topics may refer to the same data type. Therefore, a com.rti.dds.topic.Topic identifies data of a single type, ranging from one single instance to a whole collection of instances of that given type. This is shown below for the hypothetical data type Foo.

A collection of object instances, identified by their keys, can be disseminated on a topic.

In case a set of instances is gathered under the same topic, different instances must be distinguishable. This is achieved by means of the values of some data fields that form the key to that data set. The key description (i.e., the list of data fields whose value forms the key) has to be indicated to the middleware. The rule is simple: different data samples with the same key value represent successive values for the same instance, while different data samples with different key values represent different instances. If no key is provided, the data set associated with the com.rti.dds.topic.Topic is restricted to a single instance.

Topics need to be known by the middleware and potentially propagated. Topic objects are created using the create operations provided by com.rti.dds.domain.DomainParticipant.

The interaction style is straightforward on the publisher's side: when the application decides that it wants to make data available for publication, it calls the appropriate operation on the related com.rti.dds.publication.DataWriter (this, in turn, will trigger its com.rti.dds.publication.Publisher).

On the subscriber's side however, there are more choices: relevant information may arrive when the application is busy doing something else or when the application is just waiting for that information. Therefore, depending on the way the application is designed, asynchronous notifications or synchronous access may be more appropriate. Both interaction modes are allowed, a com.rti.dds.infrastructure.Listener is used to provide a callback for synchronous access and a com.rti.dds.infrastructure.WaitSet associated with one or several com.rti.dds.infrastructure.Condition objects provides asynchronous data access.

The same synchronous and asynchronous interaction modes can also be used to access changes that affect the middleware communication status (see Status Kinds). For instance, this may occur when the middleware asynchronously detects an inconsistency. In addition, other middleware information that may be relevant to the application (such as the list of the existing topics) is made available by means of built-in topics that the application can access as plain application data, using built-in data-readers.

Modules

DCPS consists of five modules:

DCPS modules and their dependencies

• Infrastructure module defines the abstract classes and the interfaces that are refined by the other modules. It also provides support for the two interaction styles (notification-based and wait-based) with the middleware.

• Domain module contains the com.rti.dds.domain.DomainParticipant class that acts as an entrypoint of the Service and acts as a factory for many of the classes. The com.rti.dds.domain.DomainParticipant also acts as a container for the other objects that make up the Service.

• Topic module contains the com.rti.dds.topic.Topic class, the com.rti.dds.topic.TopicListener interface, and more generally, all that is needed by the application to define com.rti.dds.topic.Topic objects and attach QoS policies to them.

• Publication module contains the com.rti.dds.publication.Publisher and com.rti.dds.publication.DataWriter classes as well as the com.rti.dds.publication.PublisherListener and com.rti.dds.publication.DataWriterListener interfaces, and more generally, all that is needed on the publication side.

• Subscription module contains the com.rti.dds.subscription.Subscriber, com.rti.dds.subscription.DataReader, com.rti.dds.subscription.ReadCondition, and com.rti.dds.subscription.QueryCondition classes, as well as the com.rti.dds.subscription.SubscriberListener and com.rti.dds.subscription.DataReaderListener interfaces, and more generally, all that is needed on the subscription side.