com.toc.coredx.DDS
Class Subscriber

java.lang.Object
  com.toc.coredx.DDS.Entity
      com.toc.coredx.DDS.DomainEntity
          com.toc.coredx.DDS.Subscriber

public class Subscriber
extends DomainEntity

The Subscriber configures, creates, manages and destroys DataReaders.

Method Summary

ReturnCode_t	begin_access() This operation indicates that the application is about to access the data samples in any of the DataReader objects contained in the Subscriber s. The application is expected to use this operation only if PRESENTATION QosPolicy of the Subscriber has the access_scope set to GROUP.
ReturnCode_t	copy_from_topic_qos(DataReaderQos qos, TopicQos topic_qos) This operation copies the QoS settings in a_topic_qos to the corresponding settings in a_datareader_qos. The a_datareader_qos parameter is populated with a copy of the QoS policies from the a_topic_qos structure.
DataReader	create_datareader(TopicDescription topic, DataReaderQos qos, DataReaderListener listener, long mask) This operation creates a DataReader.
ReturnCode_t	delete_contained_entities() This operation deletes all the DataReaders created by means of the Subscriber.create_datareader() operation on the Subscriber s. This routine will recursively call the corresponding delete_contained_entities() operation on each of the contained DataReader objects.
ReturnCode_t	delete_datareader(DataReader datareader) This operation deletes a DataReader.
ReturnCode_t	enable() Enables the Subscriber.
ReturnCode_t	end_access() This operation closes a corresponding Subscriber.begin_access().
ReturnCode_t	get_datareaders(java.util.Vector readers, long sample_states, long view_states, long instance_states) This operation allows the application to access DataReader objects that contain samples with the specified sample_states, view_states, and instance_states.
ReturnCode_t	get_default_datareader_qos(DataReaderQos qos) Provides access to the default DataReaderQos settings held in the Subscriber s. The provided qos argument is populated with the current default qos settings.
SubscriberListener	get_listener() This operation returns the currently installed SubscriberListener.
DomainParticipant	get_participant() This operation returns the DomainParticipant this Subscriber belongs to.
ReturnCode_t	get_qos(SubscriberQos qos) Returns the current SubscriberQos settings held in the Subscriber s. The qos parameter is populated with a copy of the current Subscriber QoS properties.
DataReader	lookup_datareader(java.lang.String topic_name) This operation retrieves a previously-created DataReader contained in the Subscriber, attached to a Topic named topic_name. If multiple DataReaders are found, one of them will be returned.
ReturnCode_t	set_default_datareader_qos(DataReaderQos qos) Sets the default DataReaderQos held in the Subscriber.
ReturnCode_t	set_listener(SubscriberListener new_listener, long mask) Installs a SubscriberListener on Subscriber s. Only one listener may be attached to a Subscriber at a time.
ReturnCode_t	set_qos(SubscriberQos qos) Sets the SubscriberQos values.

Methods inherited from class com.toc.coredx.DDS.Entity

get_instance_handle, get_status_changes, get_statuscondition

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

enable

public ReturnCode_t enable()

Enables the Subscriber. A Subscriber is created either enabled or not based on the DomainParticipantQos setting entity_factory. When a Subscriber is not enabled, only the following sub-set of all Subscriber operations are legal:

• operations to get and set QoS policies,
• factory operations (create, delete),
• get_statuscondition(),
• get_status_changes(),
• lookup operations

Any other Subscriber operation may return the ReturnCode_t.RETCODE_NOT_ENABLED error. Subscriber_enable() may be called on an already enabled Subscriber [it will have no effect].

Overrides:

enable in class Entity

create_datareader

public DataReader create_datareader(TopicDescription topic,
                                    DataReaderQos qos,
                                    DataReaderListener listener,
                                    long mask)

This operation creates a DataReader. The created DataReader is contained within the Subscriber s. It is associated with the Topic, ContentFilteredTopic, or MultiTopic indicated by a_topic, and has the DataReaderQos indicated by qos. The qos argument may be passed DDS.DATAREADER_QOS_DEFAULT, which indicates that the Subscriber should use its currently configured default data reader QoS values. The DataReaderListener a_listener, is installed at creation time.

The created DataReader (if not NULL) must be destroyed by a call to Subscriber.delete_datareader().

This routine will fail if the provided QoS settings are internally inconsistent. In this case, the routine will return NULL.

delete_datareader

public ReturnCode_t delete_datareader(DataReader datareader)

