OpenSplice-specific extension of org.omg.dds.pub.DataWriter with support for writing atomic writing of a sample and disposing the corresponding instance. More...

Inheritance diagram for org.opensplice.dds.pub.DataWriter< TYPE >:

Collaboration diagram for org.opensplice.dds.pub.DataWriter< TYPE >:

Public Member Functions
void	assertLiveliness ()
	This operation manually asserts the liveliness of the DataWriter. More...

public< OTHER > DataWriter< OTHER >	cast ()
	Cast this data writer to the given type, or throw an exception if the cast fails. More...

abstract void	close ()
	Halt communication and dispose the resources held by this Entity. More...

void	dispose (InstanceHandle instanceHandle) throws TimeoutException
	This operation requests the middleware to delete the data (the actual deletion is postponed until there is no more use for that data in the whole system). More...

void	dispose (InstanceHandle instanceHandle, TYPE instanceData) throws TimeoutException
	This operation requests the middleware to delete the data (the actual deletion is postponed until there is no more use for that data in the whole system). More...

void	dispose (InstanceHandle instanceHandle, TYPE instanceData, Time sourceTimestamp) throws TimeoutException
	This operation performs the same functions as dispose(InstanceHandle, Object) except that the application provides the value for the source time stamp that is made available to org.omg.dds.sub.DataReader objects by means of org.omg.dds.sub.Sample#getSourceTimestamp(). More...

void	dispose (InstanceHandle instanceHandle, TYPE instanceData, long sourceTimestamp, TimeUnit unit) throws TimeoutException
	This operation performs the same functions as dispose(InstanceHandle, Object) except that the application provides the value for the source time stamp that is made available to org.omg.dds.sub.DataReader objects by means of org.omg.dds.sub.Sample#getSourceTimestamp(). More...

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

InstanceHandle	getInstanceHandle ()

TYPE	getKeyValue (TYPE keyHolder, InstanceHandle handle)
	This operation can be used to retrieve the instance key that corresponds to an instance handle. More...

TYPE	getKeyValue (InstanceHandle handle)
	This operation can be used to retrieve the instance key that corresponds to an instance handle. More...

LISTENER	getListener ()
	This operation allows access to the existing Listener attached to the Entity. More...

LivelinessLostStatus	getLivelinessLostStatus ()
	This operation obtains the LivelinessLostStatus object of the DataWriter. More...

SubscriptionBuiltinTopicData	getMatchedSubscriptionData (InstanceHandle subscriptionHandle)
	This operation retrieves information on a subscription that is currently "associated" with the DataWriter; that is, a subscription with a matching org.omg.dds.topic.Topic and compatible QoS that the application has not indicated should be "ignored" by means of org.omg.dds.domain.DomainParticipant#ignoreSubscription(InstanceHandle). More...

Set< InstanceHandle >	getMatchedSubscriptions ()
	This operation retrieves the list of subscriptions currently "associated" with the DataWriter; that is, subscriptions that have a matching org.omg.dds.topic.Topic and compatible QoS that the application has not indicated should be "ignored" by means of org.omg.dds.domain.DomainParticipant#ignoreSubscription(InstanceHandle). More...

OfferedDeadlineMissedStatus	getOfferedDeadlineMissedStatus ()
	This operation obtains the OfferedDeadlineMissedStatus object of the DataWriter. More...

OfferedIncompatibleQosStatus	getOfferedIncompatibleQosStatus ()
	This operation obtains the OfferedIncompatibleQosStatus object of the DataWriter. More...

Publisher	getParent ()

PublicationMatchedStatus	getPublicationMatchedStatus ()
	This operation obtains the PublicationMatchedStatus object of the DataWriter. More...

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< DataWriter< TYPE > >	getStatusCondition ()

Topic< TYPE >	getTopic ()

InstanceHandle	lookupInstance (TYPE keyHolder)
	This operation takes as a parameter an instance and returns a handle that can be used in subsequent operations that accept an instance handle as an argument. More...

InstanceHandle	registerInstance (TYPE instanceData) throws TimeoutException
	This operation informs the Service that the application will be modifying a particular instance. More...

InstanceHandle	registerInstance (TYPE instanceData, Time sourceTimestamp) throws TimeoutException
	This operation performs the same function as registerInstance(Object) and can be used instead in the cases where the application desires to specify the value for the source time stamp. More...

InstanceHandle	registerInstance (TYPE instanceData, long sourceTimestamp, TimeUnit unit) throws TimeoutException
	This operation performs the same function as registerInstance(Object) and can be used instead in the cases where the application desires to specify the value for the source time stamp. 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	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	unregisterInstance (InstanceHandle handle) throws TimeoutException
	This operation reverses the action of registerInstance(Object). More...

void	unregisterInstance (InstanceHandle handle, TYPE instanceData) throws TimeoutException
	This operation reverses the action of registerInstance(Object). More...

void	unregisterInstance (InstanceHandle handle, TYPE instanceData, Time sourceTimestamp) throws TimeoutException
	This operation performs the same function as unregisterInstance(InstanceHandle, Object) and can be used instead in the cases where the application desires to specify the value for the source time stamp. More...

void	unregisterInstance (InstanceHandle handle, TYPE instanceData, long sourceTimestamp, TimeUnit unit) throws TimeoutException
	This operation performs the same function as unregisterInstance(InstanceHandle, Object) and can be used instead in the cases where the application desires to specify the value for the source time stamp. More...

void	waitForAcknowledgments (Duration maxWait) throws TimeoutException
	This operation is intended to be used only if the DataWriter has org.omg.dds.core.policy.Reliability#getKind() set to org.omg.dds.core.policy.Reliability.Kind#RELIABLE. More...

void	waitForAcknowledgments (long maxWait, TimeUnit unit) throws TimeoutException
	This operation is intended to be used only if the DataWriter has org.omg.dds.core.policy.Reliability#getKind() set to org.omg.dds.core.policy.Reliability.Kind#RELIABLE. More...

void	write (TYPE instanceData) throws TimeoutException
	This operation modifies the value of a data instance. More...

void	write (TYPE instanceData, Time sourceTimestamp) throws TimeoutException
	This operation performs the same functions as write(Object) except that the application provides the value for the parameter sourceTimestamp that is made available to DataReader objects. More...

void	write (TYPE instanceData, long sourceTimestamp, TimeUnit unit) throws TimeoutException
	This operation performs the same functions as write(Object) except that the application provides the value for the parameter sourceTimestamp that is made available to DataReader objects. More...

void	write (TYPE instanceData, InstanceHandle handle) throws TimeoutException
	This operation modifies the value of a data instance. More...

void	write (TYPE instanceData, InstanceHandle handle, Time sourceTimestamp) throws TimeoutException
	This operation performs the same function as write(Object, InstanceHandle) except that it also provides the value for the source time stamp that is made available to org.omg.dds.sub.DataReader objects by means of org.omg.dds.sub.Sample#getSourceTimestamp(). More...

void	write (TYPE instanceData, InstanceHandle handle, long sourceTimestamp, TimeUnit unit) throws TimeoutException
	This operation performs the same function as write(Object, InstanceHandle) except that it also provides the value for the source time stamp that is made available to org.omg.dds.sub.DataReader objects by means of org.omg.dds.sub.Sample#getSourceTimestamp(). More...

void	writeDispose (TYPE instanceData) throws TimeoutException
	This operation requests the Data Distribution Service to modify the instance and mark it disposed. More...

void	writeDispose (TYPE instanceData, Time sourceTimestamp) throws TimeoutException

void	writeDispose (TYPE instanceData, long sourceTimestamp, TimeUnit unit) throws TimeoutException

void	writeDispose (TYPE instanceData, InstanceHandle handle) throws TimeoutException

void	writeDispose (TYPE instanceData, InstanceHandle handle, Time sourceTimestamp) throws TimeoutException

void	writeDispose (TYPE instanceData, InstanceHandle handle, long sourceTimestamp, TimeUnit unit) throws TimeoutException

