Package org.omg.dds.core.status

Statuses may be classified as: Read communication statuses: i.e., those that are related to arrival of data, namely DataOnReadersEvent and DataAvailableEvent.

See: Description

Class Summary

Class	Description
DataAvailableStatus
DataOnReadersStatus
InconsistentTopicStatus	Another topic exists with the same name but different characteristics.
LivelinessChangedStatus	The liveliness of one or more DataWriters that were writing instances read through the DataReader has changed.
LivelinessLostStatus	The liveliness that the DataWriter has committed through its Liveliness was not respected; thus DataReader entities will consider the DataWriter as no longer "active."
OfferedDeadlineMissedStatus	The deadline that the DataWriter has committed through its Deadline was not respected for a specific instance.
OfferedIncompatibleQosStatus	A QosPolicy value was incompatible with what was requested.
PublicationMatchedStatus	The DataWriter has found a DataReader that matches the Topic and has compatible QoS, or has ceased to be matched with a DataReader that was previously considered to be matched.
RequestedDeadlineMissedStatus	The deadline that the DataReader was expecting through its Deadline was not respected for a specific instance.
RequestedIncompatibleQosStatus	A QosPolicy value was incompatible with what is offered.
SampleLostStatus	A sample has been lost (never received).
SampleRejectedStatus	A (received) sample has been rejected.
Status	Status is the abstract root class for all communication status objects.
SubscriptionMatchedStatus	The DataReader has found a DataWriter that matches the Topic and has compatible QoS, or has ceased to be matched with a DataWriter that was previously considered to be matched.

Enum Summary

Enum	Description
SampleRejectedStatus.Kind

Package org.omg.dds.core.status Description

Statuses may be classified as:

• Read communication statuses: i.e., those that are related to arrival of data, namely DataOnReadersEvent and DataAvailableEvent.
• Plain communication statuses: i.e., all the others.

Read communication statuses are treated slightly differently than the others for they don't change independently. In other words, at least two changes will appear at the same time (DATA_ON_READERS + DATA_AVAILABLE) and even several of the last kind may be part of the set. This 'grouping' has to be communicated to the application. For each communication status, there is a corresponding structure to hold the status value. These values contain the information related to the change of status, as well as information related to the statuses themselves (e.g., contains cumulative counts). They are used with the two different status-access mechanisms. Associated with each one of an Entity's communication status is a logical "StatusChangedFlag." This flag indicates whether that particular communication status has changed since the last time the status was "read" by the application. The way the status changes is slightly different for the Plain Communication Status and the Read Communication status. Note that this description is only conceptual; it simply represents that the Entity knows which specific statuses have changed. It does not imply any particular implementation of the StatusChangedFlag in terms of boolean values. Changes in Plain Communication Status For the plain communication status, the StatusChangedFlag flag is initially set to false. It becomes true whenever the plain communication status changes and it is reset to false each time the application accesses the plain communication status via the proper get operation on the Entity. The communication status is also reset to false whenever the associated listener operation is called as the listener implicitly accesses the status which is passed as a parameter to the operation. The fact that the status is reset prior to calling the listener means that if the application calls the get operation from inside the listener it will see the status already reset. An exception to this rule is when the associated listener is null. Such a listener is treated as a NO-OP and the act of "calling" a null listener does not reset the communication status. For example, the value of the StatusChangedFlag associated with the RequestedDeadlineMissedStatus will become true each time new deadline occurs (which increases the totalCount field within RequestedDeadlineMissedStatus). The value changes to false when the application accesses the status via DataReader.getRequestedDeadlineMissedStatus(). Changes in Read Communication Statuses For the read communication status, the StatusChangedFlag flag is initially set to false. The StatusChangedFlag becomes true when either a data sample arrives or else the ViewState, SampleState, or InstanceState of any existing sample changes for any reason other than a call to DataReader.read(),\ DataReader.take() or their variants. Specifically any of the following events will cause the StatusChangedFlag to become true:

• The arrival of new data.
• A change in the InstanceState of a contained instance. This can be caused by either:
  • The arrival of the notification that an instance has been disposed by:
    • the DataWriter that owns it if Ownership.getKind() = Ownership.Kind.EXCLUSIVE
    • or by any DataWriter if Ownership.getKind() = Ownership.Kind.SHARED.
  • The loss of liveliness of the DataWriter of an instance for which there is no other DataWriter.
  • The arrival of the notification that an instance has been unregistered by the only DataWriter that is known to be writing the instance.

Depending on the kind of StatusChangedFlag, the flag transitions to false again as follows:

• The DATA_AVAILABLE StatusChangedFlag becomes false when either the DataReaderListener.onDataAvailable(DataAvailableEvent) is called or the DataReader.read() or DataReader.take() operation (or their variants) is called on the associated DataReader.
• The DATA_ON_READERS StatusChangedFlag becomes false when any of the following events occur:
  • SubscriberListener.onDataOnReaders(DataOnReadersEvent) is called.
  • DataReaderListener.onDataAvailable(DataAvailableEvent) is called on any DataReader belonging to the Subscriber.
  • The DataReader.read() or DataReader.take() operation (or their variants) is called on any DataReader belonging to the Subscriber.

Access through Listeners Listeners provide a mechanism for the middleware to asynchronously alert the application of the occurrence of relevant status changes. All Entity types support a listener, the type of which is specialized to the specific type of the related Entity (e.g. DataReaderListener for the DataReader). Listeners are interfaces that the application must implement. Each dedicated listener presents a list of operations that correspond to the relevant communication status changes (i.e. that the application may react to). Listeners are stateless. It is thus possible to share the same DataReaderListener instance among all the DataReader objects (assuming that they will react similarly on similar status changes). Consequently, the provided parameter contains a reference to the actual concerned Entity (see EventObject.getSource()). Conditions and Wait-sets As previously mentioned, Conditions (in conjunction with WaitSets) provide an alternative mechanism to allow the middleware to communicate communication status changes (including arrival of data) to the application.