This operation deletes a DataReader. If the provided DataReader a_datareader was not created by Subscriber s, the routine will fail and will return ReturnCode_t.RETCODE_PRECONDITION_NOT_MET. If the indicated DataReader has any outstanding ReadCondition or QueryCondition objects the routine will fail and will return ReturnCode_t.RETCODE_PRECONDITION_NOT_MET. If the indicated DataReader has any outstanding 'loans' (from read() or take() operations), the routine will fail and will return ReturnCode_.tRETCODE_PRECONDITION_NOT_MET.

delete_contained_entities

public ReturnCode_t delete_contained_entities()

This operation deletes all the DataReaders created by means of the Subscriber.create_datareader() operation on the Subscriber s. This routine will recursively call the corresponding delete_contained_entities() operation on each of the contained DataReader objects. If successful, this operation will recursively delete all objects contained with this Subscriber. After successful execution, the application may delete the Subscriber by calling DomainParticipant.delete_subscriber().

If any of the objects cannot be deleted, this routine will return ReturnCode_t.RETCODE_PRECONDITION_NOT_MET.

lookup_datareader

public DataReader lookup_datareader(java.lang.String topic_name)

This operation retrieves a previously-created DataReader contained in the Subscriber, attached to a Topic named topic_name. If multiple DataReaders are found, one of them will be returned. If no matching DataReader is found, this routine will return NULL.

This routine is useful to obtain access to a particular built-in DataReader.

get_datareaders

public ReturnCode_t get_datareaders(java.util.Vector readers,
                                    long sample_states,
                                    long view_states,
                                    long instance_states)

This operation allows the application to access DataReader objects that contain samples with the specified sample_states, view_states, and instance_states.

If the PRESENTATION QosPolicy of the Subscriber to which the DataReader belongs has the access_scope set to GROUP, this operation should be invoked only inside a begin_access/end_access block. Otherwise it will return the error PRECONDITION_NOT_MET.

The returned collection of DataReader objects may either 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).

1. If PRESENTATION access_scope is INSTANCE or TOPIC, the returned collection is a set.
2. If PRESENTATION access_scope is GROUP and ordered_access is set to TRUE, then the returned collection is a list.

This difference supports alternate access mechanisms.

This method is currently unsupported.

get_participant

public DomainParticipant get_participant()

This operation returns the DomainParticipant this Subscriber belongs to.

set_qos

public ReturnCode_t set_qos(SubscriberQos qos)

Sets the SubscriberQos values. These QoS values affect the behavior of the Subscriber. This routine may fail if the provided qos argument is not internally consistent. In this case, ReturnCode_t.RETCODE_INCONSISTENT_POLICY will be returned, and no changes will be made to the Subscriber QoS.

get_qos

public ReturnCode_t get_qos(SubscriberQos qos)

Returns the current SubscriberQos settings held in the Subscriber s. The qos parameter is populated with a copy of the current Subscriber QoS properties.

set_listener

public ReturnCode_t set_listener(SubscriberListener new_listener,
                                 long mask)

Installs a SubscriberListener on Subscriber s. Only one listener may be attached to a Subscriber at a time. A call to set_listener() will replace any current listener with a_listener.

a_listener can be NULL, which indicates a listener that does nothing.

get_listener

public SubscriberListener get_listener()

This operation returns the currently installed SubscriberListener.

begin_access

public ReturnCode_t begin_access()

This operation indicates that the application is about to access the data samples in any of the DataReader objects contained in the Subscriber s. The application is expected to use this operation only if PRESENTATION QosPolicy of the Subscriber has the access_scope set to GROUP. [Otherwise this routine has no effect.]

This method is currently unsupported.

end_access

public ReturnCode_t end_access()

This operation closes a corresponding Subscriber.begin_access().

This method is currently unsupported.

set_default_datareader_qos

public ReturnCode_t set_default_datareader_qos(DataReaderQos qos)

Sets the default DataReaderQos held in the Subscriber. This default qos will be used during subsequent calls to Subscriber.create_datareader() if the special DDS.DATAREADER_QOS_DEFAULT value is provided for qos. This routine may fail if the provided qos argument is not internally consistent. In this case, ReturnCode_t.RETCODE_INCONSISTENT_POLICY will be returned, and no changes will be made to the Subscriber.

get_default_datareader_qos

public ReturnCode_t get_default_datareader_qos(DataReaderQos qos)

Provides access to the default DataReaderQos settings held in the Subscriber s. The provided qos argument is populated with the current default qos settings.

copy_from_topic_qos

public ReturnCode_t copy_from_topic_qos(DataReaderQos qos,
                                        TopicQos topic_qos)

This operation copies the QoS settings in a_topic_qos to the corresponding settings in a_datareader_qos. The a_datareader_qos parameter is populated with a copy of the QoS policies from the a_topic_qos structure. QoS entries in the datareader qos structure will be overwritten with the values from the topic.