A Subscriber is the object responsible for the actual reception of the data resulting from its subscriptions. More...

Inheritance diagram for org.omg.dds.sub.Subscriber:

Collaboration diagram for org.omg.dds.sub.Subscriber:

Classes
interface	DataState
	A DataState encapsulates sets of sample states, view states, and instance states as a convenience. More...

Public Member Functions
void	beginAccess ()
	This operation indicates that the application is about to access the data samples in any of the org.omg.dds.sub.DataReader objects attached to the Subscriber. More...

abstract void	close ()
	Halt communication and dispose the resources held by this Entity. More...

void	closeContainedEntities ()
	This operation closes all the entities that were created by means of the "create" operations on the Subscriber. More...

DataReaderQos	copyFromTopicQos (DataReaderQos drQos, TopicQos tQos)
	This operation copies the policies in the org.omg.dds.topic.TopicQos to the corresponding policies in the org.omg.dds.sub.DataReaderQos (replacing values in the latter, if present). More...

public< TYPE > DataReader< TYPE >	createDataReader (TopicDescription< TYPE > topic)
	This operation creates a org.omg.dds.sub.DataReader. More...

public< TYPE > DataReader< TYPE >	createDataReader (TopicDescription< TYPE > topic, DataReaderQos qos, DataReaderListener< TYPE > listener, Collection< Class<? extends Status >> statuses)
	This operation creates a org.omg.dds.sub.DataReader. More...

public< TYPE > DataReader< TYPE >	createDataReader (TopicDescription< TYPE > topic, DataReaderQos qos, DataReaderListener< TYPE > listener, Class<? extends Status >... statuses)
	This operation creates a org.omg.dds.sub.DataReader. More...

public< TYPE > DataReader< TYPE >	createDataReader (TopicDescription< TYPE > topic, DataReaderQos qos)
	This operation creates a org.omg.dds.sub.DataReader. More...

DataState	createDataState ()
	Create and return a new modifiable DataState object. More...

void	enable ()
	This operation enables the Entity. More...

void	endAccess ()
	Indicates that the application has finished accessing the data samples in org.omg.dds.sub.DataReader objects managed by the Subscriber. More...

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

Collection< DataReader<?> >	getDataReaders (DataState dataState)
	This operation allows the application to access the org.omg.dds.sub.DataReader objects that contain samples with the specified sample states, view states, and instance states. More...

DataReaderQos	getDefaultDataReaderQos ()
	This operation retrieves the default value of the DataReader QoS, that is, the QoS policies which will be used for newly created org.omg.dds.sub.DataReader entities in the case where the QoS policies are defaulted in the createDataReader(TopicDescription) operation. More...

InstanceHandle	getInstanceHandle ()

LISTENER	getListener ()
	This operation allows access to the existing Listener attached to the Entity. More...

DomainParticipant	getParent ()

QOS	getQos ()
	This operation allows access to the existing set of QoS policies for the Entity. More...

Set< Class<? extends Status > >	getStatusChanges ()
	This operation retrieves the list of communication statuses in the Entity that are 'triggered. More...

StatusCondition< Subscriber >	getStatusCondition ()

public< TYPE > DataReader< TYPE >	lookupDataReader (String topicName)
	This operation retrieves a previously-created DataReader belonging to the Subscriber that is attached to a org.omg.dds.topic.Topic with a matching topicName. More...

public< TYPE > DataReader< TYPE >	lookupDataReader (TopicDescription< TYPE > topicName)
	This operation retrieves a previously-created DataReader belonging to the Subscriber that is attached to the given org.omg.dds.topic.TopicDescription. More...

void	notifyDataReaders ()
	This operation invokes the operation org.omg.dds.sub.DataReaderListener#onDataAvailable(org.omg.dds.core.event.DataAvailableEvent) on the DataReaderListener objects attached to contained DataReader entities with a org.omg.dds.core.event.DataAvailableEvent that is considered changed. More...

void	retain ()
	Indicates that references to this object may go out of scope but that the application expects to look it up again later. More...

