org.omg.dds.pub

Interface DataWriter<TYPE>

Type Parameters:

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

All Superinterfaces:

AutoCloseable, Closeable, DDSObject, DomainEntity<DataWriterListener<TYPE>,DataWriterQos>, Entity<DataWriterListener<TYPE>,DataWriterQos>

public interface DataWriter<TYPE>
extends DomainEntity<DataWriterListener<TYPE>,DataWriterQos>

DataWriter allows the application to set the value of the data to be published under a given Topic. A DataWriter is attached to exactly one Publisher that acts as a factory for it. A DataWriter is bound to exactly one Topic and therefore to exactly one data type. The Topic must exist prior to the DataWriter's creation. All operations except for the inherited operations Entity.setQos(org.omg.dds.core.EntityQos), Entity.getQos(), Entity.setListener(java.util.EventListener),Entity.getListener(), Entity.enable(), getStatusCondition(), and Entity.close() may fail with the exception NotEnabledException.

Method Summary

Methods

Modifier and Type	Method and Description
void	assertLiveliness() This operation manually asserts the liveliness of the DataWriter.
<OTHER> DataWriter<OTHER>	cast() Cast this data writer to the given type, or throw an exception if the cast fails.
void	dispose(InstanceHandle instanceHandle) 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).
void	dispose(InstanceHandle instanceHandle, TYPE instanceData) 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).
void	dispose(InstanceHandle instanceHandle, TYPE instanceData, long sourceTimestamp, TimeUnit unit) 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 DataReader objects by means of Sample.getSourceTimestamp().
void	dispose(InstanceHandle instanceHandle, TYPE instanceData, Time sourceTimestamp) 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 DataReader objects by means of Sample.getSourceTimestamp().
TYPE	getKeyValue(InstanceHandle handle) This operation can be used to retrieve the instance key that corresponds to an instance handle.
TYPE	getKeyValue(TYPE keyHolder, InstanceHandle handle) This operation can be used to retrieve the instance key that corresponds to an instance handle.
LivelinessLostStatus	getLivelinessLostStatus() This operation allows access to the LIVELINESS_LOST communication status.
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 Topic and compatible QoS that the application has not indicated should be "ignored" by means of DomainParticipant.ignoreSubscription(InstanceHandle).
Set<InstanceHandle>	getMatchedSubscriptions() This operation retrieves the list of subscriptions currently "associated" with the DataWriter; that is, subscriptions that have a matching Topic and compatible QoS that the application has not indicated should be "ignored" by means of DomainParticipant.ignoreSubscription(InstanceHandle).
OfferedDeadlineMissedStatus	getOfferedDeadlineMissedStatus() This operation allows access to the OFFERED_DEADLINE_MISSED communication status.
OfferedIncompatibleQosStatus	getOfferedIncompatibleQosStatus() This operation allows access to the OFFERED_INCOMPATIBLE_QOS communication status.
Publisher	getParent()
PublicationMatchedStatus	getPublicationMatchedStatus() This operation allows access to the PUBLICATION_MATCHED communication status.
StatusCondition<DataWriter<TYPE>>	getStatusCondition() This operation allows access to the StatusCondition associated with the Entity.
Topic<TYPE>	getTopic()
ModifiableInstanceHandle	lookupInstance(ModifiableInstanceHandle handle, 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.
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.
InstanceHandle	registerInstance(TYPE instanceData) This operation informs the Service that the application will be modifying a particular instance.
InstanceHandle	registerInstance(TYPE instanceData, long sourceTimestamp, TimeUnit unit) 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.
InstanceHandle	registerInstance(TYPE instanceData, Time sourceTimestamp) 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.
void	unregisterInstance(InstanceHandle handle) This operation reverses the action of registerInstance(Object).
void	unregisterInstance(InstanceHandle handle, TYPE instanceData) This operation reverses the action of registerInstance(Object).
void	unregisterInstance(InstanceHandle handle, TYPE instanceData, long sourceTimestamp, TimeUnit unit) 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.
void	unregisterInstance(InstanceHandle handle, TYPE instanceData, Time sourceTimestamp) 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.
void	waitForAcknowledgments(Duration maxWait) This operation is intended to be used only if the DataWriter has Reliability.getKind() set to Reliability.Kind.RELIABLE.
void	waitForAcknowledgments(long maxWait, TimeUnit unit) This operation is intended to be used only if the DataWriter has Reliability.getKind() set to Reliability.Kind.RELIABLE.
void	write(TYPE instanceData) This operation modifies the value of a data instance.
void	write(TYPE instanceData, InstanceHandle handle) This operation modifies the value of a data instance.
void	write(TYPE instanceData, InstanceHandle handle, long sourceTimestamp, TimeUnit unit) 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 DataReader objects by means of Sample.getSourceTimestamp().
void	write(TYPE instanceData, InstanceHandle handle, Time sourceTimestamp) 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 DataReader objects by means of Sample.getSourceTimestamp().
void	write(TYPE instanceData, long sourceTimestamp, TimeUnit unit)
void	write(TYPE instanceData, Time sourceTimestamp)

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

cast

<OTHER> DataWriter<OTHER> cast()

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

Type Parameters:

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

Returns:

this data writer

Throws:

ClassCastException - if the cast fails

getTopic

Topic<TYPE> getTopic()

Returns:

the Topic associated with the DataWriter. This is the same Topic that was used to create the DataWriter.

waitForAcknowledgments

void waitForAcknowledgments(Duration maxWait)
                            throws TimeoutException

This operation is intended to be used only if the DataWriter has Reliability.getKind() set to 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 DataReader entities that have Reliability.getKind() set to 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.

Throws:

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

waitForAcknowledgments

void waitForAcknowledgments(long maxWait,
                          TimeUnit unit)
                            throws TimeoutException

This operation is intended to be used only if the DataWriter has Reliability.getKind() set to 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 DataReader entities that have Reliability.getKind() set to 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.

Throws:

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

getLivelinessLostStatus

LivelinessLostStatus getLivelinessLostStatus()

This operation allows access to the LIVELINESS_LOST communication status.

See Also:

org.omg.dds.core.status

getOfferedDeadlineMissedStatus

OfferedDeadlineMissedStatus getOfferedDeadlineMissedStatus()

This operation allows access to the OFFERED_DEADLINE_MISSED communication status.

See Also:

org.omg.dds.core.status

getOfferedIncompatibleQosStatus

OfferedIncompatibleQosStatus getOfferedIncompatibleQosStatus()

This operation allows access to the OFFERED_INCOMPATIBLE_QOS communication status.

See Also:

org.omg.dds.core.status

getPublicationMatchedStatus

PublicationMatchedStatus getPublicationMatchedStatus()

This operation allows access to the PUBLICATION_MATCHED communication status.

See Also:

org.omg.dds.core.status

assertLiveliness

void assertLiveliness()

This operation manually asserts the liveliness of the DataWriter. This is used in combination with the Liveliness to indicate to the Service that the entity remains active. This operation need only be used if Liveliness.getKind() is either Liveliness.Kind.MANUAL_BY_PARTICIPANT or 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.

getMatchedSubscriptions

Set<InstanceHandle> getMatchedSubscriptions()

This operation retrieves the list of subscriptions currently "associated" with the DataWriter; that is, subscriptions that have a matching Topic and compatible QoS that the application has not indicated should be "ignored" by means of 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 DataReader entities. These handles match the ones that appear in Sample.getInstanceHandle() when reading the "DCPSSubscriptions" built-in topic. The operation may fail if the infrastructure does not locally maintain the connectivity information.

Returns:

a new collection containing a copy of the information.

See Also:

getMatchedSubscriptionData(InstanceHandle)

getMatchedSubscriptionData

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 Topic and compatible QoS that the application has not indicated should be "ignored" by means of DomainParticipant.ignoreSubscription(InstanceHandle). The operation getMatchedSubscriptions() can be used to find the subscriptions that are currently matched with the DataWriter.

Parameters:

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

Returns:

a new object containing a copy of the information.

Throws:

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.

See Also:

getMatchedSubscriptions()

registerInstance

InstanceHandle registerInstance(TYPE instanceData)
                                throws TimeoutException

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.

Throws:

OutOfResourcesException - under the same circumstances described for write(Object).

TimeoutException - under the same circumstances described for write(Object).

See Also:

registerInstance(Object, Time), registerInstance(Object, long, TimeUnit), unregisterInstance(InstanceHandle), unregisterInstance(InstanceHandle, Object), InstanceHandle.nilHandle(org.omg.dds.core.ServiceEnvironment)

registerInstance

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. The source time stamp potentially affects the relative order in which readers observe events from multiple writers. For details see DestinationOrder. This operation may block and exit with TimeoutException under the same circumstances described for the write(Object).

Throws:

OutOfResourcesException - under the same circumstances described for write(Object).

TimeoutException - under the same circumstances described for write(Object).

See Also:

registerInstance(Object), registerInstance(Object, long, TimeUnit), unregisterInstance(InstanceHandle, Object, Time)

registerInstance

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. The source time stamp potentially affects the relative order in which readers observe events from multiple writers. For details see DestinationOrder. This operation may block and exit with TimeoutException under the same circumstances described for the write(Object).

Throws:

OutOfResourcesException - under the same circumstances described for write(Object).

TimeoutException - under the same circumstances described for write(Object).

See Also:

registerInstance(Object), registerInstance(Object, Time), unregisterInstance(InstanceHandle, Object, long, TimeUnit)

unregisterInstance

void unregisterInstance(InstanceHandle handle)
                        throws TimeoutException

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

Throws:

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

See Also:

unregisterInstance(InstanceHandle, Object), unregisterInstance(InstanceHandle, Object, Time), unregisterInstance(InstanceHandle, Object, long, TimeUnit), registerInstance(Object)

unregisterInstance

void unregisterInstance(InstanceHandle handle,
                      TYPE instanceData)
                        throws TimeoutException

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

Throws:

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.

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

See Also:

unregisterInstance(InstanceHandle), unregisterInstance(InstanceHandle, Object, Time), unregisterInstance(InstanceHandle, Object, long, TimeUnit), registerInstance(Object), InstanceHandle.nilHandle(org.omg.dds.core.ServiceEnvironment)

unregisterInstance

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. The source time stamp potentially affects the relative order in which readers observe events from multiple writers. For details see 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).