Detailed Description

OpenSplice-specific extension of org.omg.dds.pub.DataWriter with support for writing atomic writing of a sample and disposing the corresponding instance.

Parameters

<TYPE> The concrete type of the data to be published over the the topic.

Definition at line 37 of file DataWriter.java.

Member Function Documentation

◆ assertLiveliness()

void org.omg.dds.pub.DataWriter< TYPE >.assertLiveliness ( )

inherited

This operation manually asserts the liveliness of the DataWriter.

This is used in combination with the org.omg.dds.core.policy.Liveliness to indicate to the Service that the entity remains active.

This operation need only be used if org.omg.dds.core.policy.Liveliness#getKind() is either org.omg.dds.core.policy.Liveliness.Kind#MANUAL_BY_PARTICIPANT or org.omg.dds.core.policy.Liveliness.Kind#MANUAL_BY_TOPIC. Otherwise, it has no effect.

Note - Writing data via write(Object) asserts liveliness on the DataWriter itself and its DomainParticipant. Consequently the use of assertLiveliness is only needed if the application is not writing data regularly.

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.AlreadyClosedException	The corresponding DataWriter has been closed.

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

◆ cast()

public<OTHER> DataWriter<OTHER> org.omg.dds.pub.DataWriter< TYPE >.cast ( )

inherited

Cast this data writer to the given type, or throw an exception if the cast fails.

Parameters

<OTHER> The type of the data published by this writer, according to the caller.

Returns: this data writer

Exceptions

ClassCastException if the cast fails

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

◆ dispose() [1/4]

void org.omg.dds.pub.DataWriter< TYPE >.dispose ( InstanceHandle instanceHandle ) throws TimeoutException

inherited

This operation requests the middleware to delete the data (the actual deletion is postponed until there is no more use for that data in the whole system).

In general, applications are made aware of the deletion by means of operations on the org.omg.dds.sub.DataReader objects that already knew that instance. DataReader objects that didn't know the instance will never see it.

When this operation is used, the Service will automatically supply the value of the source time stamp that is made available to DataReader objects by means of org.omg.dds.sub.Sample#getSourceTimestamp().

The constraints on the values of the instanceHandle parameter and the corresponding error behavior are the same specified for unregisterInstance(InstanceHandle).

This operation may block and exit with TimeoutException under the same circumstances described for write(Object).

Parameters

instanceHandle The handle to the instance that needs to be disposed.

Exceptions

org.omg.dds.core.OutOfResourcesException	under the same circumstances as write(Object).
TimeoutException	under the same circumstances as write(Object).
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding DataWriter has been closed.

See also: #dispose(InstanceHandle, Object); #dispose(InstanceHandle, Object, Time); #dispose(InstanceHandle, Object, long, TimeUnit)

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

◆ dispose() [2/4]

void org.omg.dds.pub.DataWriter< TYPE >.dispose	(	InstanceHandle	instanceHandle,
		TYPE	instanceData
	)		throws TimeoutException

inherited

This operation requests the middleware to delete the data (the actual deletion is postponed until there is no more use for that data in the whole system).

In general, applications are made aware of the deletion by means of operations on the org.omg.dds.sub.DataReader objects that already knew that instance. DataReader objects that didn't know the instance will never see it.

This operation does not modify the value of the instance. The instanceData parameter is passed just for the purposes of identifying the instance.

When this operation is used, the Service will automatically supply the value of the source time stamp that is made available to DataReader objects by means of org.omg.dds.sub.Sample#getSourceTimestamp().

The constraints on the values of the instanceHandle parameter and the corresponding error behavior are the same specified for unregisterInstance(InstanceHandle, Object).

This operation may block and exit with TimeoutException under the same circumstances described for write(Object, InstanceHandle).

Parameters

instanceHandle	The handle to the instance that needs to be disposed.
instanceData	The actual instance to be disposed of.

Exceptions

org.omg.dds.core.OutOfResourcesException	under the same circumstances as write(Object, InstanceHandle).
TimeoutException	under the same circumstances as write(Object, InstanceHandle).
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding DataWriter has been closed.

See also: dispose(InstanceHandle); #dispose(InstanceHandle, Object, Time); #dispose(InstanceHandle, Object, long, TimeUnit)

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

◆ dispose() [3/4]

void org.omg.dds.pub.DataWriter< TYPE >.dispose	(	InstanceHandle	instanceHandle,
		TYPE	instanceData,
		Time	sourceTimestamp
	)		throws TimeoutException

inherited

This operation performs the same functions as dispose(InstanceHandle, Object) except that the application provides the value for the source time stamp that is made available to org.omg.dds.sub.DataReader objects by means of org.omg.dds.sub.Sample#getSourceTimestamp().

The constraints on the values of the instanceHandle parameter and the corresponding error behavior are the same specified for dispose(InstanceHandle, Object).

This operation may block and exit with TimeoutException under the same circumstances described for write(Object, InstanceHandle).

Parameters

instanceHandle	The handle to the instance that needs to be disposed.
instanceData	The actual instance to be disposed of.
sourceTimestamp	The timestamp which is provided for the DataReader. This timestamp is important for the interpretation of the DestinationOrderQosPolicy.

Exceptions

IllegalArgumentException	under the same circumstances as dispose(InstanceHandle, Object).
org.omg.dds.core.PreconditionNotMetException	under the same circumstances as dispose(InstanceHandle, Object).
org.omg.dds.core.OutOfResourcesException	under the same circumstances as write(Object, InstanceHandle).
TimeoutException	under the same circumstances as write(Object, InstanceHandle).
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding DataWriter has been closed.

See also: dispose(InstanceHandle); #dispose(InstanceHandle, Object); #dispose(InstanceHandle, Object, long, TimeUnit)

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

◆ dispose() [4/4]

void org.omg.dds.pub.DataWriter< TYPE >.dispose	(	InstanceHandle	instanceHandle,
		TYPE	instanceData,
		long	sourceTimestamp,
		TimeUnit	unit
	)		throws TimeoutException

inherited

This operation performs the same functions as dispose(InstanceHandle, Object) except that the application provides the value for the source time stamp that is made available to org.omg.dds.sub.DataReader objects by means of org.omg.dds.sub.Sample#getSourceTimestamp().

The constraints on the values of the instanceHandle parameter and the corresponding error behavior are the same specified for dispose(InstanceHandle, Object).

This operation may block and exit with TimeoutException under the same circumstances described for write(Object, InstanceHandle).

Parameters

instanceHandle	The handle to the instance that needs to be disposed.
instanceData	The actual instance to be disposed of.
sourceTimestamp	The timestamp which is provided for the DataReader. This timestamp is important for the interpretation of the DestinationOrderQosPolicy.
unit	The TimeUnit which the sourceTimestamp describes (i.e. TimeUnit.SECONDS or TimeUnit.MILLISECONDS)

Exceptions

IllegalArgumentException	under the same circumstances as dispose(InstanceHandle, Object).
org.omg.dds.core.PreconditionNotMetException	under the same circumstances as dispose(InstanceHandle, Object).
org.omg.dds.core.OutOfResourcesException	under the same circumstances as write(Object, InstanceHandle).
TimeoutException	under the same circumstances as write(Object, InstanceHandle).
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding DataWriter has been closed.

See also: dispose(InstanceHandle); #dispose(InstanceHandle, Object); #dispose(InstanceHandle, Object, Time)

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

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

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

◆ getKeyValue() [1/2]

TYPE org.omg.dds.pub.DataWriter< TYPE >.getKeyValue	(	TYPE	keyHolder,
		InstanceHandle	handle
	)

inherited

This operation can be used to retrieve the instance key that corresponds to an instance handle.

The operation will only fill the fields that form the key inside the keyHolder instance.

Parameters

keyHolder	a container, into which this method shall place its result.
handle	a handle indicating the instance whose value this method should get.

Returns: keyHolder, if it is non-null, or a new object otherwise.

