A Publisher is the object responsible for the actual dissemination of publications. More...

Inheritance diagram for org.omg.dds.pub.Publisher:

Collaboration diagram for org.omg.dds.pub.Publisher:

Public Member Functions
void	beginCoherentChanges ()
	This operation requests that the application will begin a 'coherent set' of modifications using org.omg.dds.pub.DataWriter objects attached to the Publisher. 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 Publisher. More...

DataWriterQos	copyFromTopicQos (DataWriterQos dwQos, TopicQos tQos)
	This operation copies the policies in the org.omg.dds.topic.Topic QoS to the corresponding policies in the org.omg.dds.pub.DataWriter QoS (replacing values in the DataWriter QoS, if present). More...

public< TYPE > DataWriter< TYPE >	createDataWriter (Topic< TYPE > topic)
	This operation creates a DataWriter. More...

public< TYPE > DataWriter< TYPE >	createDataWriter (Topic< TYPE > topic, DataWriterQos qos, DataWriterListener< TYPE > listener, Collection< Class<? extends Status >> statuses)
	This operation creates a DataWriter. More...

public< TYPE > DataWriter< TYPE >	createDataWriter (Topic< TYPE > topic, DataWriterQos qos, DataWriterListener< TYPE > listener, Class<? extends Status >... statuses)
	This operation creates a DataWriter. More...

public< TYPE > DataWriter< TYPE >	createDataWriter (Topic< TYPE > topic, DataWriterQos qos)
	This operation creates a DataWriter. More...

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

void	endCoherentChanges ()
	This operation terminates the 'coherent set' initiated by the matching call to beginCoherentChanges(). More...

DataWriterQos	getDefaultDataWriterQos ()
	This operation retrieves the default value of the DataWriter QoS, that is, the QoS policies which will be used for newly created org.omg.dds.pub.DataWriter entities in the case where the QoS policies are defaulted in the createDataWriter(Topic) 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< Publisher >	getStatusCondition ()

public< TYPE > DataWriter< TYPE >	lookupDataWriter (String topicName)
	This operation retrieves a previously created org.omg.dds.pub.DataWriter belonging to the Publisher that is attached to a org.omg.dds.topic.Topic with a matching name. More...

public< TYPE > DataWriter< TYPE >	lookupDataWriter (Topic< TYPE > topic)
	This operation retrieves a previously created org.omg.dds.pub.DataWriter belonging to the Publisher that is attached to the given org.omg.dds.topic.Topic. More...

void	resumePublications ()
	This operation indicates to the Service that the application has completed the multiple changes initiated by the previous suspendPublications(). 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	setDefaultDataWriterQos (DataWriterQos qos)
	This operation sets a default value of the DataWriter QoS policies, which will be used for newly created org.omg.dds.pub.DataWriter entities in the case where the QoS policies are defaulted in the createDataWriter(Topic) 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...

void	suspendPublications ()
	This operation indicates to the Service that the application is about to make multiple modifications using DataWriter objects belonging to the Publisher. More...

void	waitForAcknowledgments (Duration maxWait) throws TimeoutException
	This operation blocks the calling thread until either all data written by the reliable org.omg.dds.pub.DataWriter entities is acknowledged by all matched reliable org.omg.dds.sub.DataReader entities, or else the duration specified elapses, whichever happens first. More...

void	waitForAcknowledgments (long maxWait, TimeUnit unit) throws TimeoutException
	This operation blocks the calling thread until either all data written by the reliable org.omg.dds.pub.DataWriter entities is acknowledged by all matched reliable org.omg.dds.sub.DataReader entities, or else the duration specified elapses, whichever happens first. More...

Detailed Description

A Publisher is the object responsible for the actual dissemination of publications.

The Publisher acts on the behalf of one or several org.omg.dds.pub.DataWriter objects that belong to it. When it is informed of a change to the data associated with one of its DataWriter objects, it decides when it is appropriate to actually send the data-update message. In making this decision, it considers any extra information that goes with the data (time stamp, writer, etc.) as well as the QoS of the Publisher and the DataWriter.

All operations except for 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(), createDataWriter(Topic), and org.omg.dds.pub.Publisher#close() 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 Publisher using default Qos and no Listener.
Publisher myPub = participant.createPublisher();

Definition at line 71 of file Publisher.java.

Member Function Documentation

◆ beginCoherentChanges()

void org.omg.dds.pub.Publisher.beginCoherentChanges ( )