Throws:

TimeoutException

See Also:

unregisterInstance(InstanceHandle), unregisterInstance(InstanceHandle, Object), unregisterInstance(InstanceHandle, Object, long, TimeUnit), registerInstance(Object, Time)

unregisterInstance

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. The source time stamp potentially affects the relative order in which readers observe events from multiple writers. For details see 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).

Throws:

TimeoutException

See Also:

unregisterInstance(InstanceHandle), unregisterInstance(InstanceHandle, Object), unregisterInstance(InstanceHandle, Object, Time), registerInstance(Object, long, TimeUnit)

write

void write(TYPE instanceData)
           throws TimeoutException

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 DataReader objects by means of Sample.getSourceTimestamp(). See also DestinationOrder. As a side effect, this operation asserts liveliness on the DataWriter itself, the Publisher and the DomainParticipant. If Reliability.getKind() kind is set to 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 ResourceLimits to be exceeded. Under these circumstances, 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 History.getKind() is History.Kind.KEEP_LAST.

• If (ResourceLimits.getMaxSamples() < ResourceLimits.getMaxInstances() * 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 (ResourceLimits.getMaxSamples() < ResourceLimits.getMaxInstances()), then the DataWriter may block regardless of the HISTORY depth.

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

1. The reason for blocking would be that the RESOURCE_LIMITS are exceeded.
2. 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.

Throws:

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.

See Also:

write(Object, InstanceHandle), write(Object, InstanceHandle, Time), write(Object, InstanceHandle, long, TimeUnit)

write

void write(TYPE instanceData,
         Time sourceTimestamp)
           throws TimeoutException

Throws:

TimeoutException

write

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

Throws:

TimeoutException

write

void write(TYPE instanceData,
         InstanceHandle handle)
           throws TimeoutException

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 DataReader objects by means of Sample.getSourceTimestamp(). See also DestinationOrder. As a side effect, this operation asserts liveliness on the DataWriter itself, the Publisher and the 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 Reliability.getKind() kind is set to 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 ResourceLimits to be exceeded. Under these circumstances, 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 History.getKind() is History.Kind.KEEP_LAST.

• If (ResourceLimits.getMaxSamples() < ResourceLimits.getMaxInstances() * 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 (ResourceLimits.getMaxSamples() < ResourceLimits.getMaxInstances()), then the DataWriter may block regardless of the HISTORY depth.

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

1. The reason for blocking would be that the RESOURCE_LIMITS are exceeded.
2. 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.

Throws:

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.

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.

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.

See Also:

write(Object), write(Object, InstanceHandle, Time), write(Object, InstanceHandle, long, TimeUnit), InstanceHandle.nilHandle(org.omg.dds.core.ServiceEnvironment)

write

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 DataReader objects by means of Sample.getSourceTimestamp(). See also DestinationOrder. 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).

Throws:

IllegalArgumentException - under the same circumstances as write(Object, InstanceHandle).

PreconditionNotMetException - under the same circumstances as write(Object, InstanceHandle).

OutOfResourcesException - under the same circumstances as write(Object, InstanceHandle).

TimeoutException - under the same circumstances as write(Object, InstanceHandle).

See Also:

write(Object), write(Object, InstanceHandle), write(Object, InstanceHandle, long, TimeUnit)

write

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 DataReader objects by means of Sample.getSourceTimestamp(). See also DestinationOrder. 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).

