org.omg.dds.sub

Interface Sample<TYPE>

Type Parameters:

TYPE - The concrete type of the data encapsulated by this Sample.

All Superinterfaces:

Cloneable, DDSObject, Serializable

public interface Sample<TYPE>
extends Cloneable, Serializable, DDSObject

A Sample represents an atom of data information (i.e., one value for one instance) as returned by a DataReader's read or take operations. It consists of two parts: the Data (getData()) and the "Sample Info" (the remainder of the methods defined by this interface). Interpretation of the Sample Info In addition to the data value itself, the Sample contains information pertaining to it:

• The sampleState (getSampleState()) of the Data value (i.e., if the sample has already been SampleState.READ or SampleState.NOT_READ by that same DataReader).
• The viewState (getViewState()) of the related instance (i.e., if the current generation of the instance is ViewState.NEW or ViewState.NOT_NEW for that DataReader).
• The instanceState (getInstanceState()) of the related instance (i.e., if the instance is InstanceState.ALIVE, InstanceState.NOT_ALIVE_DISPOSED, or InstanceState.NOT_ALIVE_NO_WRITERS).
• The "valid data" flag, corresponding to whether getData() return a non-null value. Some samples do not contain data, instead indicating only a change on the instanceState of the corresponding instance.
• The values of disposedGenerationCount (getDisposedGenerationCount()) and noWritersGenerationCount (getNoWritersGenerationCount()) for the related instance at the time the sample was received. These counters indicate the number of times the instance had become ALIVE (with instanceState = InstanceState.ALIVE) at the time the sample was received.
• The sampleRank (getSampleRank()) and generationRank (getGenerationRank()) of the sample within the returned sequence. These ranks provide a preview of the samples that follow within the sequence returned by the DataReader.read() or DataReader.take() operations.
• The absoluteGenerationRank (getAbsoluteGenerationRank()) of the sample within the DataReader. This rank provides a preview of what is available within the DataReader.
• The sourceTimestamp (getSourceTimestamp()) of the sample. This is the time stamp provided by the DataWriter at the time the sample was produced.
• The instanceHandle (getInstanceHandle()) that identifies locally the corresponding instance.
• The publicationHandle (getPublicationHandle()) that identifies locally the DataWriter that modified the instance. The publicationHandle is the same InstanceHandle that is returned by the operation DataReader.getMatchedPublications() on the DataReader and can also be used as a parameter to the operation DataReader.getMatchedPublicationData(InstanceHandle).

Interpretation of the Counters and Ranks A Sample provides several counters and ranks: the disposedGenerationCount (getDisposedGenerationCount()), noWritersGenerationCount (getNoWritersGenerationCount()), sampleRank (getSampleRank()), generationRank (getGenerationRank()), and absoluteGenerationRank (getAbsoluteGenerationRank()). These counters and ranks allow the application to distinguish samples belonging to different 'generations' of the instance. Note that it is possible for an instance to transition from not-alive to alive (and back) several times before the application accesses the data by means of DataReader.read() or DataReader.take(). In this case the returned collection may contain samples that cross generations (i.e., some samples were received before the instance became not-alive, others after the instance reappeared again). Using the information in the Sample the application can anticipate what other information regarding the same instance appears in the returned collection as well as in the infrastructure and thus make appropriate decisions. For example, an application desiring to only consider the most current sample for each instance would only look at samples with sampleRank == 0. Similarly an application desiring to only consider samples that correspond to the latest generation in the collection will only look at samples with generationRank == 0. An application desiring only samples pertaining to the latest generation available will ignore samples for which absoluteGenerationRank != 0. Other application-defined criteria may also be used.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Sample.Iterator<IT_DATA>

Method Summary

Methods

Modifier and Type	Method and Description
Sample<TYPE>	clone()
int	getAbsoluteGenerationRank() The sampleRank and generationRank available in the Sample are computed based solely on the actual samples in the ordered collection returned by DataReader.read() or DataReader.take().
TYPE	getData() Get the data associated with this Sample, if any.
int	getDisposedGenerationCount() For each instance the middleware internally maintains two counts: the disposedGenerationCount and noWritersGenerationCount, relative to each DataReader: The disposedGenerationCount and noWritersGenerationCount are initialized to zero when the DataReader first detects the presence of a never-seen-before instance.
int	getGenerationRank() The sampleRank and generationRank available in the Sample are computed based solely on the actual samples in the ordered collection returned by DataReader.read() or DataReader.take().
ModifiableInstanceHandle	getInstanceHandle()
InstanceState	getInstanceState() For each instance the middleware internally maintains an instanceState.
int	getNoWritersGenerationCount() For each instance the middleware internally maintains two counts: the disposedGenerationCount and noWritersGenerationCount, relative to each DataReader: The disposedGenerationCount and noWritersGenerationCount are initialized to zero when the DataReader first detects the presence of a never-seen-before instance.
ModifiableInstanceHandle	getPublicationHandle()
int	getSampleRank() The sampleRank and generationRank available in the Sample are computed based solely on the actual samples in the ordered collection returned by DataReader.read() or DataReader.take().
SampleState	getSampleState() For each sample received, the middleware internally maintains a sampleState relative to each DataReader.
Time	getSourceTimestamp()
ViewState	getViewState() For each instance (identified by the key), the middleware internally maintains a viewState relative to each DataReader.

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