This operation requests that the application will begin a 'coherent set' of modifications using org.omg.dds.pub.DataWriter objects attached to the Publisher.

The 'coherent set' will be completed by a matching call to endCoherentChanges().

A 'coherent set' is a set of modifications that must be propagated in such a way that they are interpreted at the receivers' side as a consistent set of modifications; that is, the receiver will only be able to access the data after all the modifications in the set are available at the receiver end.

A connectivity change may occur in the middle of a set of coherent changes; for example, the set of partitions used by the Publisher or one of its Subscribers may change, a late-joining DataReader may appear on the network, or a communication failure may occur. In the event that such a change prevents an entity from receiving the entire set of coherent changes, that entity must behave as if it had received none of the set.

These calls can be nested. In that case, the coherent set terminates only with the last call to endCoherentChanges().

The support for 'coherent changes' enables a publishing application to change the value of several data instances that could belong to the same or different topics and have those changes be seen 'atomically' by the readers. This is useful in cases where the values are interrelated. For example, if there are two data instances representing the 'altitude' and 'velocity vector' of the same aircraft and both are changed, it may be useful to communicate those values in a way the reader can see both together; otherwise, it may e.g., erroneously interpret that the aircraft is on a collision course.

Exceptions

org.omg.dds.core.PreconditionNotMetException	the Publisher is not able to handle coherent changes because its PresentationQos has not set coherentAccess to TRUE.
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding Publisher has been closed.

See also: endCoherentChanges()

Implemented in org.opensplice.dds.pub.PublisherImpl.

◆ 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.pub.Publisher.closeContainedEntities ( )

This operation closes all the entities that were created by means of the "create" operations on the Publisher.

That is, it closes all contained org.omg.dds.pub.DataWriter objects.

Exceptions

org.omg.dds.core.PreconditionNotMetException if the any of the contained entities is in a state where it cannot be deleted.

Implemented in org.opensplice.dds.pub.PublisherImpl.

◆ copyFromTopicQos()

DataWriterQos org.omg.dds.pub.Publisher.copyFromTopicQos	(	DataWriterQos	dwQos,
		TopicQos	tQos
	)

This operation copies the policies in the org.omg.dds.topic.Topic QoS to the corresponding policies in the org.omg.dds.pub.DataWriter QoS (replacing values in the DataWriter QoS, if present).

This is a "convenience" operation most useful in combination with the operations getDefaultDataWriterQos() and org.omg.dds.topic.Topic#getQos(). The operation can be used to merge the DataWriter default QoS policies with the corresponding ones on the Topic. The resulting QoS can then be used to create a new DataWriter or set its QoS.

This operation does not check the resulting DatWriter 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 DataWriter.

Parameters

dwQos	The QoS whose policies are to be overridden. This object is not modified.
tQos	The QoS from which the policies are to be taken. This object is not modified.

Returns: A copy of dwQos with the applicable policies from tQos applied to it.

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 Publisher has been closed.

Implemented in org.opensplice.dds.pub.PublisherImpl.

◆ createDataWriter() [1/4]

public<TYPE> DataWriter<TYPE> org.omg.dds.pub.Publisher.createDataWriter ( Topic< TYPE > topic )

This operation creates a DataWriter.

The returned DataWriter will be attached and belongs to the Publisher.

Note that a common application pattern to construct the QoS for the DataWriter 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 DataWriter QoS by means of org.omg.dds.pub.Publisher#getDefaultDataWriterQos().
Combine those two QoS policies and selectively modify policies as desired – see copyFromTopicQos(DataWriterQos, TopicQos).
Use the resulting QoS policies to construct the DataWriter.

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

Parameters

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

Exceptions

org.omg.dds.core.OutOfResourcesException	if it is not possible for sufficient resources to be made available within the configured max blocking time.
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding Publisher has been closed.

See also: #createDataWriter(Topic, DataWriterQos, DataWriterListener, Collection)

◆ createDataWriter() [2/4]

public<TYPE> DataWriter<TYPE> org.omg.dds.pub.Publisher.createDataWriter	(	Topic< TYPE >	topic,
		DataWriterQos	qos,
		DataWriterListener< TYPE >	listener,
		Collection< Class<? extends Status >>	statuses
	)

This operation creates a DataWriter.

The returned DataWriter will be attached and belongs to the Publisher.

