Listener Interface Reference
[Entity Support]

<<interface>> Abstract base class for all Listener interfaces. More...

Inheritance diagram for Listener:

---

Detailed Description

<<interface>> Abstract base class for all Listener interfaces.

Entity:

com.rti.dds.infrastructure.Entity

QoS:

QoS Policies

Status:

Status Kinds

All the supported kinds of concrete com.rti.dds.infrastructure.Listener interfaces (one per concrete com.rti.dds.infrastructure.Entity type) derive from this root and add methods whose prototype depends on the concrete Listener.

Listeners provide a way for RTI Connext to asynchronously alert the application when there are relevant status changes.

Almost every application will have to implement listener interfaces.

Each dedicated listener presents a list of operations that correspond to the relevant communication status changes to which an application may respond.

The same com.rti.dds.infrastructure.Listener instance may be shared among multiple entities if you so desire. Consequently, the provided parameter contains a reference to the concerned com.rti.dds.infrastructure.Entity.

Access to Plain Communication Status

The general mapping between the plain communication statuses (see Status Kinds) and the listeners' operations is as follows:

• For each communication status, there is a corresponding operation whose name is on_<communication_status>(), which takes a parameter of type <communication_status> as listed in Status Kinds.

• on_<communication_status> is available on the relevant com.rti.dds.infrastructure.Entity as well as those that embed it, as expressed in the following figure:

Hierarchical listener processing. The most specific relevant enabled listener is called.

• When the application attaches a listener on an entity, it must set a mask. The mask indicates to RTI Connext which operations are enabled within the listener (cf. operation com.rti.dds.infrastructure.Entity set_listener() ).

• When a plain communication status changes, RTI Connext triggers the most specific relevant listener operation that is enabled. In case the most specific relevant listener operation corresponds to an application-installed 'nil' listener the operation will be considered handled by a NO-OP operation that does not reset the communication status.

This behavior allows the application to set a default behavior (e.g., in the listener associated with the com.rti.dds.domain.DomainParticipant) and to set dedicated behaviors only where needed.

Access to Read Communication Status

The two statuses related to data arrival are treated slightly differently. Since they constitute the core purpose of the Data Distribution Service, there is no need to provide a default mechanism (as is done for the plain communication statuses above).

The rule is as follows. Each time the read communication status changes:

• First, RTI Connext tries to trigger the com.rti.dds.subscription.SubscriberListener.on_data_on_readers with a parameter of the related com.rti.dds.subscription.Subscriber;

• If this does not succeed (there is no listener or the operation is not enabled), RTI Connext tries to trigger com.rti.dds.subscription.DataReaderListener.on_data_available on all the related com.rti.dds.subscription.DataReaderListener objects, with a parameter of the related com.rti.dds.subscription.DataReader.

The rationale is that either the application is interested in relations among data arrivals and it must use the first option (and then get the corresponding com.rti.dds.subscription.DataReader objects by calling com.rti.dds.subscription.Subscriber.get_datareaders on the related com.rti.dds.subscription.Subscriber and then get the data by calling com.rti.dds.topic.example.FooDataReader.read or com.rti.dds.topic.example.FooDataReader.take on the returned com.rti.dds.subscription.DataReader objects), or it wants to treat each com.rti.dds.subscription.DataReader independently and it may choose the second option (and then get the data by calling com.rti.dds.topic.example.FooDataReader.read or com.rti.dds.topic.example.FooDataReader.take on the related com.rti.dds.subscription.DataReader).

Note that if com.rti.dds.subscription.SubscriberListener.on_data_on_readers is called, RTI Connext will not try to call com.rti.dds.subscription.DataReaderListener.on_data_available. However, an application can force a call to the com.rti.dds.subscription.DataReader objects that have data by calling com.rti.dds.subscription.Subscriber.notify_datareaders.

Operations Allowed in Listener Callbacks

The operations that are allowed in com.rti.dds.infrastructure.Listener callbacks depend on the com.rti.dds.infrastructure.ExclusiveAreaQosPolicy QoS policy of the com.rti.dds.infrastructure.Entity to which the com.rti.dds.infrastructure.Listener is attached -- or in the case of a com.rti.dds.publication.DataWriter of com.rti.dds.subscription.DataReader listener, on the com.rti.dds.infrastructure.ExclusiveAreaQosPolicy QoS of the parent com.rti.dds.publication.Publisher or com.rti.dds.subscription.Subscriber. For instance, the com.rti.dds.infrastructure.ExclusiveAreaQosPolicy settings of a com.rti.dds.subscription.Subscriber will determine which operations are allowed within the callbacks of the listeners associated with all the DataReaders created through that com.rti.dds.subscription.Subscriber.

Note: these restrictions do not apply to builtin topic listener callbacks.

Regardless of whether com.rti.dds.infrastructure.ExclusiveAreaQosPolicy.use_shared_exclusive_area is set to true or false, the following operations are not allowed:

• Within any listener callback, deleting the entity to which the com.rti.dds.infrastructure.Listener is attached
• Within a com.rti.dds.topic.Topic listener callback, any operations on any subscribers, readers, publishers or writers

An attempt to call a disallowed method from within a callback will result in RETCODE_ILLEGAL_OPERATION.

If com.rti.dds.infrastructure.ExclusiveAreaQosPolicy.use_shared_exclusive_area is set to false, the setting which allows more concurrency among RTI Connext threads, the following are not allowed:

• Within any listener callback, creating any entity
• Within any listener callback, deleting any entity
• Within any listener callback, enabling any entity
• Within any listener callback, setting the QoS of any entities
• Within a com.rti.dds.subscription.DataReader or com.rti.dds.subscription.Subscriber listener callback, invoking any operation on any other com.rti.dds.subscription.Subscriber or on any com.rti.dds.subscription.DataReader belonging to another com.rti.dds.subscription.Subscriber.
• Within a com.rti.dds.subscription.DataReader or com.rti.dds.subscription.Subscriber listener callback, invoking any operation on any com.rti.dds.publication.Publisher (or on any com.rti.dds.publication.DataWriter belonging to such a com.rti.dds.publication.Publisher) that has com.rti.dds.infrastructure.ExclusiveAreaQosPolicy.use_shared_exclusive_area set to true.
• Within a com.rti.dds.publication.DataWriter of com.rti.dds.publication.Publisher listener callback, invoking any operation on another Publisher or on a com.rti.dds.publication.DataWriter belonging to another com.rti.dds.publication.Publisher.
• Within a com.rti.dds.publication.DataWriter of com.rti.dds.publication.Publisher listener callback, invoking any operation on any com.rti.dds.subscription.Subscriber or com.rti.dds.subscription.DataReader.

An attempt to call a disallowed method from within a callback will result in RETCODE_ILLEGAL_OPERATION.

The above limitations can be lifted by setting com.rti.dds.infrastructure.ExclusiveAreaQosPolicy.use_shared_exclusive_area to true on the com.rti.dds.publication.Publisher or com.rti.dds.subscription.Subscriber (or on the com.rti.dds.publication.Publisher/ com.rti.dds.subscription.Subscriber of the com.rti.dds.publication.DataWriter/com.rti.dds.subscription.DataReader) to which the listener is attached. However, the application will pay the cost of reduced concurrency between the affected publishers and subscribers.

See also:

EXCLUSIVE_AREA

Status Kinds

com.rti.dds.infrastructure.WaitSet, com.rti.dds.infrastructure.Condition