Exceptions

IllegalArgumentException	if the handle does not correspond to an existing data object known to the DataWriter. If the implementation is not able to check invalid handles, then the result in this situation is unspecified.
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding DataWriter has been closed.
org.omg.dds.core.OutOfResourcesException	The Data Distribution Service ran out of resources to complete this operation.
org.omg.dds.core.PreconditionNotMetException	this instance is not registered

See also: getKeyValue(InstanceHandle)

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

◆ getKeyValue() [2/2]

TYPE org.omg.dds.pub.DataWriter< TYPE >.getKeyValue ( InstanceHandle handle )

inherited

This operation can be used to retrieve the instance key that corresponds to an instance handle.

The operation will only fill the fields that form the key inside the keyHolder instance.

Parameters

handle a handle indicating the instance whose value this method should get.

Returns: A new "key holder" object. The contents of the non-key fields are unspecified.

Exceptions

IllegalArgumentException	if the handle does not correspond to an existing data object known to the DataWriter. If the implementation is not able to check invalid handles, then the result in this situation is unspecified.
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding DataWriter has been closed.
org.omg.dds.core.OutOfResourcesException	The Data Distribution Service ran out of resources to complete this operation.
org.omg.dds.core.PreconditionNotMetException	this instance is not registered

See also: #getKeyValue(Object, InstanceHandle)

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

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

◆ getLivelinessLostStatus()

LivelinessLostStatus org.omg.dds.pub.DataWriter< TYPE >.getLivelinessLostStatus ( )

inherited

This operation obtains the LivelinessLostStatus object of the DataWriter.

This object contains the information whether the liveliness (that the DataWriter has committed through its LivelinessQosPolicy) was respected. This means that the status represents whether the DataWriter failed to actively signal its liveliness within the offered liveliness period. If the liveliness is lost, the DataReader objects will consider the DataWriter as no longer "alive". The LivelinessLostStatus can also be monitored using a DataWriterListener or by using the associated StatusCondition.

Returns: a LivelinessLostStatus object

Exceptions

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

See also: org.omg.dds.core.status.LivelinessLostStatus

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

◆ getMatchedSubscriptionData()

SubscriptionBuiltinTopicData org.omg.dds.pub.DataWriter< TYPE >.getMatchedSubscriptionData ( InstanceHandle subscriptionHandle )

inherited

This operation retrieves information on a subscription that is currently "associated" with the DataWriter; that is, a subscription with a matching org.omg.dds.topic.Topic and compatible QoS that the application has not indicated should be "ignored" by means of org.omg.dds.domain.DomainParticipant#ignoreSubscription(InstanceHandle).

The operation getMatchedSubscriptions() can be used to find the subscriptions that are currently matched with the DataWriter.

The operation may also fail if the infrastructure does not hold the information necessary to fill in the subscription_data. This is the case when OpenSplice is configured not to maintain discovery information in the Networking Service. (See the description for the NetworkingService/Discovery/enabled property in the Deployment Manual for more information about this subject.) In such cases the operation will throw an UnsupportedOperationException.

Parameters

subscriptionHandle a handle to the subscription, the data of which is to be retrieved.

Returns: a new SubscriptionBuiltinTopicData object containing a copy of the information.

Exceptions

IllegalArgumentException	if subscriptionHandle does not correspond to a subscription currently associated with the DataWriter.
UnsupportedOperationException	if the infrastructure does not hold the information necessary to fill in the subscriptionData.
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding DataWriter has been closed.
org.omg.dds.core.OutOfResourcesException	The Data Distribution Service ran out of resources to complete this operation.

See also: getMatchedSubscriptions()

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

◆ getMatchedSubscriptions()

Set<InstanceHandle> org.omg.dds.pub.DataWriter< TYPE >.getMatchedSubscriptions ( )

inherited

This operation retrieves the list of subscriptions currently "associated" with the DataWriter; that is, subscriptions that have a matching org.omg.dds.topic.Topic and compatible QoS that the application has not indicated should be "ignored" by means of org.omg.dds.domain.DomainParticipant#ignoreSubscription(InstanceHandle).

The handles returned in the 'subscriptionHandles' list are the ones that are used by the DDS implementation to locally identify the corresponding matched org.omg.dds.sub.DataReader entities. These handles match the ones that appear in org.omg.dds.sub.Sample#getInstanceHandle() when reading the "DCPSSubscriptions" built-in topic.

Be aware that since an instance handle is an opaque datatype, it does not necessarily mean that the handles obtained from the getMatchedSubscriptions operation have the same value as the ones that appear in the instanceHandle field of the SampleInfo when retrieving the subscription info through corresponding "DCPSSubscriptions" built-in reader. You can't just compare two handles to determine whether they represent the same subscription. If you want to know whether two handles actually do represent the same subscription, use both handles to retrieve their corresponding SubscriptionBuiltinTopicData samples and then compare the key field of both samples.

The operation may fail with an UnsupportedOperationException if the infrastructure does not locally maintain the connectivity information.

Returns: a new collection containing a copy of the information.

Exceptions

org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding DataWriter has been closed.
org.omg.dds.core.OutOfResourcesException	The Data Distribution Service ran out of resources to complete this operation.
UnsupportedOperationException	if the infrastructure does not hold the information necessary to fill in the subscriptionData.

See also: getMatchedSubscriptionData(InstanceHandle)

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

◆ getOfferedDeadlineMissedStatus()

OfferedDeadlineMissedStatus org.omg.dds.pub.DataWriter< TYPE >.getOfferedDeadlineMissedStatus ( )

inherited

This operation obtains the OfferedDeadlineMissedStatus object of the DataWriter.

This object contains the information whether the deadline (that the DataWriter has committed through its DeadlineQosPolicy) was respected for each instance. The OfferedDeadlineMissedStatus can also be monitored using a DataWriterListener or by using the associated StatusCondition.

Returns: a OfferedDeadlineMissedStatus object

Exceptions

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

See also: org.omg.dds.core.status.OfferedDeadlineMissedStatus

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

◆ getOfferedIncompatibleQosStatus()

OfferedIncompatibleQosStatus org.omg.dds.pub.DataWriter< TYPE >.getOfferedIncompatibleQosStatus ( )

inherited

This operation obtains the OfferedIncompatibleQosStatus object of the DataWriter.

This object contains the information whether a QosPolicy setting was incompatible with the requested QosPolicy setting. This means that the status represents whether a DataReader object has been discovered by the DataWriter with the same Topic and a requested DataReaderQos that was incompatible with the one offered by the DataWriter. The OfferedIncompatibleQosStatus can also be monitored using a DataWriterListener or by using the associated StatusCondition.

Returns: a OfferedIncompatibleQosStatus object

Exceptions

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

See also: org.omg.dds.core.status.OfferedIncompatibleQosStatus

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

◆ getParent()

Publisher org.omg.dds.pub.DataWriter< TYPE >.getParent ( )

inherited

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.AbstractDataWriter< TYPE >.

◆ getPublicationMatchedStatus()

PublicationMatchedStatus org.omg.dds.pub.DataWriter< TYPE >.getPublicationMatchedStatus ( )

inherited

This operation obtains the PublicationMatchedStatus object of the DataWriter.

This object contains the information whether a new match has been discovered for the current publication, or whether an existing match has ceased to exist.

This means that the status represents that either a DataReader object has been discovered by the DataWriter with the same Topic and a compatible Qos, or that a previously discovered DataReader has ceased to be matched to the current DataWriter. A DataReader may cease to match when it gets deleted, when it changes its Qos to a value that is incompatible with the current DataWriter or when either the DataWriter or the DataReader has chosen to put its matching counterpart on its ignore-list using the ignoreSubcription or ignorePublication operations on the DomainParticipant. The operation may fail if the infrastructure does not hold the information necessary to fill in the PublicationMatchedStatus. This is the case when OpenSplice is configured not to maintain discovery information in the Networking Service. (See the description for the NetworkingService/Discovery/enabled property in the Deployment Manual for more information about this subject.) In this case the operation will throw an UnsupportedOperationException. The PublicationMatchedStatus can also be monitored using a DataWriterListener or by using the associated StatusCondition.