Note that a common application pattern to construct the QoS for the DataWriter 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 DataWriter QoS by means of org.omg.dds.pub.Publisher#getDefaultDataWriterQos().
Combine those two QoS policies and selectively modify policies as desired – see copyFromTopicQos(DataWriterQos, TopicQos).
Use the resulting QoS policies to construct the DataWriter.

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.pub.DataWriterListener 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 DataWriterListener:

OfferedDeadlineMissedStatus
OfferedIncompatibleQosStatus
LivelinessLostStatus
PublicationMatchedStatus

Status Propagation:

In case a communication status is not activated in the statuses of the DataWriterListener, the PublisherListener of the containing Publisher is invoked (if attached and activated for the status that occurred). This allows the application to set a default behaviour in the PublisherListener of the containing Publisher and a DataWriter specific behaviour when needed. In case the communication status is not activated in the statuses of the PublisherListener 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.Topic passed to this operation must have been created from the same org.omg.dds.domain.DomainParticipant that was used to create this Publisher. If the Topic was created from a different DomainParticipant, the operation will fail.

Restictions on QoS policies:

For a coherent writer there exists a constraint on the setting of the History QoS policy. When a writer is created with publisher that has a presentation QosPolicy with coherent_access enabled and where the access_scope is either TOPIC or GROUP then the History QoS policy of the coherent writer should be set to KEEP_ALL. Applying this constraint is necessary because in case of a keep-last writer the samples in the writers history could be pushed out by a new sample which causes that the transaction would not become complete.

Returns: A DataWriter object.

Parameters

topic	A reference to the topic for which the DataWriter is created.
qos	The DataWriterQos for the new DataWriter. In case these settings are not self consistent, no DataWriter is created.
listener	A reference to the DataWriterListener instance which will be attached to the new DataWriter.
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 Publisher has been closed.

See also: #createDataWriter(Topic)

◆ createDataWriter() [3/4]

public<TYPE> DataWriter<TYPE> org.omg.dds.pub.Publisher.createDataWriter	(	Topic< TYPE >	topic,
		DataWriterQos	qos,
		DataWriterListener< TYPE >	listener,
		Class<? extends Status >...	statuses
	)

This operation creates a DataWriter.

The returned DataWriter will be attached and belongs to the Publisher.

Note that a common application pattern to construct the QoS for the DataWriter 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 DataWriter QoS by means of org.omg.dds.pub.Publisher#getDefaultDataWriterQos().
Combine those two QoS policies and selectively modify policies as desired – see copyFromTopicQos(DataWriterQos, TopicQos).
Use the resulting QoS policies to construct the DataWriter.

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.pub.DataWriterListener 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 DataWriterListener:

OfferedDeadlineMissedStatus
OfferedIncompatibleQosStatus
LivelinessLostStatus
PublicationMatchedStatus

Status Propagation:

In case a communication status is not activated in the statuses of the DataWriterListener, the PublisherListener of the containing Publisher is invoked (if attached and activated for the status that occurred). This allows the application to set a default behaviour in the PublisherListener of the containing Publisher and a DataWriter specific behaviour when needed. In case the communication status is not activated in the statuses of the PublisherListener 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.Topic passed to this operation must have been created from the same org.omg.dds.domain.DomainParticipant that was used to create this Publisher. If the Topic was created from a different DomainParticipant, the operation will fail.

Returns: A DataWriter object.

Parameters

topic	A reference to the topic for which the DataWriter is created.
qos	The DataWriterQos for the new DataWriter. In case these settings are not self consistent, no DataWriter is created.
listener	A reference to the DataWriterListener instance which will be attached to the new DataWriter.
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 Publisher has been closed.

See also: #createDataWriter(Topic)

◆ createDataWriter() [4/4]

public<TYPE> DataWriter<TYPE> org.omg.dds.pub.Publisher.createDataWriter	(	Topic< TYPE >	topic,
		DataWriterQos	qos
	)

This operation creates a DataWriter.

The returned DataWriter will be attached and belongs to the Publisher.

Note that a common application pattern to construct the QoS for the DataWriter 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 DataWriter QoS by means of org.omg.dds.pub.Publisher#getDefaultDataWriterQos().
Combine those two QoS policies and selectively modify policies as desired – see copyFromTopicQos(DataWriterQos, TopicQos).
Use the resulting QoS policies to construct the DataWriter.

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

Parameters

topic	A reference to the topic for which the DataWriter is created.
qos	The DataWriterQos for the new DataWriter. In case these settings are not self consistent, no DataWriter is created.

