A Sample represents an atom of data information (i.e., one value for one instance) as returned by a org.omg.dds.sub.DataReader's read or take operations. More...

Inheritance diagram for org.omg.dds.sub.Sample< TYPE >:

Collaboration diagram for org.omg.dds.sub.Sample< TYPE >:

Classes
interface	Iterator

Public Member Functions
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 org.omg.dds.sub.DataReader#read() or org.omg.dds.sub.DataReader#take(). More...

TYPE	getData ()
	Get the data associated with this Sample, if any. More...

int	getDisposedGenerationCount ()
	For each instance the middleware internally maintains two counts: the disposedGenerationCount and noWritersGenerationCount, relative to each org.omg.dds.sub.DataReader: More...

ServiceEnvironment	getEnvironment ()

int	getGenerationRank ()
	The sampleRank and generationRank available in the Sample are computed based solely on the actual samples in the ordered collection returned by org.omg.dds.sub.DataReader#read() or org.omg.dds.sub.DataReader#take(). More...

InstanceHandle	getInstanceHandle ()
	Gets the InstanceHandle of the associated data Sample. More...

InstanceState	getInstanceState ()
	For each instance the middleware internally maintains an instanceState. More...

int	getNoWritersGenerationCount ()
	For each instance the middleware internally maintains two counts: the disposedGenerationCount and noWritersGenerationCount, relative to each org.omg.dds.sub.DataReader: More...

InstanceHandle	getPublicationHandle ()
	Gets the InstanceHandle of the associated publication. More...

int	getSampleRank ()
	The sampleRank and generationRank available in the Sample are computed based solely on the actual samples in the ordered collection returned by org.omg.dds.sub.DataReader#read() or org.omg.dds.sub.DataReader#take(). More...

SampleState	getSampleState ()
	For each sample received, the middleware internally maintains a sampleState relative to each org.omg.dds.sub.DataReader. More...

Time	getSourceTimestamp ()
	Gets the timestamp of the sample. More...

ViewState	getViewState ()
	For each instance (identified by the key), the middleware internally maintains a viewState relative to each org.omg.dds.sub.DataReader More...

Detailed Description

