org.omg.dds.core

Interface Entity<LISTENER extends EventListener,QOS extends EntityQos<?>>

Type Parameters:

LISTENER - The listener interface appropriate for this entity.

QOS - The QoS interface appropriate for this entity.

All Superinterfaces:

AutoCloseable, Closeable, DDSObject

All Known Subinterfaces:

DataReader<TYPE>, DataWriter<TYPE>, DomainEntity<LISTENER,QOS>, DomainParticipant, Publisher, Subscriber, Topic<TYPE>

public interface Entity<LISTENER extends EventListener,QOS extends EntityQos<?>>
extends Closeable, DDSObject

This class is the abstract base class for all the DCPS objects that support QoS policies, a listener and a status condition.

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Halt communication and dispose the resources held by this Entity.
void	enable() This operation enables the Entity.
InstanceHandle	getInstanceHandle()
LISTENER	getListener() This operation allows access to the existing Listener attached to the Entity.
QOS	getQos() This operation allows access to the existing set of QoS policies for the Entity.
Set<Class<? extends Status>>	getStatusChanges() This operation retrieves the list of communication statuses in the Entity that are 'triggered.'
StatusCondition<?>	getStatusCondition() This operation allows access to the StatusCondition associated with the Entity.
void	retain() Indicates that references to this object may go out of scope but that the application expects to look it up again later.
void	setListener(LISTENER listener) This operation installs a Listener on the Entity.
void	setListener(LISTENER listener, Collection<Class<? extends Status>> statuses) This operation installs a Listener on the Entity.
void	setQos(QOS qos) This operation is used to set the QoS policies of the Entity.
void	setQos(String qosLibraryName, String qosProfileName) Set the QoS to that specified in the given QoS profile in the given QoS library.

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

getEnvironment

Method Detail

getListener

LISTENER getListener()

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

See Also:

setListener(EventListener), setListener(EventListener, Collection)

setListener

void setListener(LISTENER listener)

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.

See Also:

getListener(), setListener(EventListener, Collection)

setListener

void setListener(LISTENER listener,
               Collection<Class<? extends Status>> statuses)

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)

getQos

QOS getQos()

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 (DomainParticipant, Topic, Publisher, DataWriter, Subscriber, DataReader) so that the policies meaningful to the particular Entity are retrieved.

See Also:

setQos(EntityQos)

setQos

void setQos(QOS qos)

This operation is used to set the QoS policies of the Entity. This operation must be provided by each of the derived Entity classes (DomainParticipant, Topic, Publisher, DataWriter, Subscriber, 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 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 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.

Throws:

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(), setQos(String, String)

setQos

void setQos(String qosLibraryName,
          String qosProfileName)

Set the QoS to that specified in the given QoS profile in the given QoS library.

Parameters:

qosLibraryName -

qosProfileName -

See Also:

getQos(), setQos(EntityQos)

enable

void enable()

This operation enables the Entity. Entity objects can be created either enabled or disabled. This is controlled by the value of the EntityFactory on the corresponding factory for the Entity. The default setting of 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 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 EntityFactory. Calling enable on an Entity whose factory is not enabled will fail with PreconditionNotMetException. If 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. Conditions associated with an entity that is not enabled are "inactive," that is, have a triggerValue == false.

getStatusCondition

StatusCondition<?> getStatusCondition()

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.

getStatusChanges

Set<Class<? extends Status>> getStatusChanges()

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.

getInstanceHandle

InstanceHandle getInstanceHandle()

Returns:

the InstanceHandle that represents the Entity.

close

void close()

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 Topic cannot be closed if it is still in use by any ContentFilteredTopics or MultiTopics.
• A Topic cannot be closed if any DataWriters or DataReader is still using it.
• A DataReader cannot be closed if it has any outstanding loans as a result of a call to DataReader.read(), DataReader.take(), or one of the variants thereof.

The deletion of a DataWriter will automatically unregister all instances. Depending on the settings of the WriterDataLifecycle, the deletion of the DataWriter may also dispose all instances.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

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

See Also:

TopicDescription.close()

retain

void retain()

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.