getEnvironment

Method Detail

getData

TYPE getData()

Get the data associated with this Sample, if any. Normally each Sample contains both meta-data ("Sample Info") and some data. However there are situations where a Sample contains only the Sample Info and does not have any associated data. This occurs when the Service notifies the application of a change of state for an instance that was caused by some internal mechanism (such as a timeout) for which there is no associated data. An example of this situation is when the Service detects that an instance has no writers and changes the corresponding instanceState to InstanceState.NOT_ALIVE_NO_WRITERS. The actual set of scenarios under which the middleware returns Samples containing no data is implementation dependent. The application can distinguish whether a particular Sample has data by examining the value returned by this method. If the result is not null, then the Sample contains valid data. If it is null, the Sample contains no data. To ensure correctness and portability, the application must check for a null result from this method prior to using it. If the data is null, the application should access only the Sample Info.

Returns:

the data associated with this sample. This method will return null if this sample contains no valid data.

getSampleState

SampleState getSampleState()

For each sample received, the middleware internally maintains a sampleState relative to each DataReader. The sampleState can either be SampleState.READ or SampleState.NOT_READ.

• READ indicates that the DataReader has already accessed that sample by means of DataReader.read(). (Had the sample been accessed by DataReader.take(), it would no longer be available to the DataReader.)
• NOT_READ indicates that the DataReader has not accessed that sample before.

The sampleState will, in general, be different for each sample in the collection returned by DataReader.read() or DataReader.take().

getViewState

ViewState getViewState()

For each instance (identified by the key), the middleware internally maintains a viewState relative to each DataReader. The viewState can either be ViewState.NEW or ViewState.NOT_NEW.

• NEW indicates that either this is the first time that the DataReader has ever accessed samples of that instance, or else that the DataReader has accessed previous samples of the instance, but the instance has since been reborn (i.e., become not-alive and then alive again). These two cases are distinguished by examining the disposedGenerationCount and the noWritersGenerationCount.
• NOT_NEW indicates that the DataReader has already accessed samples of the same instance and that the instance has not been reborn since.

The viewState available in the Sample is a snapshot of the viewState of the instance relative to the DataReader used to access the samples at the time the collection was obtained (i.e., at the time DataReader.read() or DataReader.take() was called). The viewState is therefore the same for all samples in the returned collection that refer to the same instance.

See Also:

getDisposedGenerationCount(), getNoWritersGenerationCount()

getInstanceState

InstanceState getInstanceState()

For each instance the middleware internally maintains an instanceState. The instanceState can be InstanceState.ALIVE, InstanceState.NOT_ALIVE_DISPOSED, or InstanceState.NOT_ALIVE_NO_WRITERS.

• ALIVE indicates that (a) samples have been received for the instance, (b) there are live DataWriter entities writing the instance, and (c) the instance has not been explicitly disposed (or else more samples have been received after it was disposed).
• NOT_ALIVE_DISPOSED indicates the instance was explicitly disposed by a DataWriter by means of DataWriter.dispose(InstanceHandle).
• NOT_ALIVE_NO_WRITERS indicates the instance has been declared as not-alive by the DataReader because it detected that there are no live DataWriter entities writing that instance.

The precise behavior events that cause the instanceState to change depends on the setting of the Ownership:

• If Ownership.getKind() is Ownership.Kind.EXCLUSIVE, then the instanceState becomes NOT_ALIVE_DISPOSED only if the DataWriter that "owns" the instance explicitly disposes it. The instanceState becomes ALIVE again only if the DataWriter that owns the instance writes it.
• If Ownership.getKind() is Ownership.Kind.SHARED, then the instanceState becomes NOT_ALIVE_DISPOSED if any DataWriter explicitly disposes the instance. The instanceState becomes ALIVE as soon as any DataWriter writes the instance again.