void	setDefaultDataReaderQos (DataReaderQos qos)
	This operation sets a default value of the DataReader QoS policies, which will be used for newly created org.omg.dds.sub.DataReader entities in the case where the QoS policies are defaulted in the createDataReader(TopicDescription) operation. More...

void	setListener (LISTENER listener)
	This operation installs a Listener on the Entity. More...

void	setListener (LISTENER listener, Collection< Class<? extends Status >> statuses)
	This operation installs a Listener on the Entity. More...

void	setListener (LISTENER listener, Class<? extends Status >... statuses)
	This operation installs a Listener on the Entity. More...

void	setQos (QOS qos)
	This operation is used to set the QoS policies of the Entity. More...

Detailed Description

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 org.omg.dds.sub.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() and then access the data available through operations on the DataReaders.

All operations except for the inherited operations org.omg.dds.core.Entity#setQos(org.omg.dds.core.EntityQos), org.omg.dds.core.Entity#getQos(), org.omg.dds.core.Entity#setListener(java.util.EventListener), org.omg.dds.core.Entity#getListener(), org.omg.dds.core.Entity#enable(), org.omg.dds.core.Entity#getStatusCondition(), and createDataReader(TopicDescription) may fail with the exception org.omg.dds.core.NotEnabledException.

Example

This example assumes a DomainParticipant named "participant" has been created
and a datatype called Foo is present: class Foo { int myKey; String myName; };

// Create a topic named "FooTopic" using the default QoS and no Listener.
Topic<Foo> fooTopic = participant.createTopic("FooTopic", Foo.class);

// Create a Subscriber using default Qos and no Listener.
Subscriber mySub = participant.createSubscriber();

Definition at line 69 of file Subscriber.java.

Member Function Documentation

◆ beginAccess()

void org.omg.dds.sub.Subscriber.beginAccess ( )

This operation indicates that the application is about to access the data samples in any of the org.omg.dds.sub.DataReader objects attached to the Subscriber.

The application is required to use this operation only if the org.omg.dds.core.policy.Presentation of the Subscriber has org.omg.dds.core.policy.Presentation#getAccessScope() equal to org.omg.dds.core.policy.Presentation.AccessScopeKind#GROUP.

In the aforementioned case, the operation must be called prior to calling any of the sample-accessing operations, namely: getDataReaders(), org.omg.dds.sub.DataReader#read(), org.omg.dds.sub.DataReader#take(), or their overloads. Otherwise the sample-accessing operations will fail with org.omg.dds.core.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 org.omg.dds.core.policy.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.

Note that a coherent subscriber should first be enabled, otherwise this operation throws a DDSException. See org.omg.dds.core.Entity#enable() for more information on coherent access.

Exceptions

org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding Subscriber has been closed.
org.omg.dds.core.PreconditionNotMetException	When the PresentationQos has not set AccessScope to GROUP

See also: endAccess(); org.omg.dds.core.policy.Presentation

Implemented in org.opensplice.dds.sub.SubscriberImpl.

◆ close()

abstract void org.omg.dds.core.Entity< LISTENER extends EventListener, QOS extends EntityQos<?>.close ( )

abstractinherited

Halt communication and dispose the resources held by this Entity.

Closing an Entity implicitly closes all of its contained objects, if any. For example, closing a Publisher also closes all of its contained DataWriters.

An Entity cannot be closed if it has any unclosed dependent objects, not including contained objects. These include the following:

A org.omg.dds.topic.Topic cannot be closed if it is still in use by any org.omg.dds.topic.ContentFilteredTopics or org.omg.dds.topic.MultiTopics.
A Topic cannot be closed if any org.omg.dds.pub.DataWriters or org.omg.dds.sub.DataReader is still using it.
A DataReader cannot be closed if it has any outstanding loans as a result of a call to org.omg.dds.sub.DataReader#read(), org.omg.dds.sub.DataReader#take(), or one of the variants thereof.

The deletion of a org.omg.dds.pub.DataWriter will automatically unregister all instances. Depending on the settings of the org.omg.dds.core.policy.WriterDataLifecycle, the deletion of the DataWriter may also dispose all instances.

Exceptions

