org.omg.dds.sub

Interface Subscriber

All Superinterfaces:

AutoCloseable, Closeable, DDSObject, DomainEntity<SubscriberListener,SubscriberQos>, Entity<SubscriberListener,SubscriberQos>

public interface Subscriber
extends DomainEntity<SubscriberListener,SubscriberQos>

A Subscriber is the object responsible for the actual reception of the data resulting from its subscriptions. A Subscriber acts on the behalf of one or several DataReader objects that are related to it. When it receives data (from the other parts of the system), it builds the list of concerned DataReader objects, and then indicates to the application that data is available, through its listener or by enabling related conditions. The application can access the list of concerned DataReader objects through the operation getDataReaders(Collection) and then access the data available through operations on the DataReaders. All operations except for the inherited operations Entity.setQos(org.omg.dds.core.EntityQos), Entity.getQos(), Entity.setListener(java.util.EventListener), Entity.getListener(), Entity.enable(), Entity.getStatusCondition(), and createDataReader(TopicDescription) may fail with the exception NotEnabledException.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Subscriber.DataState A DataState encapsulates sets of sample states, view states, and instance states as a convenience.

Method Summary

Methods

Modifier and Type	Method and Description
void	beginAccess() This operation indicates that the application is about to access the data samples in any of the DataReader objects attached to the Subscriber.
void	closeContainedEntities() This operation closes all the entities that were created by means of the "create" operations on the Subscriber.
DataReaderQos	copyFromTopicQos(DataReaderQos drQos, TopicQos tQos) This operation copies the policies in the TopicQos to the corresponding policies in the DataReaderQos (replacing values in the latter, if present).
<TYPE> DataReader<TYPE>	createDataReader(TopicDescription<TYPE> topic) This operation creates a DataReader.
<TYPE> DataReader<TYPE>	createDataReader(TopicDescription<TYPE> topic, DataReaderQos qos) This operation creates a DataReader.
<TYPE> DataReader<TYPE>	createDataReader(TopicDescription<TYPE> topic, DataReaderQos qos, DataReaderListener<TYPE> listener, Collection<Class<? extends Status>> statuses) This operation creates a DataReader.
Subscriber.DataState	createDataState() Create and return a new modifiable Subscriber.DataState object.
void	endAccess() Indicates that the application has finished accessing the data samples in DataReader objects managed by the Subscriber.
Collection<DataReader<?>>	getDataReaders(Collection<DataReader<?>> readers) This operation is equivalent to calling getDataReaders(Collection, DataState) with any sample state (Subscriber.DataState.withAnySampleState()), any view state (Subscriber.DataState.withAnyViewState()), and any instance state (Subscriber.DataState.withAnyInstanceState()).
Collection<DataReader<?>>	getDataReaders(Collection<DataReader<?>> readers, Subscriber.DataState dataState) This operation allows the application to access the DataReader objects that contain samples with the specified sample states, view states, and instance states.
DataReaderQos	getDefaultDataReaderQos() This operation retrieves the default value of the DataReader QoS, that is, the QoS policies which will be used for newly created DataReader entities in the case where the QoS policies are defaulted in the createDataReader(TopicDescription) operation.
DomainParticipant	getParent()
StatusCondition<Subscriber>	getStatusCondition() This operation allows access to the StatusCondition associated with the Entity.
<TYPE> DataReader<TYPE>	lookupDataReader(String topicName) This operation retrieves a previously-created DataReader belonging to the Subscriber that is attached to a Topic with a matching topicName.
<TYPE> DataReader<TYPE>	lookupDataReader(TopicDescription<TYPE> topicName) This operation retrieves a previously-created DataReader belonging to the Subscriber that is attached to the given TopicDescription.
void	notifyDataReaders() This operation invokes the operation DataReaderListener.onDataAvailable(org.omg.dds.core.event.DataAvailableEvent) on the DataReaderListener objects attached to contained DataReader entities with a DataAvailableEvent that is considered changed.
void	setDefaultDataReaderQos(DataReaderQos qos) This operation sets a default value of the DataReader QoS policies, which will be used for newly created DataReader entities in the case where the QoS policies are defaulted in the createDataReader(TopicDescription) operation.

Methods inherited from interface org.omg.dds.core.Entity

close, enable, getInstanceHandle, getListener, getQos, getStatusChanges, retain, setListener, setListener, setQos, setQos

Methods inherited from interface org.omg.dds.core.DDSObject

getEnvironment

Method Detail

createDataReader

<TYPE> DataReader<TYPE> createDataReader(TopicDescription<TYPE> topic)

This operation creates a DataReader. The returned DataReader will be attached and belong to the Subscriber. Note that a common application pattern to construct the QoS for the DataReader is to:

• Retrieve the QoS policies on the associated Topic by means of Entity.getQos().
• Retrieve the default DataReader QoS by means of getDefaultDataReaderQos().
• Combine those two QoS policies and selectively modify policies as desired.
• Use the resulting QoS policies to construct the DataReader.

The TopicDescription passed to this operation must have been created from the same DomainParticipant that was used to create this Subscriber. If the TopicDescription was created from a different DomainParticipant, the operation will fail.

