RTI Connext Java API  Version 5.0.0
DurabilityQosPolicy Class Reference

This QoS policy specifies whether or not RTI Connext will store and deliver previously published data samples to new com.rti.dds.subscription.DataReader entities that join the network later. More...

Inheritance diagram for DurabilityQosPolicy:
QosPolicy

Public Attributes

DurabilityQosPolicyKind kind
 The kind of durability.
 
boolean direct_communication
 <<eXtension>> Indicates whether or not a TRANSIENT or PERSISTENT com.rti.dds.subscription.DataReader should receive samples directly from a TRANSIENT or PERSISTENT com.rti.dds.publication.DataWriter
 
- 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

This QoS policy specifies whether or not RTI Connext will store and deliver previously published data samples to new com.rti.dds.subscription.DataReader entities that join the network later.

Entity:
com.rti.dds.topic.Topic, com.rti.dds.subscription.DataReader, com.rti.dds.publication.DataWriter
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
See Also
DURABILITY_SERVICE

Usage

It is possible for a com.rti.dds.publication.DataWriter to start publishing data before all (or any) com.rti.dds.subscription.DataReader entities have joined the network.

Moreover, a com.rti.dds.subscription.DataReader that joins the network after some data has been written could potentially be interested in accessing the most current values of the data, as well as potentially some history.

This policy makes it possible for a late-joining com.rti.dds.subscription.DataReader to obtain previously published samples.

By helping to ensure that DataReaders get all data that was sent by DataWriters, regardless of when it was sent, using this QoS policy can increase system tolerance to failure conditions.

Note that although related, this does not strictly control what data RTI Connext will maintain internally. That is, RTI Connext may choose to maintain some data for its own purposes (e.g., flow control) and yet not make it available to late-joining readers if the DURABILITY policy is set to com.rti.dds.infrastructure.DurabilityQosPolicyKind.DurabilityQosPolicyKind.VOLATILE_DURABILITY_QOS.

Transient and Persistent Durability

For the purpose of implementing the DURABILITY QoS kind TRANSIENT or PERSISTENT, RTI Connext behaves as if for each Topic that has com.rti.dds.infrastructure.DurabilityQosPolicy.kind of com.rti.dds.infrastructure.DurabilityQosPolicyKind.DurabilityQosPolicyKind.TRANSIENT_DURABILITY_QOS or com.rti.dds.infrastructure.DurabilityQosPolicyKind.DurabilityQosPolicyKind.PERSISTENT_DURABILITY_QOS there is a corresponding "built-in" com.rti.dds.subscription.DataReader and com.rti.dds.publication.DataWriter configured with the same DURABILITY kind. In other words, it is as if somewhere in the system, independent of the original com.rti.dds.publication.DataWriter, there is a built-in durable com.rti.dds.subscription.DataReader subscribing to that Topic and a built-in durable DataWriter re-publishing it as needed for the new subscribers that join the system. This functionality is provided by the RTI Persistence Service.

The Persistence Service can configure itself based on the QoS of your application's com.rti.dds.publication.DataWriter and com.rti.dds.subscription.DataReader entities. For each transient or persistent com.rti.dds.topic.Topic, the built-in fictitious Persistence Service com.rti.dds.subscription.DataReader and com.rti.dds.publication.DataWriter have their QoS configured from the QoS of your application's com.rti.dds.publication.DataWriter and com.rti.dds.subscription.DataReader entities that communicate on that com.rti.dds.topic.Topic.

For a given com.rti.dds.topic.Topic, the usual request/offered semantics apply to the matching between any com.rti.dds.publication.DataWriter in the domain that writes the com.rti.dds.topic.Topic and the built-in transient/persistent com.rti.dds.subscription.DataReader for that com.rti.dds.topic.Topic; similarly for the built-in transient/persistent com.rti.dds.publication.DataWriter for a com.rti.dds.topic.Topic and any com.rti.dds.subscription.DataReader for the com.rti.dds.topic.Topic. As a consequence, a com.rti.dds.publication.DataWriter that has an incompatible QoS will not send its data to the RTI Persistence Service, and a com.rti.dds.subscription.DataReader that has an incompatible QoS will not get data from it.