PreconditionNotMetException if close is called on an Entity with unclosed dependent object(s), not including contained objects.

See also: org.omg.dds.topic.TopicDescription::close()

◆ closeContainedEntities()

void org.omg.dds.sub.Subscriber.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 org.omg.dds.sub.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 org.omg.dds.sub.QueryCondition and org.omg.dds.sub.ReadCondition objects belonging to the contained DataReaders.

Exceptions

org.omg.dds.core.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 org.omg.dds.sub.DataReader#read() or org.omg.dds.sub.DataReader#take() operation and has not called the corresponding Sample.Iterator#close() operation to return the loaned samples.

Implemented in org.opensplice.dds.sub.SubscriberImpl.

◆ copyFromTopicQos()

DataReaderQos org.omg.dds.sub.Subscriber.copyFromTopicQos	(	DataReaderQos	drQos,
		TopicQos	tQos
	)

This operation copies the policies in the org.omg.dds.topic.TopicQos to the corresponding policies in the org.omg.dds.sub.DataReaderQos (replacing values in the latter, if present).

This is a "convenience" operation most useful in combination with the operations getDefaultDataReaderQos() and org.omg.dds.topic.Topic#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.

Exceptions

org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding Subscriber has been closed.
org.omg.dds.core.OutOfResourcesException	The Data Distribution Service ran out of resources to complete this operation.

Implemented in org.opensplice.dds.sub.SubscriberImpl.

◆ createDataReader() [1/4]

public<TYPE> DataReader<TYPE> org.omg.dds.sub.Subscriber.createDataReader ( TopicDescription< TYPE > topic )

This operation creates a org.omg.dds.sub.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 org.omg.dds.topic.Topic by means of org.omg.dds.topic.Topic#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 org.omg.dds.topic.TopicDescription passed to this operation must have been created from the same org.omg.dds.domain.DomainParticipant that was used to create this Subscriber. If the TopicDescription was created from a different DomainParticipant, the operation will fail.

Parameters

topic A reference to the topic for which the DataReader is created.

Exceptions

org.omg.dds.core.OutOfResourcesException	The Data Distribution Service ran out of resources to complete this operation.
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding Subscriber has been closed.

See also: #createDataReader(TopicDescription, DataReaderQos, DataReaderListener, Collection)

◆ createDataReader() [2/4]

public<TYPE> DataReader<TYPE> org.omg.dds.sub.Subscriber.createDataReader	(	TopicDescription< TYPE >	topic,
		DataReaderQos	qos,
		DataReaderListener< TYPE >	listener,
		Collection< Class<? extends Status >>	statuses
	)

This operation creates a org.omg.dds.sub.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 org.omg.dds.topic.Topic by means of org.omg.dds.topic.Topic#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.

For each communication status, the StatusChangedFlag flag is initially set to false. It becomes true whenever that communication status changes. For each communication status activated in the mask, the associated org.omg.dds.sub.DataReaderListener operation is invoked and the communication status is reset to false, as the listener implicitly accesses the status which is passed as a parameter to that operation. The status is reset prior to calling the listener, so if the application calls the get<status_name>Status from inside the listener it will see the status already reset. The following statuses are applicable to the DataReaderListener:

RequestedDeadlineMissedStatus
RequestedIncompatibleQosStatus
SampleRejectedStatus
LivelinessChangedStatus
DataAvailableStatus
SubscriptionMatchedStatus
SampleLostStatus

Status Propagation:

In case a communication status is not activated in the statuses of the DataReaderListener, the PublisherListener of the containing Subscriber is invoked (if attached and activated for the status that occurred). This allows the application to set a default behaviour in the SubscriberListener of the containing Subscriber and a DataReader specific behaviour when needed. In case the communication status is not activated in the statuses of the SubscriberListener as well, the communication status will be propagated to the DomainParticipantListener of the containing DomainParticipant. In case the DomainParticipantListener is also not attached or the communication status is not activated in its mask, the application is not notified of the change.

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

Returns: A DataReader object.

Parameters