Exceptions

org.omg.dds.core.OutOfResourcesException	if it is not possible for sufficient resources to be made available within the configured max blocking time.
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding Publisher has been closed.
org.omg.dds.core.InconsistentPolicyException	The parameter qos contains conflicting QosPolicy settings.
org.omg.dds.core.AlreadyClosedException	The corresponding Publisher has been closed.

See also: #createDataWriter(Topic, DataWriterQos, DataWriterListener, Collection)

◆ 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)

◆ endCoherentChanges()

void org.omg.dds.pub.Publisher.endCoherentChanges ( )

This operation terminates the 'coherent set' initiated by the matching call to beginCoherentChanges().

Exceptions

org.omg.dds.core.PreconditionNotMetException	if there is no matching call to beginCoherentChanges().
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding Publisher has been closed.

See also: beginCoherentChanges()

Implemented in org.opensplice.dds.pub.PublisherImpl.

◆ getDefaultDataWriterQos()

DataWriterQos org.omg.dds.pub.Publisher.getDefaultDataWriterQos ( )

This operation retrieves the default value of the DataWriter QoS, that is, the QoS policies which will be used for newly created org.omg.dds.pub.DataWriter entities in the case where the QoS policies are defaulted in the createDataWriter(Topic) operation.

The values retrieved will match the set of values specified on the last successful call to setDefaultDataWriterQos(DataWriterQos), or else, if the call was never made, the default values identified by the DDS specification.

Returns: A DataWriterQos

Exceptions

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

See also: setDefaultDataWriterQos(DataWriterQos)

Implemented in org.opensplice.dds.pub.PublisherImpl.

◆ 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.pub.Publisher.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.pub.PublisherImpl.

◆ 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<Publisher> org.omg.dds.pub.Publisher.getStatusCondition ( )

Implemented in org.opensplice.dds.pub.PublisherImpl.

◆ lookupDataWriter() [1/2]

public<TYPE> DataWriter<TYPE> org.omg.dds.pub.Publisher.lookupDataWriter ( String topicName )

This operation retrieves a previously created org.omg.dds.pub.DataWriter belonging to the Publisher that is attached to a org.omg.dds.topic.Topic with a matching name.

If no such DataWriter exists, the operation will return null.

If multiple DataWriters attached to the Publisher satisfy this condition, then the operation will return one of them. It is not specified which one.

Returns: the found DataWriter

Parameters

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

Exceptions

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

See also: #lookupDataWriter(Topic)

◆ lookupDataWriter() [2/2]

public<TYPE> DataWriter<TYPE> org.omg.dds.pub.Publisher.lookupDataWriter ( Topic< TYPE > topic )

This operation retrieves a previously created org.omg.dds.pub.DataWriter belonging to the Publisher that is attached to the given org.omg.dds.topic.Topic.

If no such DataWriter exists, the operation will return null.

If multiple DataWriters attached to the Publisher satisfy this condition, then the operation will return one of them. It is not specified which one.

Returns: the found DataWriter

Parameters

topic The Topic, which is attached to the DataWriter to look for.

Exceptions

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

See also: lookupDataWriter(String)

◆ resumePublications()

void org.omg.dds.pub.Publisher.resumePublications ( )

This operation indicates to the Service that the application has completed the multiple changes initiated by the previous suspendPublications().

This is a hint to the Service that can be used by a Service implementation to e.g., batch all the modifications made since the suspendPublications().

Exceptions

org.omg.dds.core.PreconditionNotMetException	if the call to this method does not match a previous call to suspendPublications().
org.omg.dds.core.OutOfResourcesException	if it is not possible for sufficient resources to be made available within the configured max blocking time.
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding Publisher has been closed.

See also: suspendPublications()

Implemented in org.opensplice.dds.pub.PublisherImpl.

◆ 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.

◆ setDefaultDataWriterQos()

void org.omg.dds.pub.Publisher.setDefaultDataWriterQos ( DataWriterQos qos )

This operation sets a default value of the DataWriter QoS policies, which will be used for newly created org.omg.dds.pub.DataWriter entities in the case where the QoS policies are defaulted in the createDataWriter(Topic) operation.

Parameters

qos	The new default DataWriterQos

Exceptions

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

See also: getDefaultDataWriterQos()

Implemented in org.opensplice.dds.pub.PublisherImpl.

◆ 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()