Returns: a PublicationMatchedStatus object

Exceptions

org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding DataWriter has been closed.
org.omg.dds.core.OutOfResourcesException	The Data Distribution Service ran out of resources to complete this operation.
UnsupportedOperationException	if the infrastructure does not hold the information necessary to fill in the publicationData.

See also: org.omg.dds.core.status.PublicationMatchedStatus

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

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

inherited

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

◆ getTopic()

Topic<TYPE> org.omg.dds.pub.DataWriter< TYPE >.getTopic ( )

inherited

Returns: the org.omg.dds.topic.Topic associated with the DataWriter. This is the same Topic that was used to create the DataWriter.

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

◆ lookupInstance()

InstanceHandle org.omg.dds.pub.DataWriter< TYPE >.lookupInstance ( TYPE keyHolder )

inherited

This operation takes as a parameter an instance and returns a handle that can be used in subsequent operations that accept an instance handle as an argument.

The instance parameter is only used for the purpose of examining the fields that define the key.

This operation does not register the instance in question. If the instance has not been previously registered, or if for any other reason the Service is unable to provide an instance handle, the Service will return a nil handle.

Parameters

keyHolder a sample of the instance whose handle this method should look up.

Returns: an immutable handle to the instance.

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

◆ registerInstance() [1/3]

InstanceHandle org.omg.dds.pub.DataWriter< TYPE >.registerInstance ( TYPE instanceData ) throws TimeoutException

inherited

This operation informs the Service that the application will be modifying a particular instance.

It gives an opportunity to the Service to pre-configure itself to improve performance.

It takes as a parameter an instance (to get the key value) and returns a handle that can be used in successive write(Object) or dispose(InstanceHandle) operations.

This operation should be invoked prior to calling any operation that modifies the instance.

A nil handle may be returned by the Service if it does not want to allocate any handle for that instance.

This operation may block and exit with TimeoutException under the same circumstances described for the write(Object).

The operation is idempotent. If it is called for an already registered instance, it just returns the already allocated handle. This may be used to lookup and retrieve the handle allocated to a given instance. The explicit use of this operation is optional as the application may call directly the write operation and specify a nil handle to indicate that the 'key' should be examined to identify the instance.

Blocking

If the HistoryQosPolicy is set to KEEP_ALL, the registerInstance operation on the DataWriter may block if the modification would cause data to be lost because one of the limits, specified in the ResourceLimitsQosPolicy, to be exceeded. In case the synchronous attribute value of the ReliabilityQosPolicy is set to TRUE for communicating DataWriters and DataReaders then the DataWriter will wait until all synchronous DataReaders have acknowledged the data. Under these circumstances, the maxBlockingTime attribute of the ReliabilityQosPolicy configures the maximum time the registerInstance operation may block (either waiting for space to become available or data to be acknowledged). If maxBlockingTime elapses before the DataWriter is able to store the modification without exceeding the limits and all expected acknowledgments are received, the registerInstance operation will fail and return a nilHandle.

Returns: A handle to the Instance, which may be used for writing and disposing of. In case of an error, a nilHandle is returned.

Parameters

instanceData The instance, which the application writes to or disposes of.

Exceptions

org.omg.dds.core.OutOfResourcesException	under the same circumstances described for write(Object).
TimeoutException	under the same circumstances described for write(Object).
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding DataWriter has been closed.

See also: #registerInstance(Object, Time); #registerInstance(Object, long, TimeUnit); unregisterInstance(InstanceHandle); #unregisterInstance(InstanceHandle, Object); InstanceHandle::nilHandle(org.omg.dds.core.ServiceEnvironment)

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

◆ registerInstance() [2/3]

InstanceHandle org.omg.dds.pub.DataWriter< TYPE >.registerInstance	(	TYPE	instanceData,
		Time	sourceTimestamp
	)		throws TimeoutException

inherited

This operation performs the same function as registerInstance(Object) and can be used instead in the cases where the application desires to specify the value for the source time stamp.

The source time stamp potentially affects the relative order in which readers observe events from multiple writers. For details see org.omg.dds.core.policy.DestinationOrder.

This operation may block and exit with TimeoutException under the same circumstances described for the write(Object).

Returns: A handle to the Instance, which may be used for writing and disposing of. In case of an error, a nilHandle is returned.

Parameters

instanceData	The instance, which the application writes to or disposes of.
sourceTimestamp	The timestamp which is provided for the DataReader. This timestamp is important for the interpretation of the DestinationOrderQosPolicy.

Exceptions

org.omg.dds.core.OutOfResourcesException	under the same circumstances described for write(Object).
TimeoutException	under the same circumstances described for write(Object).
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding DataWriter has been closed.

See also: #registerInstance(Object); #registerInstance(Object, long, TimeUnit); #unregisterInstance(InstanceHandle, Object, Time)

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

◆ registerInstance() [3/3]

InstanceHandle org.omg.dds.pub.DataWriter< TYPE >.registerInstance	(	TYPE	instanceData,
		long	sourceTimestamp,
		TimeUnit	unit
	)		throws TimeoutException

inherited

This operation performs the same function as registerInstance(Object) and can be used instead in the cases where the application desires to specify the value for the source time stamp.

The source time stamp potentially affects the relative order in which readers observe events from multiple writers. For details see org.omg.dds.core.policy.DestinationOrder.

This operation may block and exit with TimeoutException under the same circumstances described for the write(Object).

Returns: A handle to the Instance, which may be used for writing and disposing of. In case of an error, a nilHandle is returned.

Parameters

instanceData	The instance, which the application writes to or disposes of.
sourceTimestamp	The timestamp which is provided for the DataReader. This timestamp is important for the interpretation of the DestinationOrderQosPolicy.
unit	The TimeUnit which the sourceTimestamp describes (i.e. TimeUnit.SECONDS or TimeUnit.MILLISECONDS)

Exceptions

org.omg.dds.core.OutOfResourcesException	under the same circumstances described for write(Object).
TimeoutException	under the same circumstances described for write(Object).
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding DataWriter has been closed.

See also: #registerInstance(Object); #registerInstance(Object, Time); #unregisterInstance(InstanceHandle, Object, long, TimeUnit)

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

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

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

◆ unregisterInstance() [1/4]

void org.omg.dds.pub.DataWriter< TYPE >.unregisterInstance ( InstanceHandle handle ) throws TimeoutException

inherited

This operation reverses the action of registerInstance(Object).

It should only be called on an instance that is currently registered.

The operation should be called just once per instance, regardless of how many times registerInstance(Object) was called for that instance.

This operation informs the Service that the DataWriter is not intending to modify that data instance any more. This operation also indicates that the Service can locally remove all information regarding that instance. The application should not attempt to use the handle previously allocated to that instance after calling unregisterInstance(InstanceHandle).

If handle is any value other than nil, then it must correspond to the value returned by registerInstance(Object) when the instance (identified by its key) was registered.

If after that, the application wants to modify (write or dispose) the instance, it has to register it again, or else use a nil handle.

This operation does not indicate that the instance is deleted (that is the purpose of dispose). The operation just indicates that the DataWriter no longer has 'anything to say' about the instance. DataReader entities that are reading the instance will eventually receive a sample with a org.omg.dds.sub.InstanceState#NOT_ALIVE_NO_WRITERS instance state if no other DataWriter entities are writing the instance.

This operation can affect the ownership of the data instance (see org.omg.dds.core.policy.Ownership). If the DataWriter was the exclusive owner of the instance, then calling this method will relinquish that ownership.

This operation may block and exit with TimeoutException under the same circumstances described for the write(Object).

Parameters

handle The handle to the Instance, which has been used for writing and disposing.

Exceptions

