org.omg.dds.pub

Interface Publisher

All Superinterfaces:

AutoCloseable, Closeable, DDSObject, DomainEntity<PublisherListener,PublisherQos>, Entity<PublisherListener,PublisherQos>

public interface Publisher
extends DomainEntity<PublisherListener,PublisherQos>

A Publisher is the object responsible for the actual dissemination of publications. The Publisher acts on the behalf of one or several 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 Entity.setQos(org.omg.dds.core.EntityQos), Entity.getQos(), Entity.setListener(java.util.EventListener), Entity.getListener(), Entity.enable(), Entity.getStatusCondition(), createDataWriter(Topic), and Entity.close() may fail with the exception NotEnabledException.

Method Summary

Methods

Modifier and Type	Method and Description
void	beginCoherentChanges() This operation requests that the application will begin a 'coherent set' of modifications using DataWriter objects attached to the Publisher.
void	closeContainedEntities() This operation closes all the entities that were created by means of the "create" operations on the Publisher.
DataWriterQos	copyFromTopicQos(DataWriterQos dwQos, TopicQos tQos) This operation copies the policies in the Topic QoS to the corresponding policies in the DataWriter QoS (replacing values in the DataWriter QoS, if present).
<TYPE> DataWriter<TYPE>	createDataWriter(Topic<TYPE> topic) This operation creates a DataWriter.
<TYPE> DataWriter<TYPE>	createDataWriter(Topic<TYPE> topic, DataWriterQos qos) This operation creates a DataWriter.
<TYPE> DataWriter<TYPE>	createDataWriter(Topic<TYPE> topic, DataWriterQos qos, DataWriterListener<TYPE> listener, Collection<Class<? extends Status>> statuses) This operation creates a DataWriter.
void	endCoherentChanges() This operation terminates the 'coherent set' initiated by the matching call to beginCoherentChanges().
DataWriterQos	getDefaultDataWriterQos() This operation retrieves the default value of the DataWriter QoS, that is, the QoS policies which will be used for newly created DataWriter entities in the case where the QoS policies are defaulted in the createDataWriter(Topic) operation.
DomainParticipant	getParent()
StatusCondition<Publisher>	getStatusCondition() This operation allows access to the StatusCondition associated with the Entity.
<TYPE> DataWriter<TYPE>	lookupDataWriter(String topicName) This operation retrieves a previously created DataWriter belonging to the Publisher that is attached to a Topic with a matching name.
<TYPE> DataWriter<TYPE>	lookupDataWriter(Topic<TYPE> topic) This operation retrieves a previously created DataWriter belonging to the Publisher that is attached to the given Topic.
void	resumePublications() This operation indicates to the Service that the application has completed the multiple changes initiated by the previous suspendPublications().
void	setDefaultDataWriterQos(DataWriterQos qos) This operation sets a default value of the DataWriter QoS policies, which will be used for newly created DataWriter entities in the case where the QoS policies are defaulted in the createDataWriter(Topic) operation.
void	suspendPublications() This operation indicates to the Service that the application is about to make multiple modifications using DataWriter objects belonging to the Publisher.
void	waitForAcknowledgments(Duration maxWait) This operation blocks the calling thread until either all data written by the reliable DataWriter entities is acknowledged by all matched reliable DataReader entities, or else the duration specified elapses, whichever happens first.
void	waitForAcknowledgments(long maxWait, TimeUnit unit) This operation blocks the calling thread until either all data written by the reliable DataWriter entities is acknowledged by all matched reliable DataReader entities, or else the duration specified elapses, whichever happens first.

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

close, enable, getInstanceHandle, getListener, getQos, getStatusChanges, retain, setListener, setListener, setQos, setQos

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

getEnvironment

Method Detail

createDataWriter

<TYPE> DataWriter<TYPE> 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 Topic by means of Entity.getQos().
• Retrieve the default DataWriter QoS by means of 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 Topic passed to this operation must have been created from the same DomainParticipant that was used to create this Publisher. If the Topic was created from a different DomainParticipant, the operation will fail.

