RTI Connext Java API  Version 5.0.0
PresentationQosPolicy Class Reference

Specifies how the samples representing changes to data instances are presented to a subscribing application. More...

Inheritance diagram for PresentationQosPolicy:
QosPolicy

Public Attributes

PresentationQosPolicyAccessScopeKind access_scope
 Determines the largest scope spanning the entities for which the order and coherency of changes can be preserved.
 
boolean coherent_access
 Specifies support for coherent access. Controls whether coherent access is supported within the scope access_scope.
 
boolean ordered_access
 Specifies support for ordered access to the samples received at the subscription end. Controls whether ordered access is supported within the scope access_scope.
 
- Public Attributes inherited from QosPolicy
final QosPolicyId_t id
 The ID of this QoS policy.
 
final String policy_name
 The name of this QoS policy.
 

Additional Inherited Members

- Public Member Functions inherited from Struct
abstract boolean equals (Object obj)
 
abstract int hashCode ()
 
String toString ()
 
- Protected Member Functions inherited from Struct
 Struct ()
 
abstract void pull_from_nativeI (long native_status)
 
abstract void push_to_nativeI (long native_status)
 

Detailed Description

Specifies how the samples representing changes to data instances are presented to a subscribing application.

This QoS policy controls the extent to which changes to data instances can be made dependent on each other and also the kind of dependencies that can be propagated and maintained by RTI Connext. Specifically, this policy affects the application's ability to:

  • specify and receive coherent changes to instances
  • specify the relative order in which changes are presented
Entity:
com.rti.dds.publication.Publisher, com.rti.dds.subscription.Subscriber
Status:
com.rti.dds.infrastructure.StatusKind.StatusKind.OFFERED_INCOMPATIBLE_QOS_STATUS, com.rti.dds.infrastructure.StatusKind.StatusKind.REQUESTED_INCOMPATIBLE_QOS_STATUS
Properties:
RxO = YES
Changeable = UNTIL ENABLE

Usage

A com.rti.dds.subscription.DataReader will usually receive data in the order that it was sent by a com.rti.dds.publication.DataWriter, and the data is presented to the com.rti.dds.subscription.DataReader as soon as the application receives the next expected value. However, sometimes, you may want a set of data for the same com.rti.dds.publication.DataWriter to be presented to the com.rti.dds.subscription.DataReader only after all of the elements of the set have been received. Or you may want the data to be presented in a different order than that in which it was received. Specifically for keyed data, you may want the middleware to present the data in keyed – or instance – order, such that samples pertaining to the same instance are presented together.

The Presentation QoS policy allows you to specify different scopes of presentation: within a com.rti.dds.publication.DataWriter, across instances of a single com.rti.dds.publication.DataWriter, and even across multiple DataWriters used by different writers of a publisher. It also controls whether or not a set of changes within the scope is delivered at the same time or can be delivered as soon as each element is received.

  • ordered_access controls whether RTI Connext will preserve the order of changes.
  • access_scope controls the granularity of the other settings. See below:

If coherent_access is set, then the access_scope controls the maximum extent of coherent changes. The behavior is as follows:

  • If access_scope is set to com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.GROUP_PRESENTATION_QOS, then coherent changes made to instances through a com.rti.dds.publication.DataWriter attached to a common com.rti.dds.publication.Publisher are made available as a unit to remote subscribers. (RTI does not currently support this access scope.)

If ordered_access is set, then the access_scope controls the maximum extent for which order will be preserved by RTI Connext.

  • If access_scope is set to com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.INSTANCE_PRESENTATION_QOS (the lowest level), then changes to each instance are considered unordered relative to changes to any other instance. That means that changes (creations, deletions, modifications) made to two instances are not necessarily seen in the order they occur. This is the case even if it is the same application thread making the changes using the same com.rti.dds.publication.DataWriter.
  • Finally, if access_scope is set to com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.GROUP_PRESENTATION_QOS, changes made to instances via com.rti.dds.publication.DataWriter entities attached to the same com.rti.dds.publication.Publisher object are made available to subscribers on the same order they occur.

Note that this QoS policy controls the scope at which related changes are made available to the subscriber. This means the subscriber can access the changes in a coherent manner and in the proper order; however, it does not necessarily imply that the com.rti.dds.subscription.Subscriber will indeed access the changes in the correct order. For that to occur, the application at the subscriber end must use the proper logic in reading the com.rti.dds.subscription.DataReader objects.

For com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.GROUP_PRESENTATION_QOS the subscribing application must use the APIs com.rti.dds.subscription.Subscriber.begin_access, com.rti.dds.subscription.Subscriber.end_access and com.rti.dds.subscription.Subscriber.get_datareaders to access the changes in the proper order.

Compatibility

The value offered is considered compatible with the value requested if and only if the following conditions are met:

  • the inequality offered access_scope >= requested access_scope evaluates to 'TRUE' or requested access_scope is com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.HIGHEST_OFFERED_PRESENTATION_QOS. For the purposes of this inequality, the values of access_scope are considered ordered such that com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.INSTANCE_PRESENTATION_QOS < com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.TOPIC_PRESENTATION_QOS < com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.GROUP_PRESENTATION_QOS.
  • requested coherent_access is com.rti.dds.infrastructure.false, or else both offered and requested coherent_access are com.rti.dds.infrastructure.true.
  • requested ordered_access is com.rti.dds.infrastructure.false, or else both offered and requested ordered_access are com.rti.dds.infrastructure.true.

Member Data Documentation

Determines the largest scope spanning the entities for which the order and coherency of changes can be preserved.

[default] com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.INSTANCE_PRESENTATION_QOS

boolean coherent_access

Specifies support for coherent access. Controls whether coherent access is supported within the scope access_scope.

That is, the ability to group a set of changes as a unit on the publishing end such that they are received as a unit at the subscribing end.

Note: To use this feature, the DataWriter must be configured for RELIABLE communication (see com.rti.dds.infrastructure.ReliabilityQosPolicyKind.ReliabilityQosPolicyKind.RELIABLE_RELIABILITY_QOS).

[default] com.rti.dds.infrastructure.false

boolean ordered_access

Specifies support for ordered access to the samples received at the subscription end. Controls whether ordered access is supported within the scope access_scope.

That is, the ability of the subscriber to see changes in the same order as they occurred on the publishing end.

[default] com.rti.dds.infrastructure.false


RTI Connext Java API Version 5.0.0 Copyright © Thu Aug 30 2012 Real-Time Innovations, Inc