RTI Connext Java API  Version 5.3.1
 All Classes Namespaces Functions Variables Groups Pages
Entity Interface Reference

<<interface>> Abstract base class for all the DDS objects that support QoS policies, a listener, and a status condition. More...

Inheritance diagram for Entity:
DomainParticipant DomainEntity DataWriter Publisher DataReader Subscriber Topic DynamicDataWriter BytesDataWriter KeyedBytesDataWriter KeyedStringDataWriter StringDataWriter FooDataWriter DynamicDataReader BytesDataReader KeyedBytesDataReader KeyedStringDataReader StringDataReader FooDataReader

Public Member Functions

void enable ()
 Enables the com.rti.dds.infrastructure.Entity.
 
StatusCondition get_statuscondition ()
 Allows access to the com.rti.dds.infrastructure.StatusCondition associated with the com.rti.dds.infrastructure.Entity.
 
int get_status_changes ()
 Retrieves the list of communication statuses in the com.rti.dds.infrastructure.Entity that are triggered.
 
InstanceHandle_t get_instance_handle ()
 Allows access to the com.rti.dds.infrastructure.InstanceHandle_t associated with the com.rti.dds.infrastructure.Entity.
 

Detailed Description

<<interface>> Abstract base class for all the DDS objects that support QoS policies, a listener, and a status condition.

All operations except for set_qos(), get_qos(), set_listener(), get_listener() and enable(), may return the value com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

QoS:
QoS Policies
Status:
Status Kinds
Listener:
com.rti.dds.infrastructure.Listener

Abstract operations

Each derived entity provides the following operations specific to its role in RTI Connext.

set_qos (abstract)

This operation sets the QoS policies of the com.rti.dds.infrastructure.Entity. Each of the derived entity classes provides this operation: com.rti.dds.infrastructure.Entity classes (com.rti.dds.domain.DomainParticipant, com.rti.dds.topic.Topic, com.rti.dds.publication.Publisher, com.rti.dds.publication.DataWriter, com.rti.dds.subscription.Subscriber, and com.rti.dds.subscription.DataReader) so that the policies that are meaningful to each com.rti.dds.infrastructure.Entity can be set.

Precondition
Certain policies are immutable (see QoS Policies): they can only be set at com.rti.dds.infrastructure.Entity creation time or before the entity is enabled. If set_qos() is invoked after the com.rti.dds.infrastructure.Entity is enabled and it attempts to change the value of an immutable policy, the operation will fail and return com.rti.dds.infrastructure.RETCODE_IMMUTABLE_POLICY.
Certain values of QoS policies can be incompatible with the settings of the other policies. The set_qos() 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, the operation will fail and return com.rti.dds.infrastructure.RETCODE_INCONSISTENT_POLICY.
If the application supplies a non-default value for a QoS policy that is not supported by the implementation of the service, the set_qos operation will fail and return com.rti.dds.infrastructure.RETCODE_UNSUPPORTED.
Postcondition
The existing set of policies is only changed if the set_qos() operation succeeds. This is indicated by a return code of com.rti.dds.infrastructure.RETCODE_OK. In all other cases, none of the policies are modified.

Each derived com.rti.dds.infrastructure.Entity class (com.rti.dds.domain.DomainParticipant, com.rti.dds.topic.Topic, com.rti.dds.publication.Publisher, com.rti.dds.publication.DataWriter, com.rti.dds.subscription.Subscriber, com.rti.dds.subscription.DataReader) has a corresponding special value of the QoS (com.rti.dds.domain.DomainParticipantFactory.PARTICIPANT_QOS_DEFAULT, com.rti.dds.domain.DomainParticipant.PUBLISHER_QOS_DEFAULT, com.rti.dds.domain.DomainParticipant.SUBSCRIBER_QOS_DEFAULT, com.rti.dds.domain.DomainParticipant.TOPIC_QOS_DEFAULT, com.rti.dds.publication.Publisher.DATAWRITER_QOS_DEFAULT, com.rti.dds.subscription.Subscriber.DATAREADER_QOS_DEFAULT). This special value may be used as a parameter to the set_qos operation to indicate that the QoS of the com.rti.dds.infrastructure.Entity should be changed to match the current default QoS set in the com.rti.dds.infrastructure.Entity's factory. The operation set_qos cannot modify the immutable QoS, so a successful return of the operation indicates that the mutable QoS for the Entity has been modified to match the current default for the com.rti.dds.infrastructure.Entity's factory.

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

Possible exceptions thrown in addition to Standard Return Codes : com.rti.dds.infrastructure.RETCODE_IMMUTABLE_POLICY, com.rti.dds.infrastructure.RETCODE_INCONSISTENT_POLICY.

get_qos (abstract)

This operation allows access to the existing set of QoS policies for the com.rti.dds.infrastructure.Entity. This operation must be provided by each of the derived com.rti.dds.infrastructure.Entity classes (com.rti.dds.domain.DomainParticipant, com.rti.dds.topic.Topic, com.rti.dds.publication.Publisher, com.rti.dds.publication.DataWriter, com.rti.dds.subscription.Subscriber, and com.rti.dds.subscription.DataReader), so that the policies that are meaningful to each com.rti.dds.infrastructure.Entity can be retrieved.

Possible error codes are Standard Return Codes.

set_listener (abstract)

This operation installs a com.rti.dds.infrastructure.Listener on the com.rti.dds.infrastructure.Entity. The listener will only be invoked on the changes of communication status indicated by the specified mask.