See Also:

createDataWriter(Topic, DataWriterQos, DataWriterListener, Collection)

createDataWriter

<TYPE> DataWriter<TYPE> 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 Topic by means of Entity.getQos().
• Retrieve the default DataWriter QoS by means of 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 Topic passed to this operation must have been created from the same DomainParticipant that was used to create this Publisher. If the Topic was created from a different DomainParticipant, the operation will fail.

Parameters:

statuses - Of which status changes the listener should be notified. A null collection signifies all status changes.

See Also:

createDataWriter(Topic)

createDataWriter

<TYPE> DataWriter<TYPE> createDataWriter(Topic<TYPE> topic,
                                       DataWriterQos qos)

This operation creates a DataWriter. The returned DataWriter will be attached and belong to the Publisher.

Parameters:

topic - The Topic created from the same DomainParticipant that was used to create this Publisher.

qos - An instance of (@link org.omg.dds.sub.DataWriterQos} or null.

Returns:

DataWriter

See Also:

createDataWriter(Topic)

lookupDataWriter

<TYPE> DataWriter<TYPE> lookupDataWriter(String topicName)

This operation retrieves a previously created DataWriter belonging to the Publisher that is attached to a 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.

See Also:

lookupDataWriter(Topic)

lookupDataWriter

<TYPE> DataWriter<TYPE> lookupDataWriter(Topic<TYPE> topic)

This operation retrieves a previously created DataWriter belonging to the Publisher that is attached to the given 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.

See Also:

lookupDataWriter(String)

closeContainedEntities

void 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 DataWriter objects.

Throws:

PreconditionNotMetException - if the any of the contained entities is in a state where it cannot be deleted.

suspendPublications

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

See Also:

resumePublications()

resumePublications

void 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().

Throws:

PreconditionNotMetException - if the call to this method does not match a previous call to suspendPublications().

See Also:

suspendPublications()

beginCoherentChanges

void beginCoherentChanges()

This operation requests that the application will begin a 'coherent set' of modifications using 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.

See Also:

endCoherentChanges()

endCoherentChanges

void endCoherentChanges()

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

Throws:

PreconditionNotMetException - if there is no matching call to beginCoherentChanges().

See Also:

beginCoherentChanges()

waitForAcknowledgments

void waitForAcknowledgments(Duration maxWait)
                            throws TimeoutException

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

Throws:

TimeoutException - if maxWait elapsed before all the data was acknowledged.

waitForAcknowledgments

void waitForAcknowledgments(long maxWait,
                          TimeUnit unit)
                            throws TimeoutException

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

Throws:

TimeoutException - if maxWait elapsed before all the data was acknowledged.

getDefaultDataWriterQos

DataWriterQos getDefaultDataWriterQos()

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

See Also:

setDefaultDataWriterQos(DataWriterQos)

setDefaultDataWriterQos

void setDefaultDataWriterQos(DataWriterQos qos)

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

Throws:

InconsistentPolicyException - if the resulting policies are not self consistent; if they are not, the operation will have no effect.

See Also:

getDefaultDataWriterQos()

copyFromTopicQos

DataWriterQos copyFromTopicQos(DataWriterQos dwQos,
                             TopicQos tQos)

This operation copies the policies in the Topic QoS to the corresponding policies in the DataWriter QoS (replacing values in the DataWriter QoS, if present). This is a "convenience" operation most useful in combination with the operations getDefaultDataWriterQos() and Entity.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.

getStatusCondition

StatusCondition<Publisher> getStatusCondition()

Description copied from interface: Entity

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.

Specified by:

getStatusCondition in interface Entity<PublisherListener,PublisherQos>

getParent

DomainParticipant getParent()

Specified by:

getParent in interface DomainEntity<PublisherListener,PublisherQos>

Returns:

the factory object that created this entity.