A Sample represents an atom of data information (i.e., one value for one instance) as returned by a org.omg.dds.sub.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 org.omg.dds.sub.SampleState#READ or org.omg.dds.sub.SampleState#NOT_READ by that same org.omg.dds.sub.DataReader).
The viewState (getViewState()) of the related instance (i.e., if the current generation of the instance is org.omg.dds.sub.ViewState#NEW or org.omg.dds.sub.ViewState#NOT_NEW for that DataReader).
The instanceState (getInstanceState()) of the related instance (i.e., if the instance is org.omg.dds.sub.InstanceState#ALIVE, org.omg.dds.sub.InstanceState#NOT_ALIVE_DISPOSED, or org.omg.dds.sub.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 = org.omg.dds.sub.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 org.omg.dds.sub.DataReader#read() or org.omg.dds.sub.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 org.omg.dds.pub.DataWriter at the time the sample was produced.
The instanceHandle (getInstanceHandle()) that identifies locally the corresponding instance.
The publicationHandle (getPublicationHandle()) that identifies locally the org.omg.dds.pub.DataWriter that modified the instance. The publicationHandle is the same org.omg.dds.core.InstanceHandle that is returned by the operation org.omg.dds.sub.DataReader#getMatchedPublications() on the DataReader and can also be used as a parameter to the operation org.omg.dds.sub.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 org.omg.dds.sub.DataReader#read() or org.omg.dds.sub.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.

Parameters

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

Definition at line 116 of file Sample.java.

Member Function Documentation

◆ clone()

Sample<TYPE> org.omg.dds.sub.Sample< TYPE >.clone ( )

Implemented in org.opensplice.dds.sub.SampleImpl< TYPE >.

◆ getAbsoluteGenerationRank()

int org.omg.dds.sub.Sample< TYPE >.getAbsoluteGenerationRank ( )

The sampleRank and generationRank available in the Sample are computed based solely on the actual samples in the ordered collection returned by org.omg.dds.sub.DataReader#read() or org.omg.dds.sub.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 org.omg.dds.sub.DataReader#read() or org.omg.dds.sub.DataReader#take() was called.

absoluteGenerationRank = (MRS.disposedGenerationCount


MRS.noWritersGenerationCount)
(S.disposedGenerationCount
S.noWritersGenerationCount)  Returns
the absolute generation rank 
See also
getGenerationRank() 

getSampleRank()

Implemented in org.opensplice.dds.sub.SampleImpl< TYPE >.

◆ getData()

TYPE org.omg.dds.sub.Sample< 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 org.omg.dds.sub.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.

Implemented in org.opensplice.dds.sub.SampleImpl< TYPE >.

◆ getDisposedGenerationCount()

int org.omg.dds.sub.Sample< TYPE >.getDisposedGenerationCount ( )

For each instance the middleware internally maintains two counts: the disposedGenerationCount and noWritersGenerationCount, relative to each org.omg.dds.sub.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.

Returns: the disposed generation count

See also: getNoWritersGenerationCount()

Implemented in org.opensplice.dds.sub.SampleImpl< TYPE >.

◆ getEnvironment()

ServiceEnvironment org.omg.dds.core.DDSObject.getEnvironment ( )

inherited

Returns: the org.omg.dds.core.ServiceEnvironment object that directly or indirectly was used to create this object.

◆ getGenerationRank()

int org.omg.dds.sub.Sample< TYPE >.getGenerationRank ( )

The sampleRank and generationRank available in the Sample are computed based solely on the actual samples in the ordered collection returned by org.omg.dds.sub.DataReader#read() or org.omg.dds.sub.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)  Returns
the generation rank 
See also
getAbsoluteGenerationRank() 

getSampleRank()

Implemented in org.opensplice.dds.sub.SampleImpl< TYPE >.

◆ getInstanceHandle()

InstanceHandle org.omg.dds.sub.Sample< TYPE >.getInstanceHandle ( )

Gets the InstanceHandle of the associated data Sample.

Returns: the InstanceHandle of the sample

Implemented in org.opensplice.dds.sub.SampleImpl< TYPE >.

◆ getInstanceState()

InstanceState org.omg.dds.sub.Sample< TYPE >.getInstanceState ( )

For each instance the middleware internally maintains an instanceState.

The instanceState can be org.omg.dds.sub.InstanceState#ALIVE, org.omg.dds.sub.InstanceState#NOT_ALIVE_DISPOSED, or org.omg.dds.sub.InstanceState#NOT_ALIVE_NO_WRITERS.

ALIVE indicates that (a) samples have been received for the instance, (b) there are live org.omg.dds.pub.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 org.omg.dds.pub.DataWriter#dispose(InstanceHandle).
NOT_ALIVE_NO_WRITERS indicates the instance has been declared as not-alive by the org.omg.dds.sub.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 org.omg.dds.core.policy.Ownership:

If org.omg.dds.core.policy.Ownership#getKind() is org.omg.dds.core.policy.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 org.omg.dds.core.policy.Ownership#getKind() is org.omg.dds.core.policy.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 org.omg.dds.sub.DataReader#read() or org.omg.dds.sub.DataReader#take() was called). The instanceState is therefore the same for all samples in the returned collection that refer to the same instance.

Returns: the InstanceState

Implemented in org.opensplice.dds.sub.SampleImpl< TYPE >.

◆ getNoWritersGenerationCount()

int org.omg.dds.sub.Sample< TYPE >.getNoWritersGenerationCount ( )

For each instance the middleware internally maintains two counts: the disposedGenerationCount and noWritersGenerationCount, relative to each org.omg.dds.sub.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.

Returns: the no writers generation count

See also: getDisposedGenerationCount()

Implemented in org.opensplice.dds.sub.SampleImpl< TYPE >.

◆ getPublicationHandle()

InstanceHandle org.omg.dds.sub.Sample< TYPE >.getPublicationHandle ( )

Gets the InstanceHandle of the associated publication.

Returns: the PublicationHandle

Implemented in org.opensplice.dds.sub.SampleImpl< TYPE >.

◆ getSampleRank()

int org.omg.dds.sub.Sample< TYPE >.getSampleRank ( )

The sampleRank and generationRank available in the Sample are computed based solely on the actual samples in the ordered collection returned by org.omg.dds.sub.DataReader#read() or org.omg.dds.sub.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.

Returns: the sample rank

See also: getAbsoluteGenerationRank(); getGenerationRank()

Implemented in org.opensplice.dds.sub.SampleImpl< TYPE >.

◆ getSampleState()

SampleState org.omg.dds.sub.Sample< TYPE >.getSampleState ( )

For each sample received, the middleware internally maintains a sampleState relative to each org.omg.dds.sub.DataReader.

The sampleState can either be org.omg.dds.sub.SampleState#READ or org.omg.dds.sub.SampleState#NOT_READ.

READ indicates that the DataReader has already accessed that sample by means of org.omg.dds.sub.DataReader#read(). (Had the sample been accessed by org.omg.dds.sub.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 org.omg.dds.sub.DataReader#read() or org.omg.dds.sub.DataReader#take().

Returns: the SampleState

Implemented in org.opensplice.dds.sub.SampleImpl< TYPE >.

◆ getSourceTimestamp()

Time org.omg.dds.sub.Sample< TYPE >.getSourceTimestamp ( )

Gets the timestamp of the sample.

This is the timestamp provided by the DataWriter at the time the sample was produced.

Returns: the timestamp

Implemented in org.opensplice.dds.sub.SampleImpl< TYPE >.

◆ getViewState()

ViewState org.omg.dds.sub.Sample< TYPE >.getViewState ( )

For each instance (identified by the key), the middleware internally maintains a viewState relative to each org.omg.dds.sub.DataReader

The viewState can either be org.omg.dds.sub.ViewState#NEW or org.omg.dds.sub.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 org.omg.dds.sub.DataReader#read() or org.omg.dds.sub.DataReader#take() was called). The viewState is therefore the same for all samples in the returned collection that refer to the same instance.

Returns: the ViewState

See also: getDisposedGenerationCount(); getNoWritersGenerationCount()

Implemented in org.opensplice.dds.sub.SampleImpl< TYPE >.

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

java5/common/java/code/org/omg/dds/sub/Sample.java

Classes

Public Member Functions

Detailed Description

Member Function Documentation

◆ clone()

◆ getAbsoluteGenerationRank()

◆ getData()

◆ getDisposedGenerationCount()

◆ getEnvironment()

◆ getGenerationRank()

◆ getInstanceHandle()

◆ getInstanceState()

◆ getNoWritersGenerationCount()

◆ getPublicationHandle()

◆ getSampleRank()

◆ getSampleState()

◆ getSourceTimestamp()

◆ getViewState()