See Also:

createDataReader(TopicDescription, DataReaderQos, DataReaderListener, Collection)

createDataReader

<TYPE> DataReader<TYPE> createDataReader(TopicDescription<TYPE> topic,
                                       DataReaderQos qos,
                                       DataReaderListener<TYPE> listener,
                                       Collection<Class<? extends Status>> statuses)

This operation creates a DataReader. The returned DataReader will be attached and belong to the Subscriber. Note that a common application pattern to construct the QoS for the DataReader is to:

• Retrieve the QoS policies on the associated Topic by means of Entity.getQos().
• Retrieve the default DataReader QoS by means of getDefaultDataReaderQos().
• Combine those two QoS policies and selectively modify policies as desired.
• Use the resulting QoS policies to construct the DataReader.

The TopicDescription passed to this operation must have been created from the same DomainParticipant that was used to create this Subscriber. If the TopicDescription was created from a different DomainParticipant, the operation will fail.

Parameters:

statuses - Of which status changes the listener should be notified. A null collection signifies all status changes.

See Also:

createDataReader(TopicDescription)

createDataReader

<TYPE> DataReader<TYPE> createDataReader(TopicDescription<TYPE> topic,
                                       DataReaderQos qos)

This operation creates a DataReader. The returned DataReader will be attached and belong to the Subscriber.

Parameters:

topic - The TopicDescription created from the same DomainParticipant that was used to create this Subscriber.

qos - An instance of (@link org.omg.dds.sub.DataReaderQos} or null.

Returns:

DataReader

See Also:

createDataReader(TopicDescription)

lookupDataReader

<TYPE> DataReader<TYPE> lookupDataReader(String topicName)

This operation retrieves a previously-created DataReader belonging to the Subscriber that is attached to a Topic with a matching topicName. If no such DataReader exists, the operation will return null. If multiple DataReaders attached to the Subscriber satisfy this condition, then the operation will return one of them. It is not specified which one. The use of this operation on the built-in Subscriber allows access to the built-in DataReader entities for the built-in topics.

See Also:

DomainParticipant.getBuiltinSubscriber()

lookupDataReader

<TYPE> DataReader<TYPE> lookupDataReader(TopicDescription<TYPE> topicName)

This operation retrieves a previously-created DataReader belonging to the Subscriber that is attached to the given TopicDescription. If no such DataReader exists, the operation will return null. If multiple DataReaders attached to the Subscriber satisfy this condition, then the operation will return one of them. It is not specified which one. The use of this operation on the built-in Subscriber allows access to the built-in DataReader entities for the built-in topics.

See Also:

DomainParticipant.getBuiltinSubscriber()

closeContainedEntities

void closeContainedEntities()

This operation closes all the entities that were created by means of the "create" operations on the Subscriber. That is, it closes all contained DataReader objects. This pattern is applied recursively. In this manner the operation on the Subscriber will end up closing all the entities recursively contained in the Subscriber, that is also the QueryCondition and ReadCondition objects belonging to the contained DataReaders.

Throws:

PreconditionNotMetException - if any of the contained entities is in a state where it cannot be closed. This will occur, for example, if a contained DataReader cannot be closed because the application has called a DataReader.read() or DataReader.take() operation and has not called the corresponding Sample.Iterator.close() operation to return the loaned samples.

getDataReaders

Collection<DataReader<?>> getDataReaders(Collection<DataReader<?>> readers)

This operation is equivalent to calling getDataReaders(Collection, DataState) with any sample state (Subscriber.DataState.withAnySampleState()), any view state (Subscriber.DataState.withAnyViewState()), and any instance state (Subscriber.DataState.withAnyInstanceState()).

Parameters:

readers - a container, into which this method will place its result.

Returns:

readers, as a convenience to facilitate chaining.

Throws:

PreconditionNotMetException - if the Subscriber has Presentation.getAccessScope() set to Presentation.AccessScopeKind.GROUP and this operation is not invoked inside a beginAccess()/endAccess() block.

See Also:

getDataReaders(Collection, DataState), beginAccess(), endAccess(), Presentation

getDataReaders

Collection<DataReader<?>> getDataReaders(Collection<DataReader<?>> readers,
                                       Subscriber.DataState dataState)

This operation allows the application to access the DataReader objects that contain samples with the specified sample states, view states, and instance states. If the Presentation of the Subscriber has Presentation.getAccessScope() set to Presentation.AccessScopeKind.GROUP, this operation should only be invoked inside a beginAccess()/ endAccess() block. Otherwise it will fail with PreconditionNotMetException. Depending on the setting of the Presentation, the returned collection of DataReader objects may be a 'set' containing each DataReader at most once in no specified order, or a 'list' containing each DataReader one or more times in a specific order. (This refers to the semantics of the collection; the concrete type of the collection may or may not implement Set or List).

1. If Presentation.getAccessScope() is Presentation.AccessScopeKind.INSTANCE or Presentation.AccessScopeKind.TOPIC, the returned collection is a 'set'.
2. If Presentation.getAccessScope() is Presentation.AccessScopeKind.GROUP and Presentation.isOrderedAccess() is true, then the returned collection is a 'list'.