Incompatibilities between local com.rti.dds.subscription.DataReader and com.rti.dds.publication.DataWriter entities and the corresponding fictitious built-in transient/persistent entities cause the com.rti.dds.infrastructure.StatusKind.StatusKind.REQUESTED_INCOMPATIBLE_QOS_STATUS and com.rti.dds.infrastructure.StatusKind.StatusKind.OFFERED_INCOMPATIBLE_QOS_STATUS to change and the corresponding Listener invocations and/or signaling of com.rti.dds.infrastructure.Condition objects as they would with your application's own entities.

The value of com.rti.dds.infrastructure.DurabilityServiceQosPolicy.service_cleanup_delay controls when RTI Persistence Service is able to remove all information regarding a data instances.

Information on a data instance is maintained until the following conditions are met:

1. The instance has been explicitly disposed (instance_state = NOT_ALIVE_DISPOSED),

and

2. While in the NOT_ALIVE_DISPOSED state, the system detects that there are no more 'live' com.rti.dds.publication.DataWriter entities writing the instance. That is, all existing writers either unregister the instance (call unregister) or lose their liveliness,

and

3. A time interval longer that com.rti.dds.infrastructure.DurabilityServiceQosPolicy.service_cleanup_delay has elapsed since the moment RTI Connext detected that the previous two conditions were met.

The utility of com.rti.dds.infrastructure.DurabilityServiceQosPolicy.service_cleanup_delay is apparent in the situation where an application disposes an instance and it crashes before it has a chance to complete additional tasks related to the disposition. Upon restart, the application may ask for initial data to regain its state and the delay introduced by the service_cleanup_delay will allow the restarted application to receive the information on the disposed instance and complete the interrupted tasks.

Compatibility

The value offered is considered compatible with the value requested if and only if the inequality offered kind >= requested kind evaluates to 'TRUE'. For the purposes of this inequality, the values of DURABILITY kind are considered ordered such that com.rti.dds.infrastructure.DurabilityQosPolicyKind.DurabilityQosPolicyKind.VOLATILE_DURABILITY_QOS < com.rti.dds.infrastructure.DurabilityQosPolicyKind.DurabilityQosPolicyKind.TRANSIENT_LOCAL_DURABILITY_QOS < com.rti.dds.infrastructure.DurabilityQosPolicyKind.DurabilityQosPolicyKind.TRANSIENT_DURABILITY_QOS < com.rti.dds.infrastructure.DurabilityQosPolicyKind.DurabilityQosPolicyKind.PERSISTENT_DURABILITY_QOS.

Member Data Documentation

The kind of durability.

[default] com.rti.dds.infrastructure.DurabilityQosPolicyKind.DurabilityQosPolicyKind.VOLATILE_DURABILITY_QOS

boolean direct_communication

<<eXtension>> Indicates whether or not a TRANSIENT or PERSISTENT com.rti.dds.subscription.DataReader should receive samples directly from a TRANSIENT or PERSISTENT com.rti.dds.publication.DataWriter

When direct_communication is set to com.rti.dds.infrastructure.true, a TRANSIENT or PERSISTENT com.rti.dds.subscription.DataReader will receive samples from both the original com.rti.dds.publication.DataWriter configured with TRANSIENT or PERSISTENT durability and the com.rti.dds.publication.DataWriter created by the persistence service. This peer-to-peer communication pattern provides low latency between end-points.

If the same sample is received from the original com.rti.dds.publication.DataWriter and the persistence service, the middleware will discard the duplicate.

When direct_communication is set to com.rti.dds.infrastructure.false, a TRANSIENT or PERSISTENT com.rti.dds.subscription.DataReader will only receive samples from the com.rti.dds.publication.DataWriter created by the persistence service. This brokered communication pattern provides a way to guarantee eventual consistency.

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


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