topic	A reference to the topic for which the DataReader is created.
qos	The DataReaderQos for the new DataReader. In case these settings are not self consistent, no DataReader is created.
listener	A reference to the DataReaderListener instance which will be attached to the new DataReader.
statuses	A collection of statuses the listener should be notified of. A null collection signifies all status changes.

Exceptions

org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.OutOfResourcesException	The Data Distribution Service ran out of resources to complete this operation.
org.omg.dds.core.InconsistentPolicyException	The parameter qos contains conflicting QosPolicy settings.
org.omg.dds.core.AlreadyClosedException	The corresponding Subscriber has been closed.

See also: #createDataReader(TopicDescription)

◆ createDataReader() [3/4]

public<TYPE> DataReader<TYPE> org.omg.dds.sub.Subscriber.createDataReader	(	TopicDescription< TYPE >	topic,
		DataReaderQos	qos,
		DataReaderListener< TYPE >	listener,
		Class<? extends Status >...	statuses
	)

This operation creates a org.omg.dds.sub.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 org.omg.dds.topic.Topic by means of org.omg.dds.topic.Topic#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.

For each communication status, the StatusChangedFlag flag is initially set to false. It becomes true whenever that communication status changes. For each communication status activated in the mask, the associated org.omg.dds.sub.DataReaderListener operation is invoked and the communication status is reset to false, as the listener implicitly accesses the status which is passed as a parameter to that operation. The status is reset prior to calling the listener, so if the application calls the get<status_name>Status from inside the listener it will see the status already reset. The following statuses are applicable to the DataReaderListener:

RequestedDeadlineMissedStatus
RequestedIncompatibleQosStatus
SampleRejectedStatus
LivelinessChangedStatus
DataAvailableStatus
SubscriptionMatchedStatus
SampleLostStatus

Status Propagation:

In case a communication status is not activated in the statuses of the DataReaderListener, the PublisherListener of the containing Subscriber is invoked (if attached and activated for the status that occurred). This allows the application to set a default behaviour in the SubscriberListener of the containing Subscriber and a DataReader specific behaviour when needed. In case the communication status is not activated in the statuses of the SubscriberListener as well, the communication status will be propagated to the DomainParticipantListener of the containing DomainParticipant. In case the DomainParticipantListener is also not attached or the communication status is not activated in its mask, the application is not notified of the change.

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

Returns: A DataReader object.

Parameters

topic	A reference to the topic for which the DataReader is created.
qos	The DataReaderQos for the new DataReader. In case these settings are not self consistent, no DataReader is created.
listener	A reference to the DataReaderListener instance which will be attached to the new DataReader.
statuses	An arbitrary number of statuses that the listener should be notified of.

Exceptions

org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.OutOfResourcesException	The Data Distribution Service ran out of resources to complete this operation.
org.omg.dds.core.InconsistentPolicyException	The parameter qos contains conflicting QosPolicy settings.
org.omg.dds.core.AlreadyClosedException	The corresponding Subscriber has been closed.

See also: #createDataReader(TopicDescription)

◆ createDataReader() [4/4]

public<TYPE> DataReader<TYPE> org.omg.dds.sub.Subscriber.createDataReader	(	TopicDescription< TYPE >	topic,
		DataReaderQos	qos
	)

This operation creates a org.omg.dds.sub.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 org.omg.dds.topic.Topic by means of org.omg.dds.topic.Topic#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.

Parameters

topic The org.omg.dds.topic.TopicDescription created from the same org.omg.dds.domain.DomainParticipant that was used to create this Subscriber.

qos An instance of (} or null. org.omg.dds.core.DDSException An internal error has occurred. org.omg.dds.core.OutOfResourcesException The Data Distribution Service ran out of resources to complete this operation. org.omg.dds.core.InconsistentPolicyException The parameter qos contains conflicting QosPolicy settings. org.omg.dds.core.AlreadyClosedException The corresponding Subscriber has been closed. #createDataReader(TopicDescription)

◆ createDataState()

DataState org.omg.dds.sub.Subscriber.createDataState ( )

Create and return a new modifiable 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 DataState object.

Implemented in org.opensplice.dds.sub.SubscriberImpl.