◆ suspendPublications()

void org.omg.dds.pub.Publisher.suspendPublications ( )

This operation indicates to the Service that the application is about to make multiple modifications using DataWriter objects belonging to the Publisher.

It is a hint to the Service so it can optimize its performance by e.g., holding the dissemination of the modifications and then batching them.

It is not required that the Service use this hint in any way.

The use of this operation must be matched by a corresponding call to resumePublications() indicating that the set of modifications has completed. If the Publisher is deleted before resumePublications() is called, any suspended updates yet to be published will be discarded.

Exceptions

org.omg.dds.core.OutOfResourcesException	if it is not possible for sufficient resources to be made available within the configured max blocking time.
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding Publisher has been closed.

See also: resumePublications()

Implemented in org.opensplice.dds.pub.PublisherImpl.

◆ waitForAcknowledgments() [1/2]

void org.omg.dds.pub.Publisher.waitForAcknowledgments ( Duration maxWait ) throws TimeoutException

This operation blocks the calling thread until either all data written by the reliable org.omg.dds.pub.DataWriter entities is acknowledged by all matched reliable org.omg.dds.sub.DataReader entities, or else the duration specified elapses, whichever happens first.

Be aware that in case the operation succeeds, the data has only been acknowledged by the local infrastructure: it does not mean all remote subscriptions have already received the data. However, delivering the data to remote nodes is then the sole responsibility of the networking service: even when the publishing application would terminate, all data that has not yet been received may be considered 'on-route' and will therefore eventually arrive (unless the networking service itself will crash). In contrast, if a DataWriter would still have data in its local history buffer when it terminates, this data is considered 'lost'.

Parameters

maxWait The maximum duration to block for the waitForAcknowledgments, after which the application thread is unblocked. The operation Duration.infiniteDuration(env) can be used when the maximum waiting time does not need to be bounded.

Exceptions

TimeoutException	if maxWait elapsed before all the data was acknowledged.
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 Publisher has been closed.

Implemented in org.opensplice.dds.pub.PublisherImpl.

◆ waitForAcknowledgments() [2/2]

void org.omg.dds.pub.Publisher.waitForAcknowledgments	(	long	maxWait,
		TimeUnit	unit
	)		throws TimeoutException

This operation blocks the calling thread until either all data written by the reliable org.omg.dds.pub.DataWriter entities is acknowledged by all matched reliable org.omg.dds.sub.DataReader entities, or else the duration specified elapses, whichever happens first.

Be aware that in case the operation succeeds, the data has only been acknowledged by the local infrastructure: it does not mean all remote subscriptions have already received the data. However, delivering the data to remote nodes is then the sole responsibility of the networking service: even when the publishing application would terminate, all data that has not yet been received may be considered 'on-route' and will therefore eventually arrive (unless the networking service itself will crash). In contrast, if a DataWriter would still have data in its local history buffer when it terminates, this data is considered 'lost'.

Parameters

maxWait	The maximum duration to block for the waitForAcknowledgments, after which the application thread is unblocked defined in a long.
unit	The TimeUnit which the maxWait describes (i.e. TimeUnit.SECONDS or TimeUnit.MILLISECONDS)

Exceptions

TimeoutException	if maxWait elapsed before all the data was acknowledged.
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 Publisher has been closed.

Implemented in org.opensplice.dds.pub.PublisherImpl.

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

java5/common/java/code/org/omg/dds/pub/Publisher.java

Public Member Functions

Detailed Description

Member Function Documentation

◆ beginCoherentChanges()

◆ close()

◆ closeContainedEntities()

◆ copyFromTopicQos()

◆ createDataWriter() [1/4]

◆ createDataWriter() [2/4]

◆ createDataWriter() [3/4]

◆ createDataWriter() [4/4]

◆ enable()

◆ endCoherentChanges()

◆ getDefaultDataWriterQos()

◆ getInstanceHandle()

◆ getListener()

◆ getParent()

◆ getQos()

◆ getStatusChanges()

◆ getStatusCondition()

◆ lookupDataWriter() [1/2]

◆ lookupDataWriter() [2/2]

◆ resumePublications()

◆ retain()

◆ setDefaultDataWriterQos()

◆ setListener() [1/3]

◆ setListener() [2/3]

◆ setListener() [3/3]

◆ setQos()

◆ suspendPublications()

◆ waitForAcknowledgments() [1/2]

◆ waitForAcknowledgments() [2/2]