IllegalArgumentException	if the handle does not correspond to an existing instance, and if this situation is detectable by the Service implementation. If the situation is not detectable, the behavior is unspecified.
TimeoutException	Either the current action overflowed the available resources as specified by the combination of the ReliablityQosPolicy, HistoryQosPolicy and ResourceLimitsQosPolicy, or the current action was waiting for data delivery acknowledgment by synchronous DataReaders. This caused blocking of the unregisterInstance operation, which could not be resolved before maxBlockingTime of the ReliabilityQosPolicy elapsed.
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding DataWriter has been closed.
org.omg.dds.core.PreconditionNotMetException	The handle has not been registered with this DataWriter.

See also: #unregisterInstance(InstanceHandle, Object); #unregisterInstance(InstanceHandle, Object, Time); #unregisterInstance(InstanceHandle, Object, long, TimeUnit); #registerInstance(Object)

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

◆ unregisterInstance() [2/4]

void org.omg.dds.pub.DataWriter< TYPE >.unregisterInstance	(	InstanceHandle	handle,
		TYPE	instanceData
	)		throws TimeoutException

inherited

This operation reverses the action of registerInstance(Object).

It should only be called on an instance that is currently registered.

The operation should be called just once per instance, regardless of how many times registerInstance(Object) was called for that instance.

This operation informs the Service that the DataWriter is not intending to modify that data instance any more. This operation also indicates that the Service can locally remove all information regarding that instance. The application should not attempt to use the handle previously allocated to that instance after calling unregisterInstance(InstanceHandle).

A nil handle can be used for the parameter handle. This indicates that the identity of the instance should be automatically deduced from the instance data (by means of the key).

If handle is any value other than nil, then it must correspond to the value returned by registerInstance(Object) when the instance (identified by its key) was registered.

If after that, the application wants to modify (write or dispose) the instance, it has to register it again, or else use a nil handle.

This operation does not indicate that the instance is deleted (that is the purpose of dispose). The operation just indicates that the DataWriter no longer has 'anything to say' about the instance. DataReader entities that are reading the instance will eventually receive a sample with a org.omg.dds.sub.InstanceState#NOT_ALIVE_NO_WRITERS instance state if no other DataWriter entities are writing the instance.

This operation can affect the ownership of the data instance (see org.omg.dds.core.policy.Ownership). If the DataWriter was the exclusive owner of the instance, then calling this method will relinquish that ownership.

This operation may block and exit with TimeoutException under the same circumstances described for the write(Object).

Parameters

handle	The handle to the Instance, which has been used for writing and disposing.
instanceData	The instance, which the application writes to or disposes of.

Exceptions

IllegalArgumentException	if the handle does not correspond to an existing instance, and if this situation is detectable by the Service implementation. If the situation is not detectable, the behavior is unspecified.
org.omg.dds.core.PreconditionNotMetException	if the handle corresponds to an existing instance but does not correspond to the same instance referred by the instancData parameter, and if this situation is detectable by the Service implementation If the situation is not detectable, the behavior is unspecified.
TimeoutException	Either the current action overflowed the available resources as specified by the combination of the ReliablityQosPolicy, HistoryQosPolicy and ResourceLimitsQosPolicy, or the current action was waiting for data delivery acknowledgment by synchronous DataReaders. This caused blocking of the unregisterInstance operation, which could not be resolved before maxBlockingTime of the ReliabilityQosPolicy elapsed.
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding DataWriter has been closed.

See also: unregisterInstance(InstanceHandle); #unregisterInstance(InstanceHandle, Object, Time); #unregisterInstance(InstanceHandle, Object, long, TimeUnit); #registerInstance(Object); InstanceHandle::nilHandle(org.omg.dds.core.ServiceEnvironment)

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

◆ unregisterInstance() [3/4]

void org.omg.dds.pub.DataWriter< TYPE >.unregisterInstance	(	InstanceHandle	handle,
		TYPE	instanceData,
		Time	sourceTimestamp
	)		throws TimeoutException

inherited

This operation performs the same function as unregisterInstance(InstanceHandle, Object) and can be used instead in the cases where the application desires to specify the value for the source time stamp.

The source time stamp potentially affects the relative order in which readers observe events from multiple writers. For details see org.omg.dds.core.policy.DestinationOrder.

The constraints on the values of the handle parameter and the corresponding error behavior are the same specified for the unregisterInstance(InstanceHandle, Object) operation.

This operation may block and exit with TimeoutException under the same circumstances described for the write(Object).

Parameters

handle	The handle to the Instance, which has been used for writing and disposing.
instanceData	The instance, which the application writes to or disposes of.
sourceTimestamp	The timestamp which is provided for the DataReader. This timestamp is important for the interpretation of the DestinationOrderQosPolicy.

Exceptions

IllegalArgumentException	if the handle does not correspond to an existing instance, and if this situation is detectable by the Service implementation. If the situation is not detectable, the behavior is unspecified.
org.omg.dds.core.PreconditionNotMetException	if the handle corresponds to an existing instance but does not correspond to the same instance referred by the instancData parameter, and if this situation is detectable by the Service implementation If the situation is not detectable, the behavior is unspecified.
TimeoutException	Either the current action overflowed the available resources as specified by the combination of the ReliablityQosPolicy, HistoryQosPolicy and ResourceLimitsQosPolicy, or the current action was waiting for data delivery acknowledgment by synchronous DataReaders. This caused blocking of the unregisterInstance operation, which could not be resolved before maxBlockingTime of the ReliabilityQosPolicy elapsed.
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding DataWriter has been closed.

See also: unregisterInstance(InstanceHandle); #unregisterInstance(InstanceHandle, Object); #unregisterInstance(InstanceHandle, Object, long, TimeUnit); #registerInstance(Object, Time)

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

◆ unregisterInstance() [4/4]

void org.omg.dds.pub.DataWriter< TYPE >.unregisterInstance	(	InstanceHandle	handle,
		TYPE	instanceData,
		long	sourceTimestamp,
		TimeUnit	unit
	)		throws TimeoutException

inherited

This operation performs the same function as unregisterInstance(InstanceHandle, Object) and can be used instead in the cases where the application desires to specify the value for the source time stamp.

The source time stamp potentially affects the relative order in which readers observe events from multiple writers. For details see org.omg.dds.core.policy.DestinationOrder.

The constraints on the values of the handle parameter and the corresponding error behavior are the same specified for the unregisterInstance(InstanceHandle, Object) operation.

This operation may block and exit with TimeoutException under the same circumstances described for the write(Object).

Parameters

instanceData	The instance, which the application writes to or disposes of.
sourceTimestamp	The timestamp which is provided for the DataReader. This timestamp is important for the interpretation of the DestinationOrderQosPolicy.
unit	The TimeUnit which the sourceTimestamp describes (i.e. TimeUnit.SECONDS or TimeUnit.MILLISECONDS)

Exceptions

IllegalArgumentException	if the handle does not correspond to an existing instance, and if this situation is detectable by the Service implementation. If the situation is not detectable, the behavior is unspecified.
org.omg.dds.core.PreconditionNotMetException	if the handle corresponds to an existing instance but does not correspond to the same instance referred by the instancData parameter, and if this situation is detectable by the Service implementation If the situation is not detectable, the behavior is unspecified.
TimeoutException	Either the current action overflowed the available resources as specified by the combination of the ReliablityQosPolicy, HistoryQosPolicy and ResourceLimitsQosPolicy, or the current action was waiting for data delivery acknowledgment by synchronous DataReaders. This caused blocking of the unregisterInstance operation, which could not be resolved before maxBlockingTime of the ReliabilityQosPolicy elapsed.
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding DataWriter has been closed.

See also: unregisterInstance(InstanceHandle); #unregisterInstance(InstanceHandle, Object); #unregisterInstance(InstanceHandle, Object, Time); #registerInstance(Object, long, TimeUnit)

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

◆ waitForAcknowledgments() [1/2]