The instanceState available in the Sample is a snapshot of the instanceState of the instance at the time the collection was obtained (i.e., at the time DataReader.read() or DataReader.take() was called). The instanceState is therefore the same for all samples in the returned collection that refer to the same instance.

getSourceTimestamp

Time getSourceTimestamp()

getInstanceHandle

ModifiableInstanceHandle getInstanceHandle()

getPublicationHandle

ModifiableInstanceHandle getPublicationHandle()

getDisposedGenerationCount

int getDisposedGenerationCount()

For each instance the middleware internally maintains two counts: the disposedGenerationCount and noWritersGenerationCount, relative to each DataReader:

• The disposedGenerationCount and noWritersGenerationCount are initialized to zero when the DataReader first detects the presence of a never-seen-before instance.
• The disposedGenerationCount is incremented each time the instanceState of the corresponding instance changes from NOT_ALIVE_DISPOSED to ALIVE.
• The noWritersGenerationCount is incremented each time the instanceState of the corresponding instance changes from NOT_ALIVE_NO_WRITERS to ALIVE.

The disposedGenerationCount and noWritersGenerationCount available in the Sample capture a snapshot of the corresponding counters at the time the sample was received.

See Also:

getNoWritersGenerationCount()

getNoWritersGenerationCount

int getNoWritersGenerationCount()

For each instance the middleware internally maintains two counts: the disposedGenerationCount and noWritersGenerationCount, relative to each DataReader:

• The disposedGenerationCount and noWritersGenerationCount are initialized to zero when the DataReader first detects the presence of a never-seen-before instance.
• The disposedGenerationCount is incremented each time the instanceState of the corresponding instance changes from NOT_ALIVE_DISPOSED to ALIVE.
• The noWritersGenerationCount is incremented each time the instanceState of the corresponding instance changes from NOT_ALIVE_NO_WRITERS to ALIVE.

The disposedGenerationCount and noWritersGenerationCount available in the Sample capture a snapshot of the corresponding counters at the time the sample was received.

See Also:

getDisposedGenerationCount()

getSampleRank

int getSampleRank()

The sampleRank and generationRank available in the Sample are computed based solely on the actual samples in the ordered collection returned by DataReader.read() or DataReader.take().

• The sampleRank indicates the number of samples of the same instance that follow the current one in the collection.
• The generationRank available in the Sample indicates the difference in 'generations' between the sample (S) and the Most Recent Sample of the same instance that appears In the returned Collection (MRSIC). That is, it counts the number of times the instance transitioned from not-alive to alive in the time from the reception of S to the reception of MRSIC.

See Also:

getAbsoluteGenerationRank(), getGenerationRank()

getGenerationRank

int getGenerationRank()

The sampleRank and generationRank available in the Sample are computed based solely on the actual samples in the ordered collection returned by DataReader.read() or DataReader.take().

• The sampleRank indicates the number of samples of the same instance that follow the current one in the collection.
• The generationRank available in the Sample indicates the difference in 'generations' between the sample (S) and the Most Recent Sample of the same instance that appears In the returned Collection (MRSIC). That is, it counts the number of times the instance transitioned from not-alive to alive in the time from the reception of S to the reception of MRSIC.

The generationRank is computed using the formula: generationRank = (MRSIC.disposedGenerationCount + MRSIC.noWritersGenerationCount) - (S.disposedGenerationCount + S.noWritersGenerationCount)

See Also:

getAbsoluteGenerationRank(), getSampleRank()

getAbsoluteGenerationRank

int getAbsoluteGenerationRank()

The sampleRank and generationRank available in the Sample are computed based solely on the actual samples in the ordered collection returned by DataReader.read() or DataReader.take().

• The sampleRank indicates the number of samples of the same instance that follow the current one in the collection.
• The generationRank available in the Sample indicates the difference in 'generations' between the sample (S) and the Most Recent Sample of the same instance that appears In the returned Collection (MRSIC). That is, it counts the number of times the instance transitioned from not-alive to alive in the time from the reception of S to the reception of MRSIC.

The absoluteGenerationRank available in the Sample indicates the difference in 'generations' between the sample (S) and the Most Recent Sample of the same instance that the middleware has received (MRS). That is, it counts the number of times the instance transitioned from not-alive to alive in the time from the reception of S to the time when DataReader.read() or DataReader.take() was called. absoluteGenerationRank = (MRS.disposedGenerationCount + MRS.noWritersGenerationCount) - (S.disposedGenerationCount + S.noWritersGenerationCount)

See Also:

getGenerationRank(), getSampleRank()

clone

Sample<TYPE> clone()