Throws:

IllegalArgumentException - under the same circumstances as write(Object, InstanceHandle).

PreconditionNotMetException - under the same circumstances as write(Object, InstanceHandle).

OutOfResourcesException - under the same circumstances as write(Object, InstanceHandle).

TimeoutException - under the same circumstances as write(Object, InstanceHandle).

See Also:

write(Object), write(Object, InstanceHandle), write(Object, InstanceHandle, Time)

dispose

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). In general, applications are made aware of the deletion by means of operations on the 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 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).

Throws:

OutOfResourcesException - under the same circumstances as write(Object).

TimeoutException - under the same circumstances as write(Object).

See Also:

dispose(InstanceHandle, Object), dispose(InstanceHandle, Object, Time), dispose(InstanceHandle, Object, long, TimeUnit)

dispose

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). In general, applications are made aware of the deletion by means of operations on the 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 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).

Throws:

OutOfResourcesException - under the same circumstances as write(Object, InstanceHandle).

TimeoutException - under the same circumstances as write(Object, InstanceHandle).

See Also:

dispose(InstanceHandle), dispose(InstanceHandle, Object, Time), dispose(InstanceHandle, Object, long, TimeUnit)

dispose

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 DataReader objects by means of 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).

Throws:

IllegalArgumentException - under the same circumstances as dispose(InstanceHandle, Object).