void org.omg.dds.pub.DataWriter< TYPE >.waitForAcknowledgments ( Duration maxWait ) throws TimeoutException

inherited

This operation is intended to be used only if the DataWriter has org.omg.dds.core.policy.Reliability#getKind() set to org.omg.dds.core.policy.Reliability.Kind#RELIABLE.

Otherwise the operation will return immediately.

The operation blocks the calling thread until either all data written by the DataWriter is acknowledged by all matched org.omg.dds.sub.DataReader entities that have org.omg.dds.core.policy.Reliability#getKind() set to org.omg.dds.core.policy.Reliability.Kind#RELIABLE, or else the duration specified by the maxWait parameter elapses, whichever happens first.

A normal return indicates that all the samples written have been acknowledged by all reliable matched data readers.

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

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

◆ waitForAcknowledgments() [2/2]

void org.omg.dds.pub.DataWriter< TYPE >.waitForAcknowledgments	(	long	maxWait,
		TimeUnit	unit
	)		throws TimeoutException

inherited

This operation is intended to be used only if the DataWriter has org.omg.dds.core.policy.Reliability#getKind() set to org.omg.dds.core.policy.Reliability.Kind#RELIABLE.

Otherwise the operation will return immediately.

The operation blocks the calling thread until either all data written by the DataWriter is acknowledged by all matched org.omg.dds.sub.DataReader entities that have org.omg.dds.core.policy.Reliability#getKind() set to org.omg.dds.core.policy.Reliability.Kind#RELIABLE, or else the duration specified by the maxWait parameter elapses, whichever happens first.

A normal return indicates that all the samples written have been acknowledged by all reliable matched data readers.

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

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

◆ write() [1/6]

void org.omg.dds.pub.DataWriter< TYPE >.write ( TYPE instanceData ) throws TimeoutException

inherited

This operation modifies the value of a data instance.

When this operation is used, the Service will automatically supply the value of the source time stamp that is made available to org.omg.dds.sub.DataReader objects by means of org.omg.dds.sub.Sample#getSourceTimestamp(). See also org.omg.dds.core.policy.DestinationOrder.

As a side effect, this operation asserts liveliness on the DataWriter itself, the org.omg.dds.pub.Publisher and the org.omg.dds.domain.DomainParticipant.

If org.omg.dds.core.policy.Reliability#getKind() kind is set to org.omg.dds.core.policy.Reliability.Kind#RELIABLE, the operation may block if the modification would cause data to be lost or else cause one of the limits specified in org.omg.dds.core.policy.ResourceLimits to be exceeded. Under these circumstances, org.omg.dds.core.policy.Reliability#getMaxBlockingTime() configures the maximum time the operation may block waiting for space to become available. If this duration elapses before the DataWriter is able to store the modification without exceeding the limits, the operation will fail with TimeoutException.

Specifically, the DataWriter write operation may block in the following situations (note that the list may not be exhaustive), even if org.omg.dds.core.policy.History#getKind() is org.omg.dds.core.policy.History.Kind#KEEP_LAST.