This difference is due to the fact that, in the second situation it is required to access samples belonging to different DataReader objects in a particular order. In this case, the application should process each DataReader in the same order it appears in the 'list' and read or take exactly one sample from each DataReader.

Parameters:

readers - a container, into which this method will place its result.

dataState - a DataReader will only be placed into the readers collection if it has data available with one of these sample states, view states, and instance states.

Returns:

readers, as a convenience to facilitate chaining.

Throws:

PreconditionNotMetException - if the Subscriber has Presentation.getAccessScope() set to Presentation.AccessScopeKind.GROUP and this operation is not invoked inside a beginAccess()/endAccess() block.

See Also:

getDataReaders(Collection), beginAccess(), endAccess(), Presentation

notifyDataReaders

void notifyDataReaders()

This operation invokes the operation DataReaderListener.onDataAvailable(org.omg.dds.core.event.DataAvailableEvent) on the DataReaderListener objects attached to contained DataReader entities with a DataAvailableEvent that is considered changed. This operation is typically invoked from SubscriberListener.onDataOnReaders(org.omg.dds.core.event.DataOnReadersEvent). That way the SubscriberListener can delegate to the DataReaderListener objects the handling of the data.

beginAccess

void beginAccess()

This operation indicates that the application is about to access the data samples in any of the DataReader objects attached to the Subscriber. The application is required to use this operation only if the Presentation of the Subscriber has Presentation.getAccessScope() equal to Presentation.AccessScopeKind.GROUP. In the aforementioned case, the operation must be called prior to calling any of the sample-accessing operations, namely: getDataReaders(Collection), DataReader.read(), DataReader.take(), or their overloads. Otherwise the sample-accessing operations will fail with PreconditionNotMetException. Once the application has finished accessing the data samples it must call endAccess(). It is not required for the application to call beginAccess()/ endAccess() if the Presentation has the access scope set to something other than 'GROUP'. Calling these methods in this case is not considered an error and has no effect. The calls to beginAccess()/endAccess() may be nested. In that case, the application must call endAccess() as many times as it called beginAccess.

See Also:

endAccess(), Presentation

endAccess

void endAccess()

Indicates that the application has finished accessing the data samples in DataReader objects managed by the Subscriber. This operation must be used to 'close' a corresponding beginAccess(). After calling endAccess the application should no longer access any of the Sample (including corresponding data) elements returned from the sample-accessing operations.

Throws:

PreconditionNotMetException - if this call does not close a previous call to beginAccess().

See Also:

beginAccess()

getDefaultDataReaderQos

DataReaderQos getDefaultDataReaderQos()

This operation retrieves the default value of the DataReader QoS, that is, the QoS policies which will be used for newly created DataReader entities in the case where the QoS policies are defaulted in the createDataReader(TopicDescription) operation. The values retrieved will match the set of values specified on the last successful call to setDefaultDataReaderQos(DataReaderQos), or else, if the call was never made, the default values identified by the DDS specification.

See Also:

setDefaultDataReaderQos(DataReaderQos)

setDefaultDataReaderQos

void setDefaultDataReaderQos(DataReaderQos qos)

This operation sets a default value of the DataReader QoS policies, which will be used for newly created DataReader entities in the case where the QoS policies are defaulted in the createDataReader(TopicDescription) operation.

Throws:

InconsistentPolicyException - if the resulting policies are not self consistent. In this case, this operation will have no effect.

See Also:

getDefaultDataReaderQos()

copyFromTopicQos

DataReaderQos copyFromTopicQos(DataReaderQos drQos,
                             TopicQos tQos)

This operation copies the policies in the TopicQos to the corresponding policies in the DataReaderQos (replacing values in the latter, if present). This is a "convenience" operation most useful in combination with the operations getDefaultDataReaderQos() and Entity.getQos(). The operation can be used to merge the DataReader default QoS policies with the corresponding ones on the Topic. The resulting QoS can then be used to create a new DataReader or set its QoS. This operation does not check the resulting QoS for consistency. This is because the 'merged' QoS may not be the final one, as the application can still modify some policies prior to applying the policies to the DataReader.

Parameters:

drQos - The QoS, the policies of which will be overridden. This object is not modified.

tQos - The source for the new policies to be copied. This object is not modified.

Returns:

A copy of drQos with the applicable policies from tQos applied to it.

getStatusCondition

StatusCondition<Subscriber> getStatusCondition()

Description copied from interface: Entity

This operation allows access to the StatusCondition associated with the Entity. The returned condition can then be added to a WaitSet so that the application can wait for specific status changes that affect the Entity.

Specified by:

getStatusCondition in interface Entity<SubscriberListener,SubscriberQos>

getParent

DomainParticipant getParent()

Specified by:

getParent in interface DomainEntity<SubscriberListener,SubscriberQos>

Returns:

the factory object that created this entity.

createDataState

Subscriber.DataState createDataState()

Create and return a new modifiable Subscriber.DataState object. This object will be initialized with no sample states, no instance states, and no view states. This method shall never return null.

Returns:

a new Subscriber.DataState object.