◆ enable()

void org.omg.dds.core.Entity< LISTENER extends EventListener, QOS extends EntityQos<?>.enable ( )

inherited

This operation enables the Entity.

Entity objects can be created either enabled or disabled. This is controlled by the value of the org.omg.dds.core.policy.EntityFactory on the corresponding factory for the Entity.

The default setting of org.omg.dds.core.policy.EntityFactory is such that, by default, it is not necessary to explicitly call enable on newly created entities.

The enable operation is idempotent. Calling enable on an already enabled Entity has no effect.

If an Entity has not yet been enabled, the following kinds of operations may be invoked on it:

Operations to set or get an Entity's QoS policies (including default QoS policies) and listener
getStatusCondition()
'factory' operations and close()
getStatusChanges() and other get status operations (although the status of a disabled entity never changes)
'lookup' operations

Other operations may explicitly state that they may be called on disabled entities; those that do not will fail with org.omg.dds.core.NotEnabledException.

It is legal to delete an Entity that has not been enabled by calling close(). Entities created from a factory that is disabled are created disabled regardless of the setting of org.omg.dds.core.policy.EntityFactory.

Calling enable on an Entity whose factory is not enabled will fail with org.omg.dds.core.PreconditionNotMetException.

If org.omg.dds.core.policy.EntityFactory#isAutoEnableCreatedEntities() is true, the enable operation on the factory will automatically enable all entities created from the factory.

The Listeners associated with an entity are not called until the entity is enabled. org.omg.dds.core.Conditions associated with an entity that is not enabled are "inactive," that is, have a triggerValue == false.

In addition to the general description, the enable operation on a org.omg.dds.sub.Subscriber has special meaning in specific usecases. This applies only to Subscribers with PresentationQoS coherent-access set to true with access-scope set to group.

In this case the subscriber is always created in a disabled state, regardless of the factory's auto-enable created entities setting. While the subscriber remains disabled, DataReaders can be created that will participate in coherent transactions of the subscriber.

See org.omg.dds.sub.Subscriber#beginAccess() and org.omg.dds.sub.Subscriber#endAccess() for more information.

All DataReaders will also be created in a disabled state. Coherency with group access-scope requires data to be delivered as a transaction, atomically, to all eligible readers. Therefore data should not be delivered to any single DataReader immediately after it's created, as usual, but only after the application has finished creating all DataReaders for a given Subscriber. At this point, the application should enable the Subscriber which in turn enables all its DataReaders.

Note that for a DataWriter which has a corresponding Publisher with a PresentationQoS with coherent-access set to true and access-scope set to topic or group that the HistoryQoS of the DataWriter should be set to KEEP_ALL otherwise the enable operation will fail. See org.omg.dds.pub.Publisher#createDataWriter(Topic, DataWriterQos, DataWriterListener, Collection)

◆ endAccess()

void org.omg.dds.sub.Subscriber.endAccess ( )

Indicates that the application has finished accessing the data samples in org.omg.dds.sub.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.

See org.omg.dds.core.Entity#enable() for more information on coherent access.

Exceptions

org.omg.dds.core.PreconditionNotMetException	if this call does not close a previous call to beginAccess().
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding Subscriber has been closed.

See also: beginAccess()

Implemented in org.opensplice.dds.sub.SubscriberImpl.

◆ getDataReaders() [1/2]

Collection<DataReader<?> > org.omg.dds.sub.Subscriber.getDataReaders ( )

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

Returns: A collection of DataReaders that belong to this Subscriber.

Exceptions

org.omg.dds.core.PreconditionNotMetException	if the Subscriber has org.omg.dds.core.policy.Presentation#getAccessScope() set to org.omg.dds.core.policy.Presentation.AccessScopeKind#GROUP and this operation is not invoked inside a beginAccess()/endAccess() block.
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.OutOfResourcesException	The Data Distribution Service ran out of resources to complete this operation.
org.omg.dds.core.AlreadyClosedException	The corresponding Subscriber has been closed.

See also: getDataReaders(DataState); beginAccess(); endAccess(); org.omg.dds.core.policy.Presentation