If (org.omg.dds.core.policy.ResourceLimits#getMaxSamples() < org.omg.dds.core.policy.ResourceLimits#getMaxInstances() * org.omg.dds.core.policy.History#getDepth()), then in the situation where the max samples resource limit is exhausted the Service is allowed to discard samples of some other instance as long as at least one sample remains for such an instance. If it is still not possible to make space available to store the modification, the writer is allowed to block.
If (org.omg.dds.core.policy.ResourceLimits#getMaxSamples() < org.omg.dds.core.policy.ResourceLimits#getMaxInstances()), then the DataWriter may block regardless of the HISTORY depth.

Instead of blocking, the operation is allowed to fail immediately with org.omg.dds.core.OutOfResourcesException provided the following two conditions are met:

The reason for blocking would be that the RESOURCE_LIMITS are exceeded.
The service determines that waiting the max blocking time has no chance of freeing the necessary resources. For example, if the only way to gain the necessary resources would be for the user to unregister an instance.

Parameters

instanceData The data to be written

Exceptions

org.omg.dds.core.OutOfResourcesException	if it is not possible for sufficient resources to be made available within the configured max blocking time.
TimeoutException	Either the current action overflowed the available resources as specified by the combination of the ReliablityQosPolicy, HistoryQosPolicy and ResourceLimitsQosPolicy, or the current action was waiting for data delivery acknowledgment by synchronous DataReaders. This caused blocking of the unregisterInstance operation, which could not be resolved before maxBlockingTime of the ReliabilityQosPolicy elapsed.
IllegalArgumentException	if the handle is not a valid sample.
org.omg.dds.core.PreconditionNotMetException	If the handle has not been registered with this DataWriter
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding DataWriter has been closed.

See also: #write(Object, InstanceHandle); #write(Object, InstanceHandle, Time); #write(Object, InstanceHandle, long, TimeUnit)

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

◆ write() [2/6]

void org.omg.dds.pub.DataWriter< TYPE >.write	(	TYPE	instanceData,
		Time	sourceTimestamp
	)		throws TimeoutException

inherited

This operation performs the same functions as write(Object) except that the application provides the value for the parameter sourceTimestamp that is made available to DataReader objects.

This timestamp is important for the interpretation of the DestinationOrderQosPolicy.

Parameters

instanceData	The data to be written
sourceTimestamp	The timestamp which is provided for the DataReader. This timestamp is important for the interpretation of the DestinationOrderQosPolicy.

Exceptions

org.omg.dds.core.OutOfResourcesException	if it is not possible for sufficient resources to be made available within the configured max blocking time.
TimeoutException	Either the current action overflowed the available resources as specified by the combination of the ReliablityQosPolicy, HistoryQosPolicy and ResourceLimitsQosPolicy, or the current action was waiting for data delivery acknowledgment by synchronous DataReaders. This caused blocking of the unregisterInstance operation, which could not be resolved before maxBlockingTime of the ReliabilityQosPolicy elapsed.
IllegalArgumentException	if the handle is not a valid sample.
org.omg.dds.core.PreconditionNotMetException	If the handle has not been registered with this DataWriter
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding DataWriter has been closed.

See also: #write(Object, InstanceHandle); #write(Object, InstanceHandle, Time); #write(Object, InstanceHandle, long, TimeUnit)

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

◆ write() [3/6]

void org.omg.dds.pub.DataWriter< TYPE >.write	(	TYPE	instanceData,
		long	sourceTimestamp,
		TimeUnit	unit
	)		throws TimeoutException

inherited

This operation performs the same functions as write(Object) except that the application provides the value for the parameter sourceTimestamp that is made available to DataReader objects.

This timestamp is important for the interpretation of the DestinationOrderQosPolicy.

Parameters

instanceData	The data to be written
sourceTimestamp	The timestamp which is provided for the DataReader. This timestamp is important for the interpretation of the DestinationOrderQosPolicy.
unit	The TimeUnit which the sourceTimestamp describes (i.e. TimeUnit.SECONDS or TimeUnit.MILLISECONDS)

Exceptions

org.omg.dds.core.OutOfResourcesException	if it is not possible for sufficient resources to be made available within the configured max blocking time.
TimeoutException	Either the current action overflowed the available resources as specified by the combination of the ReliablityQosPolicy, HistoryQosPolicy and ResourceLimitsQosPolicy, or the current action was waiting for data delivery acknowledgment by synchronous DataReaders. This caused blocking of the unregisterInstance operation, which could not be resolved before maxBlockingTime of the ReliabilityQosPolicy elapsed.
IllegalArgumentException	if the handle is not a valid sample.
org.omg.dds.core.PreconditionNotMetException	If the handle has not been registered with this DataWriter
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding DataWriter has been closed.

See also: #write(Object, InstanceHandle); #write(Object, InstanceHandle, Time); #write(Object, InstanceHandle, long, TimeUnit)

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

◆ write() [4/6]

void org.omg.dds.pub.DataWriter< TYPE >.write	(	TYPE	instanceData,
		InstanceHandle	handle
	)		throws TimeoutException

inherited

This operation modifies the value of a data instance.

When this operation is used, the Service will automatically supply the value of the source time stamp that is made available to org.omg.dds.sub.DataReader objects by means of org.omg.dds.sub.Sample#getSourceTimestamp(). See also org.omg.dds.core.policy.DestinationOrder.

As a side effect, this operation asserts liveliness on the DataWriter itself, the org.omg.dds.pub.Publisher and the org.omg.dds.domain.DomainParticipant.

A nil handle can be used for the parameter handle. This indicates that the identity of the instance should be automatically deduced from the instanceData (by means of the key). If handle is not nil, then it must correspond to the value returned by registerInstance(Object) when the instance (identified by its key) was registered.

If org.omg.dds.core.policy.Reliability#getKind() kind is set to org.omg.dds.core.policy.Reliability.Kind#RELIABLE, the operation may block if the modification would cause data to be lost or else cause one of the limits specified in org.omg.dds.core.policy.ResourceLimits to be exceeded. Under these circumstances, org.omg.dds.core.policy.Reliability#getMaxBlockingTime() configures the maximum time the operation may block waiting for space to become available. If this duration elapses before the DataWriter is able to store the modification without exceeding the limits, the operation will fail with TimeoutException.

Specifically, the DataWriter write operation may block in the following situations (note that the list may not be exhaustive), even if org.omg.dds.core.policy.History#getKind() is org.omg.dds.core.policy.History.Kind#KEEP_LAST.

If (org.omg.dds.core.policy.ResourceLimits#getMaxSamples() < org.omg.dds.core.policy.ResourceLimits#getMaxInstances() * org.omg.dds.core.policy.History#getDepth()), then in the situation where the max samples resource limit is exhausted the Service is allowed to discard samples of some other instance as long as at least one sample remains for such an instance. If it is still not possible to make space available to store the modification, the writer is allowed to block.
If (org.omg.dds.core.policy.ResourceLimits#getMaxSamples() < org.omg.dds.core.policy.ResourceLimits#getMaxInstances()), then the DataWriter may block regardless of the HISTORY depth.

Instead of blocking, the operation is allowed to fail immediately with org.omg.dds.core.OutOfResourcesException provided the following two conditions are met:

The reason for blocking would be that the RESOURCE_LIMITS are exceeded.
The service determines that waiting the max blocking time has no chance of freeing the necessary resources. For example, if the only way to gain the necessary resources would be for the user to unregister an instance.

Parameters

instanceData	The data to be written
handle	the handle to the instance as supplied by registerInstance.

Exceptions

IllegalArgumentException	if the handle does not correspond to an existing instance, and if this situation is detectable by the Service implementation. If the situation is not detectable, the behavior is unspecified.
org.omg.dds.core.PreconditionNotMetException	if the handle corresponds to an existing instance but does not correspond to the same instance referred by the instancData parameter, and if this situation is detectable by the Service implementation If the situation is not detectable, the behavior is unspecified.
org.omg.dds.core.OutOfResourcesException	if it is not possible for sufficient resources to be made available within the configured max blocking time.
TimeoutException	if the configured maximum time elapses and the DataWriter is still unable to store the new sample without exceeding its configured resource limits.
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding DataWriter has been closed.

See also: #write(Object); #write(Object, InstanceHandle, Time); #write(Object, InstanceHandle, long, TimeUnit); InstanceHandle::nilHandle(org.omg.dds.core.ServiceEnvironment)

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

◆ write() [5/6]

void org.omg.dds.pub.DataWriter< TYPE >.write	(	TYPE	instanceData,
		InstanceHandle	handle,
		Time	sourceTimestamp
	)		throws TimeoutException

inherited

This operation performs the same function as write(Object, InstanceHandle) except that it also provides the value for the source time stamp that is made available to org.omg.dds.sub.DataReader objects by means of org.omg.dds.sub.Sample#getSourceTimestamp().

The constraints on the values of the handle parameter and the corresponding error behavior are the same specified for write(Object, InstanceHandle).

This operation may block and exit with TimeoutException under the same circumstances described for write(Object, InstanceHandle).

Parameters

instanceData	The data to be written
handle	the handle to the instance as supplied by registerInstance.
sourceTimestamp	The timestamp which is provided for the DataReader. This timestamp is important for the interpretation of the DestinationOrderQosPolicy.

Exceptions

IllegalArgumentException	under the same circumstances as write(Object, InstanceHandle).
org.omg.dds.core.PreconditionNotMetException	under the same circumstances as write(Object, InstanceHandle).
org.omg.dds.core.OutOfResourcesException	under the same circumstances as write(Object, InstanceHandle).
TimeoutException	under the same circumstances as write(Object, InstanceHandle).
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding DataWriter has been closed.

See also: #write(Object); #write(Object, InstanceHandle); #write(Object, InstanceHandle, long, TimeUnit)

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

◆ write() [6/6]

void org.omg.dds.pub.DataWriter< TYPE >.write	(	TYPE	instanceData,
		InstanceHandle	handle,
		long	sourceTimestamp,
		TimeUnit	unit
	)		throws TimeoutException

inherited

This operation performs the same function as write(Object, InstanceHandle) except that it also provides the value for the source time stamp that is made available to org.omg.dds.sub.DataReader objects by means of org.omg.dds.sub.Sample#getSourceTimestamp().

The constraints on the values of the handle parameter and the corresponding error behavior are the same specified for write(Object, InstanceHandle).

This operation may block and exit with TimeoutException under the same circumstances described for write(Object, InstanceHandle).

Parameters

instanceData	The data to be written
handle	the handle to the instance as supplied by registerInstance.
sourceTimestamp	The timestamp which is provided for the DataReader. This timestamp is important for the interpretation of the DestinationOrderQosPolicy.
unit	The TimeUnit which the sourceTimestamp describes (i.e. TimeUnit.SECONDS or TimeUnit.MILLISECONDS)

Exceptions

IllegalArgumentException	under the same circumstances as write(Object, InstanceHandle).
org.omg.dds.core.PreconditionNotMetException	under the same circumstances as write(Object, InstanceHandle).
org.omg.dds.core.OutOfResourcesException	under the same circumstances as write(Object, InstanceHandle).
TimeoutException	under the same circumstances as write(Object, InstanceHandle).
org.omg.dds.core.DDSException	An internal error has occurred.
org.omg.dds.core.AlreadyClosedException	The corresponding DataWriter has been closed.

See also: #write(Object); #write(Object, InstanceHandle); #write(Object, InstanceHandle, Time)

Implemented in org.opensplice.dds.pub.DataWriterImpl< TYPE >.

◆ writeDispose() [1/6]

void org.opensplice.dds.pub.DataWriter< TYPE >.writeDispose ( TYPE instanceData ) throws TimeoutException

This operation requests the Data Distribution Service to modify the instance and mark it disposed.

Copies of the instance and its corresponding samples, which are stored in every connected DataReader and, dependent on the QoSPolicy settings, also in the Transient and Persistent stores, will be modified and marked as disposed by setting the InstanceState to NOT_ALIVE_DISPOSED.

When this operation is used, the Data Distribution Service will automatically supply the value of the sourceTimestamp that is made available to connected DataReader objects. This timestamp is important for the interpretation of the DestinationOrder QosPolicy.

As a side effect, this operation asserts liveliness on the DataWriter itself and on the containing DomainParticipant.

Effects on DataReaders
Actual deletion of the instance administration in a connected DataReader will be postponed until the following conditions have been met:

the instance must be unregistered (either implicitly or explicitly) by all connected DataWriters that have previously registered it.
- A DataWriter can register an instance explicitly by using one of the special registerInstance operations
- A DataWriter can register an instance implicitly by using the special nil InstanceHandle in one of the other DataWriter operations.
- A DataWriter can unregister an instance explicitly by using one of the special unregisterInstance methods
- A DataWriter will unregister all its contained instances implicitly when it is deleted.
- When a DataReader detects a loss of liveliness in one of its connected DataWriters, it will consider all instances registered by that DataWriter as being implicitly unregistered.
and the application must have consumed all samples belonging to the instance, either implicitly or explicitly.
- An application can consume samples explicitly by invoking the take operation, or one of its variants, on its DataReaders.
- The DataReader can consume disposed samples implicitly when the autopurgeDisposedSamplesDelay of the ReaderDataLifecycle QosPolicy has expired.

The DataReader may also remove instances that haven't been disposed first: this happens when the autopurgeNowriterSamplesDelay of the ReaderDataLifecycle QosPolicy has expired after the instance is considered unregistered by all connected DataWriters ( i . e. when it has a InstanceState of NOT_ALIVE_NO_WRITERS). See also org.omg.dds.core.policy.ReaderDataLifecycle

Effects on Transient/Persistent Stores
Actual deletion of the instance administration in the connected Transient and Persistent stores will be postponed until the following conditions have been met:

the instance must be unregistered (either implicitly or explicitly) by all connected DataWriters that have previously registered it. (See above.)
and the period of time specified by the service_cleanup_delay attribute in the DurabilityServiceQosPolicy on the Topic must have elapsed after the instance is considered unregistered by all connected DataWriters.

Instance Handle
The nil handle value (see org.omg.dds.core.InstanceHandle#nilHandle(org.omg.dds.core.ServiceEnvironment) can be used for the parameter handle. This indicates the identity of the instance is automatically deduced from the instance_data (by means of the key). If handle is any value other than nil, it must correspond to the value that was returned by either the register_instance operation or the register_instance_w_timestamp operation, when the instance (identified by its key) was registered. If there is no correspondence, the result of the operation is unspecified. The sample that is passed as instance_data will actually be delivered to the connected DataReaders, but will immediately be marked for deletion.

Blocking
If the org.omg.dds.core.policy.History QosPolicy is set to KEEP_ALL, the writeDispose operation on the DataWriter may block if the modification would cause data to be lost because one of the limits, specified in the org.omg.dds.core.policy.ResourceLimits QosPolicy, to be exceeded. In case the synchronous attribute value of the org.omg.dds.core.policy.Reliability QosPolicy is set to true for communicating DataWriters and DataReaders then the DataWriter will wait until all synchronous DataReaders have acknowledged the data. Under these circumstances, the maxBlockingTime attribute of the Reliability QosPolicy configures the maximum time the writeDispose operation may block (either waiting for space to become available or data to be acknowledged). If maxBlockingTime elapses before the DataWriter is able to store the modification without exceeding the limits and all expected acknowledgements are received, the writeDispose operation will fail and throws a TimeoutException.

Sample Validation
Before the sample is accepted by the DataWriter, it is validated against the restrictions imposed by the IDL to Java language mapping, where:

a string (bounded or unbounded) may not be null. (Use "" for an empty string instead)
the length of a bounded string may not exceed the limit specified in IDL
the length of a bounded sequence may not exceed the limit specified in IDL
the length of an array must exactly match the size specified in IDL

If any of these restrictions is violated, the operation will fail and throw a IllegalArgumentException. More specific information about the context of this error will be written to the error log.

Parameters

instanceData the data to write

Exceptions

TimeoutException	if the configured maximum time elapses and the DataWriter is still unable to store the new sample without exceeding its configured resource limits.
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 DataWriter has been closed.

See also: #writeDispose(Object, Time); #writeDispose(Object, long, TimeUnit); #writeDispose(Object, InstanceHandle); #writeDispose(Object, InstanceHandle, Time); #writeDispose(Object, InstanceHandle, long, TimeUnit)

◆ writeDispose() [2/6]

void org.opensplice.dds.pub.DataWriter< TYPE >.writeDispose	(	TYPE	instanceData,
		Time	sourceTimestamp
	)		throws TimeoutException

See also: #writeDispose(Object)

Parameters

instanceData	The data to write
sourceTimestamp	The timestamp which is provided for the DataReader. This timestamp is important for the interpretation of the DestinationOrderQosPolicy.

◆ writeDispose() [3/6]

void org.opensplice.dds.pub.DataWriter< TYPE >.writeDispose	(	TYPE	instanceData,
		long	sourceTimestamp,
		TimeUnit	unit
	)		throws TimeoutException

See also: #writeDispose(Object)

Parameters

instanceData	The data to write
sourceTimestamp	The timestamp which is provided for the DataReader. This timestamp is important for the interpretation of the DestinationOrderQosPolicy.
unit	The TimeUnit which the sourceTimestamp describes (i.e. TimeUnit.SECONDS or TimeUnit.MILLISECONDS)

◆ writeDispose() [4/6]

void org.opensplice.dds.pub.DataWriter< TYPE >.writeDispose	(	TYPE	instanceData,
		InstanceHandle	handle
	)		throws TimeoutException

See also: #writeDispose(Object)

Parameters

instanceData	The data to write
handle	The handle to the instance that needs to be disposed.

◆ writeDispose() [5/6]

void org.opensplice.dds.pub.DataWriter< TYPE >.writeDispose	(	TYPE	instanceData,
		InstanceHandle	handle,
		Time	sourceTimestamp
	)		throws TimeoutException

See also: #writeDispose(Object)

Parameters

instanceData	The data to write
handle	The handle to the instance that needs to be disposed.
sourceTimestamp	The timestamp which is provided for the DataReader. This timestamp is important for the interpretation of the DestinationOrderQosPolicy.

◆ writeDispose() [6/6]

void org.opensplice.dds.pub.DataWriter< TYPE >.writeDispose	(	TYPE	instanceData,
		InstanceHandle	handle,
		long	sourceTimestamp,
		TimeUnit	unit
	)		throws TimeoutException

See also: #writeDispose(Object)

Parameters

instanceData	The data to write
handle	The handle to the instance that needs to be disposed.
sourceTimestamp	The timestamp which is provided for the DataReader. This timestamp is important for the interpretation of the DestinationOrderQosPolicy.
unit	The TimeUnit which the sourceTimestamp describes (i.e. TimeUnit.SECONDS or TimeUnit.MILLISECONDS)

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

java5/common/java/code/org/opensplice/dds/pub/DataWriter.java

Public Member Functions

Detailed Description

Member Function Documentation

◆ assertLiveliness()

◆ cast()

◆ close()

◆ dispose() [1/4]

◆ dispose() [2/4]

◆ dispose() [3/4]

◆ dispose() [4/4]

◆ enable()

◆ getInstanceHandle()

◆ getKeyValue() [1/2]

◆ getKeyValue() [2/2]

◆ getListener()

◆ getLivelinessLostStatus()

◆ getMatchedSubscriptionData()

◆ getMatchedSubscriptions()

◆ getOfferedDeadlineMissedStatus()

◆ getOfferedIncompatibleQosStatus()

◆ getParent()

◆ getPublicationMatchedStatus()

◆ getQos()

◆ getStatusChanges()

◆ getStatusCondition()

◆ getTopic()

◆ lookupInstance()

◆ registerInstance() [1/3]

◆ registerInstance() [2/3]

◆ registerInstance() [3/3]

◆ retain()

◆ setListener() [1/3]

◆ setListener() [2/3]

◆ setListener() [3/3]

◆ setQos()

◆ unregisterInstance() [1/4]

◆ unregisterInstance() [2/4]

◆ unregisterInstance() [3/4]

◆ unregisterInstance() [4/4]

◆ waitForAcknowledgments() [1/2]

◆ waitForAcknowledgments() [2/2]

◆ write() [1/6]

◆ write() [2/6]

◆ write() [3/6]

◆ write() [4/6]

◆ write() [5/6]

◆ write() [6/6]

◆ writeDispose() [1/6]

◆ writeDispose() [2/6]

◆ writeDispose() [3/6]

◆ writeDispose() [4/6]

◆ writeDispose() [5/6]

◆ writeDispose() [6/6]