PreconditionNotMetException - under the same circumstances as dispose(InstanceHandle, Object).

OutOfResourcesException - under the same circumstances as write(Object, InstanceHandle).

TimeoutException - under the same circumstances as write(Object, InstanceHandle).

See Also:

dispose(InstanceHandle), dispose(InstanceHandle, Object), dispose(InstanceHandle, Object, long, TimeUnit)

dispose

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 DataReader objects by means of 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).

Throws:

IllegalArgumentException - under the same circumstances as dispose(InstanceHandle, Object).

PreconditionNotMetException - under the same circumstances as dispose(InstanceHandle, Object).

OutOfResourcesException - under the same circumstances as write(Object, InstanceHandle).

TimeoutException - under the same circumstances as write(Object, InstanceHandle).

See Also:

dispose(InstanceHandle), dispose(InstanceHandle, Object), dispose(InstanceHandle, Object, Time)

getKeyValue

TYPE getKeyValue(TYPE keyHolder,
               InstanceHandle handle)

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.

Throws:

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.

See Also:

getKeyValue(InstanceHandle)

getKeyValue

TYPE getKeyValue(InstanceHandle handle)

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.

Throws:

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.

See Also:

getKeyValue(Object, InstanceHandle)

lookupInstance

ModifiableInstanceHandle lookupInstance(ModifiableInstanceHandle handle,
                                      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. 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:

handle - a container, into which this method shall place its result.

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

Returns:

handle, if it is non-null, or a new object otherwise.

See Also:

lookupInstance(Object)

lookupInstance

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

See Also:

lookupInstance(ModifiableInstanceHandle, Object)

getStatusCondition

StatusCondition<DataWriter<TYPE>> 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<DataWriterListener<TYPE>,DataWriterQos>

getParent

Publisher getParent()

Specified by:

getParent in interface DomainEntity<DataWriterListener<TYPE>,DataWriterQos>

Returns:

the factory object that created this entity.