Implemented in org.opensplice.dds.sub.SubscriberImpl.

◆ getDataReaders() [2/2]

Collection<DataReader<?> > org.omg.dds.sub.Subscriber.getDataReaders ( DataState dataState )

This operation allows the application to access the org.omg.dds.sub.DataReader objects that contain samples with the specified sample states, view states, and instance states.

If the org.omg.dds.core.policy.Presentation of the Subscriber has org.omg.dds.core.policy.Presentation#getAccessScope() set to org.omg.dds.core.policy.Presentation.AccessScopeKind#GROUP, this operation should only be invoked inside a beginAccess()/ endAccess() block. Otherwise it will fail with org.omg.dds.core.PreconditionNotMetException.

Depending on the setting of the org.omg.dds.core.policy.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 java.util.List).

If org.omg.dds.core.policy.Presentation#getAccessScope() is org.omg.dds.core.policy.Presentation.AccessScopeKind#INSTANCE or org.omg.dds.core.policy.Presentation.AccessScopeKind#TOPIC, the returned collection is a 'set'.
If org.omg.dds.core.policy.Presentation#getAccessScope() is org.omg.dds.core.policy.Presentation.AccessScopeKind#GROUP and org.omg.dds.core.policy.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

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: A collection of DataReaders that contain samples with the specified sample states.

Exceptions

org.omg.dds.core.PreconditionNotMetException	if the Subscriber has org.omg.dds.core.policy.Presentation#getAccessScope() set to org.omg.dds.core.policy.Presentation.AccessScopeKind#GROUP and this operation is not invoked inside a beginAccess()/endAccess() block.
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.OutOfResourcesException	The Data Distribution Service ran out of resources to complete this operation.
org.omg.dds.core.AlreadyClosedException	The corresponding Subscriber has been closed.

See also: getDataReaders(); beginAccess(); endAccess(); org.omg.dds.core.policy.Presentation

Implemented in org.opensplice.dds.sub.SubscriberImpl.

◆ getDefaultDataReaderQos()

DataReaderQos org.omg.dds.sub.Subscriber.getDefaultDataReaderQos ( )

This operation retrieves the default value of the DataReader QoS, that is, the QoS policies which will be used for newly created org.omg.dds.sub.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.

Returns: the default DataReaderQos

Exceptions

org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding Subscriber has been closed.
org.omg.dds.core.OutOfResourcesException	The Data Distribution Service ran out of resources to complete this operation.

See also: setDefaultDataReaderQos(DataReaderQos)

Implemented in org.opensplice.dds.sub.SubscriberImpl.

◆ getInstanceHandle()

InstanceHandle org.omg.dds.core.Entity< LISTENER extends EventListener, QOS extends EntityQos<?>.getInstanceHandle ( )

inherited

Returns: the org.omg.dds.core.InstanceHandle that represents the Entity.

◆ getListener()

LISTENER org.omg.dds.core.Entity< LISTENER extends EventListener, QOS extends EntityQos<?>.getListener ( )

inherited

This operation allows access to the existing Listener attached to the Entity.

Returns: The attached listener if set, or null otherwise.

See also: #setListener(EventListener); #setListener(EventListener, Collection)

◆ getParent()

DomainParticipant org.omg.dds.sub.Subscriber.getParent ( )

Returns: the factory object that created this entity.

Implements org.omg.dds.core.DomainEntity< LISTENER extends EventListener, QOS extends EntityQos<?>.

Implemented in org.opensplice.dds.sub.SubscriberImpl.

◆ getQos()

QOS org.omg.dds.core.Entity< LISTENER extends EventListener, QOS extends EntityQos<?>.getQos ( )

inherited

This operation allows access to the existing set of QoS policies for the Entity.

This operation must be provided by each of the derived Entity classes (org.omg.dds.domain.DomainParticipant, org.omg.dds.topic.Topic, org.omg.dds.pub.Publisher, org.omg.dds.pub.DataWriter, org.omg.dds.sub.Subscriber, org.omg.dds.sub.DataReader) so that the policies meaningful to the particular Entity are retrieved.