This operation must be provided by each of the derived com.rti.dds.infrastructure.Entity classes (com.rti.dds.domain.DomainParticipant, com.rti.dds.topic.Topic, com.rti.dds.publication.Publisher, com.rti.dds.publication.DataWriter, com.rti.dds.subscription.Subscriber, and com.rti.dds.subscription.DataReader), so that the listener is of the concrete type suitable to the particular com.rti.dds.infrastructure.Entity.

There are two components involved when setting up listeners: the listener itself and the mask. Both of these can be NULL.

Listeners for some Entities derive from the Connext DDS Listeners for related Entities. This means that the derived Listener has all of the methods of its parent class. You can install Listeners at all levels of the object hierarchy. At the top is the DomainParticipantListener; only one can be installed in a DomainParticipant. Then every Subscriber and Publisher can have their own Listener. Finally, each Topic, DataReader and DataWriter can have their own listeners. All are optional.

Suppose, however, that an Entity does not install a Listener, or installs a Listener that does not have particular communication status selected in the bitmask. In this case, if/when that particular status changes for that Entity, the corresponding Listener for that Entity’s parent is called. Status changes are “propagated” from child Entity to parent Entity until a Listener is found that is registered for that status. Connext DDS will give up and drop the status-change event only if no Listeners have been installed in the object hierarchy to be called back for the specific status.

The following table describes the effect of different combinations of Listeners and Status Bit Masks considering the hierarchical processing.

Effect of Different Combinations of Listeners and Status Bit Masks
No Bits Set in Mask Some/All Bits Set in Mask
Listener is Specified Connext DDS finds the next most relevant listener for the changed status For the statuses that are enabled in the mask, the most relevant listener will be called. The 'statusChangedFlag' for the relevant status is reset
Listener is NULL Connext DDS behaves as if the listener is not installed and finds the next most relevant listener for that status Connext DDS behaves as if the listener is installed, but the callback is doing nothing. This is called a ‘nil’ listener
Postcondition
Only one listener can be attached to each com.rti.dds.infrastructure.Entity. If a listener was already set, the operation set_listener() will replace it with the new one. Consequently, if the value null is passed for the listener parameter to the set_listener operation, any existing listener will be removed.

get_listener (abstract)

This operation allows access to the existing com.rti.dds.infrastructure.Listener attached to the com.rti.dds.infrastructure.Entity.

This operation must be provided by each of the derived com.rti.dds.infrastructure.Entity classes (com.rti.dds.domain.DomainParticipant, com.rti.dds.topic.Topic, com.rti.dds.publication.Publisher, com.rti.dds.publication.DataWriter, com.rti.dds.subscription.Subscriber, and com.rti.dds.subscription.DataReader) so that the listener is of the concrete type suitable to the particular com.rti.dds.infrastructure.Entity.

If no listener is installed on the com.rti.dds.infrastructure.Entity, this operation will return null.

Member Function Documentation

void enable ( )

Enables the com.rti.dds.infrastructure.Entity.

This operation enables the Entity. Entity objects can be created either enabled or disabled. This is controlled by the value of the ENTITY_FACTORY QoS policy on the corresponding factory for the com.rti.dds.infrastructure.Entity.

By default, ENTITY_FACTORY is set so that it is not necessary to explicitly call com.rti.dds.infrastructure.Entity.enable on newly created entities.

The com.rti.dds.infrastructure.Entity.enable operation is idempotent. Calling enable on an already enabled Entity returns OK and has no effect.

If a com.rti.dds.infrastructure.Entity has not yet been enabled, the following kinds of operations may be invoked on it:

Other operations may explicitly state that they may be called on disabled entities; those that do not will return the error com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

It is legal to delete an com.rti.dds.infrastructure.Entity that has not been enabled by calling the proper operation on its factory.

Entities created from a factory Entity that is disabled are created disabled, regardless of the setting of the com.rti.dds.infrastructure.EntityFactoryQosPolicy.

Calling enable on an Entity whose factory Entity is not enabled will fail and return com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET.

If com.rti.dds.infrastructure.EntityFactoryQosPolicy.autoenable_created_entities is TRUE, the enable operation on a factory will automatically enable all entities created from that factory (for example, enabling a com.rti.dds.publication.Publisher will enable all its contained com.rti.dds.publication.DataWriter objects)

Listeners associated with an entity are not called until the entity is enabled.

Conditions associated with a disabled entity are "inactive," that is, they have a trigger_value == FALSE.

Exceptions
Oneof the Standard Return Codes, Standard Return Codes or com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET.
StatusCondition get_statuscondition ( )

Allows access to the com.rti.dds.infrastructure.StatusCondition associated with the com.rti.dds.infrastructure.Entity.

The returned condition can then be added to a com.rti.dds.infrastructure.WaitSet so that the application can wait for specific status changes that affect the com.rti.dds.infrastructure.Entity.

Returns
the status condition associated with this entity.
int get_status_changes ( )

Retrieves the list of communication statuses in the com.rti.dds.infrastructure.Entity that are triggered.

That is, the list of statuses whose value has changed since the last time the application read the status using the get_*_status() method.

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 by the get_status_changes operation will be empty.

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

Returns
list of communication statuses in the com.rti.dds.infrastructure.Entity that are triggered.
See Also
Status Kinds
InstanceHandle_t get_instance_handle ( )

Allows access to the com.rti.dds.infrastructure.InstanceHandle_t associated with the com.rti.dds.infrastructure.Entity.

This operation returns the com.rti.dds.infrastructure.InstanceHandle_t that represents the com.rti.dds.infrastructure.Entity.

Returns
the instance handle associated with this entity.

RTI Connext Java API Version 5.3.1 Copyright © Mon Feb 19 2018 Real-Time Innovations, Inc