See also: #setQos(EntityQos)

◆ getStatusChanges()

Set<Class<? extends Status> > org.omg.dds.core.Entity< LISTENER extends EventListener, QOS extends EntityQos<?>.getStatusChanges ( )

inherited

This operation retrieves the list of communication statuses in the Entity that are 'triggered.

' That is, the list of statuses whose value has changed since the last time the application read the status.

When the entity is first created or if the entity is not enabled, all communication statuses are in the "untriggered" state so the list returned will be empty.

The list of statuses returned refers to the statuses that are triggered on the Entity itself and does not include statuses that apply to contained entities.

Returns: a new Set containing the triggered statuses.

◆ getStatusCondition()

StatusCondition<Subscriber> org.omg.dds.sub.Subscriber.getStatusCondition ( )

Implemented in org.opensplice.dds.sub.SubscriberImpl.

◆ lookupDataReader() [1/2]

public<TYPE> DataReader<TYPE> org.omg.dds.sub.Subscriber.lookupDataReader ( String topicName )

This operation retrieves a previously-created DataReader belonging to the Subscriber that is attached to a org.omg.dds.topic.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.

Returns: the found DataReader

Parameters

topicName The name of the Topic, which is attached to the DataReader to look for.

Exceptions

org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding Subscriber has been closed.

See also: DomainParticipant::getBuiltinSubscriber()

◆ lookupDataReader() [2/2]

public<TYPE> DataReader<TYPE> org.omg.dds.sub.Subscriber.lookupDataReader ( TopicDescription< TYPE > topicName )

This operation retrieves a previously-created DataReader belonging to the Subscriber that is attached to the given org.omg.dds.topic.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.

Returns: the found DataReader

Parameters

topicName The topic description of the Topic, which is attached to the DataReader to look for.

Exceptions

org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding Subscriber has been closed.

See also: DomainParticipant::getBuiltinSubscriber()

◆ notifyDataReaders()

void org.omg.dds.sub.Subscriber.notifyDataReaders ( )

This operation invokes the operation org.omg.dds.sub.DataReaderListener#onDataAvailable(org.omg.dds.core.event.DataAvailableEvent) on the DataReaderListener objects attached to contained DataReader entities with a org.omg.dds.core.event.DataAvailableEvent that is considered changed.

This operation is typically invoked from org.omg.dds.sub.SubscriberListener#onDataOnReaders(org.omg.dds.core.event.DataOnReadersEvent). That way the SubscriberListener can delegate to the DataReaderListener objects the handling of the data.

Implemented in org.opensplice.dds.sub.SubscriberImpl.

◆ retain()

void org.omg.dds.core.Entity< LISTENER extends EventListener, QOS extends EntityQos<?>.retain ( )

inherited

Indicates that references to this object may go out of scope but that the application expects to look it up again later.

Therefore, the Service must consider this object to be still in use and may not close it automatically.

◆ setDefaultDataReaderQos()

void org.omg.dds.sub.Subscriber.setDefaultDataReaderQos ( DataReaderQos qos )

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

Parameters

qos	The new default DataReaderQos

Exceptions

org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding Subscriber has been closed.
org.omg.dds.core.OutOfResourcesException	The Data Distribution Service ran out of resources to complete this operation.
org.omg.dds.core.InconsistentPolicyException	if the resulting policies are not self consistent. In this case, this operation will have no effect.

See also: getDefaultDataReaderQos()

Implemented in org.opensplice.dds.sub.SubscriberImpl.

◆ setListener() [1/3]

void org.omg.dds.core.Entity< LISTENER extends EventListener, QOS extends EntityQos<?>.setListener ( LISTENER listener )

inherited

This operation installs a Listener on the Entity.

The listener will only be invoked on all communication statuses pertaining to the concrete type of this entity.

It is permitted to use null as the value of the listener. The null listener behaves as a Listener whose operations perform no action.

Only one listener can be attached to each Entity. If a listener was already set, the operation will replace it with the new one. Consequently if the value null is passed for the listener parameter, any existing listener will be removed.

Parameters

listener the listener to attach.

See also: getListener(); #setListener(EventListener, Collection)

◆ setListener() [2/3]

void org.omg.dds.core.Entity< LISTENER extends EventListener, QOS extends EntityQos<?>.setListener	(	LISTENER	listener,
		Collection< Class<? extends Status >>	statuses
	)

inherited

This operation installs a Listener on the Entity.

The listener will only be invoked on the changes of communication status indicated by the specified mask.

It is permitted to use null as the value of the listener. The null listener behaves as a Listener whose operations perform no action.

Only one listener can be attached to each Entity. If a listener was already set, the operation will replace it with the new one. Consequently if the value null is passed for the listener parameter, any existing listener will be removed.

See also: getListener(); #setListener(EventListener)

◆ setListener() [3/3]

void org.omg.dds.core.Entity< LISTENER extends EventListener, QOS extends EntityQos<?>.setListener	(	LISTENER	listener,
		Class<? extends Status >...	statuses
	)

inherited

This operation installs a Listener on the Entity.

The listener will only be invoked on the changes of communication status indicated by the specified mask.

It is permitted to use null as the value of the listener. The null listener behaves as a Listener whose operations perform no action.

Only one listener can be attached to each Entity. If a listener was already set, the operation will replace it with the new one. Consequently if the value null is passed for the listener parameter, any existing listener will be removed.

See also: getListener(); #setListener(EventListener)

◆ setQos()

void org.omg.dds.core.Entity< LISTENER extends EventListener, QOS extends EntityQos<?>.setQos ( QOS qos )

inherited

This operation is used to set the QoS policies of the Entity.

This operation must be provided by each of the derived Entity classes (org.omg.dds.domain.DomainParticipant, org.omg.dds.topic.Topic, org.omg.dds.pub.Publisher, org.omg.dds.pub.DataWriter, org.omg.dds.sub.Subscriber, org.omg.dds.sub.DataReader) so that the policies that are meaningful to each Entity can be set.

The set of policies specified as the parameter are applied on top of the existing QoS, replacing the values of any policies previously set.

Certain policies are "immutable"; they can only be set at Entity creation time, or before the entity is made enabled. If setQos is invoked after the Entity is enabled and it attempts to change the value of an "immutable" policy, the operation will fail with org.omg.dds.core.ImmutablePolicyException.

Certain values of QoS policies can be incompatible with the settings of the other policies. The setQos operation will also fail if it specifies a set of values that once combined with the existing values would result in an inconsistent set of policies. In this case, it shall fail with org.omg.dds.core.InconsistentPolicyException.

If the application supplies a non-default value for a QoS policy that is not supported by the implementation of the service, the setQos operation will fail with UnsupportedOperationException.

The existing set of policies are only changed if the setQos operation succeeds. In all other cases, none of the policies is modified.

Exceptions

ImmutablePolicyException	if an immutable policy changes its value.
InconsistentPolicyException	if a combination of policies is inconsistent with one another.
UnsupportedOperationException	if an unsupported policy has a non-default value.

See also: getQos()

The documentation for this interface was generated from the following file:

java5/common/java/code/org/omg/dds/sub/Subscriber.java

Classes

Public Member Functions

Detailed Description

Member Function Documentation

◆ beginAccess()

◆ close()

◆ closeContainedEntities()

◆ copyFromTopicQos()

◆ createDataReader() [1/4]

◆ createDataReader() [2/4]

◆ createDataReader() [3/4]

◆ createDataReader() [4/4]

◆ createDataState()

◆ enable()

◆ endAccess()

◆ getDataReaders() [1/2]

◆ getDataReaders() [2/2]

◆ getDefaultDataReaderQos()

◆ getInstanceHandle()

◆ getListener()

◆ getParent()

◆ getQos()

◆ getStatusChanges()

◆ getStatusCondition()

◆ lookupDataReader() [1/2]

◆ lookupDataReader() [2/2]

◆ notifyDataReaders()

◆ retain()

◆ setDefaultDataReaderQos()

◆ setListener() [1/3]

◆ setListener() [2/3]

◆ setListener() [3/3]

◆ setQos()