Durability and Persistence
[RTI Connext API Reference]

APIs related to RTI Connext Durability and Persistence. More...
RTI Connext offers the following mechanisms for achieving durability and persistence:

To use any of these features, you need a relational database, which is not included with RTI Connext. Supported databases are listed in the Release Notes.

These three features can be used separately or in combination.


Durable Writer History

This feature allows a com.rti.dds.publication.DataWriter to locally persist its local history cache so that it can survive shutdowns, crashes and restarts. When an application restarts, each com.rti.dds.publication.DataWriter that has been configured to have durable writer history automatically loads all the data in its history cache from disk and can carry on sending data as if it had never stopped executing. To the rest of the system, it will appear as if the com.rti.dds.publication.DataWriter had been temporarily disconnected from the network and then reappeared.

See also:
Configuring Durable Writer History

Durable Reader State

This feature allows a com.rti.dds.subscription.DataReader to locally persists its state and remember the data it has already received. When an application restarts, each com.rti.dds.subscription.DataReader that has been configured to have durable reader state automatically loads its state from disk and can carry on receiving data as if it had never stopped executing. Data that had already been received by the com.rti.dds.subscription.DataReader before the restart will be suppressed so it is not sent over the network.

Data Durability

This feature is a full implementation of the OMG DDS Persistence Profile. The DURABILITY QoS lets an application configure a com.rti.dds.publication.DataWriter such that the information written by the com.rti.dds.publication.DataWriter survives beyond the lifetime of the com.rti.dds.publication.DataWriter. In this manner, a late-joining com.rti.dds.subscription.DataReader can subscribe and receive the information even after the com.rti.dds.publication.DataWriter application is no longer executing. To use this feature, you need RTI Persistence Service -- an optional product that can be purchased separately.


Durability and Persistence Based on Virtual GUID

Every modification to the global dataspace made by a com.rti.dds.publication.DataWriter is identified by a pair (virtual GUID, sequence number).

Several com.rti.dds.publication.DataWriter entities can be configured with the same virtual GUID. If each of these com.rti.dds.publication.DataWriter entities publishes a sample with sequence number '0', the sample will only be received once by the com.rti.dds.subscription.DataReader entities subscribing to the content published by the com.rti.dds.publication.DataWriter entities.

NDDSGlobalDataspace.png

Global Dataspace Changes

RTI Connext also uses the virtual GUID (Global Unique Identifier) to associate a persisted state (state in permanent storage) to the corresponding DDS entity.

For example, the history of a com.rti.dds.publication.DataWriter will be persisted in a database table with a name generated from the virtual GUID of the com.rti.dds.publication.DataWriter. If the com.rti.dds.publication.DataWriter is restarted, it must have associated the same virtual GUID to restore its previous history.

Likewise, the state of a com.rti.dds.subscription.DataReader will be persisted in a database table whose name is generated from the com.rti.dds.subscription.DataReader virtual GUID

NDDSVirtualGUID.png

History/State Persistence Based on the Virtual GUID

A com.rti.dds.publication.DataWriter's virtual GUID can be configured using com.rti.dds.infrastructure.DataWriterProtocolQosPolicy.virtual_guid. Similarly, a com.rti.dds.subscription.DataReader's virtual GUID can be configured using com.rti.dds.infrastructure.DataReaderProtocolQosPolicy.virtual_guid.

The builtin.PublicationBuiltinTopicData and builtin.SubscriptionBuiltinTopicData structures include the virtual GUID associated with the discovered publication or subscription.

Refer to the User's Manual for additional use cases.

See also:
com.rti.dds.infrastructure.DataWriterProtocolQosPolicy.virtual_guid com.rti.dds.infrastructure.DataReaderProtocolQosPolicy.virtual_guid.

Configuring Durable Writer History

To configure a com.rti.dds.publication.DataWriter to have durable writer history, use the PROPERTY QoS policy associated with the com.rti.dds.publication.DataWriter or the com.rti.dds.domain.DomainParticipant.

Properties defined for the com.rti.dds.domain.DomainParticipant will be applied to all the com.rti.dds.publication.DataWriter objects belonging to the com.rti.dds.domain.DomainParticipant, unless the property is overwritten by the com.rti.dds.publication.DataWriter.

See also:
com.rti.dds.infrastructure.PropertyQosPolicy
The following table lists the supported durable writer history properties.

Durable Writer History Properties
Property Description
dds.data_writer.history.plugin_name Must be set to "dds.data_writer.history.odbc_plugin.builtin" to enable durable writer history in the DataWriter. This property is required.
dds.data_writer.history.odbc_plugin.dsn The ODBC DSN (Data Source Name) associated with the database where the writer history must be persisted. This property is required.
dds.data_writer.history.odbc_plugin.driver This property tells RTI Connext which ODBC driver to load. If the property is not specified, RTI Connext will try to use the standard ODBC driver manager library: UnixOdbc (odbc32.dll) on UNIX/Linux systems; the Windows ODBC driver manager (libodbc.so) on Windows systems).
dds.data_writer.history.odbc_plugin.username Configures the username used to connect to the database. This property is not used if it is unspecified. There is no default value.
dds.data_writer.history.odbc_plugin.password Configures the password used to connect to the database. This property is not used if it is unspecified. There is no default value.
dds.data_writer.history.odbc_plugin.shared If set to 1, RTI Connext creates a single connection per DSN that will be shared across DataWriters within the same Publisher.

If set to 0 (the default), a com.rti.dds.publication.DataWriter will create its own database connection.

Default: 0 (false)

dds.data_writer.history.odbc_plugin.instance_cache_max_size These properties configure the resource limits associated with the ODBC writer history caches. To minimize the number of accesses to the database, RTI Connext uses two caches, one for samples and one for instances. The initial and maximum sizes of these caches are configured using these properties. The resource limits initial_instances, max_instances, initial_samples, max_samples and max_samples_per_instance in the com.rti.dds.infrastructure.ResourceLimitsQosPolicy are used to configure the maximum number of samples and instances that can be stored in the relational database. Default: com.rti.dds.infrastructure.ResourceLimitsQosPolicy.max_instances
dds.data_writer.history.odbc_plugin.instance_cache_init_size See description above. Default: com.rti.dds.infrastructure.ResourceLimitsQosPolicy.initial_instances
dds.data_writer.history.odbc_plugin.sample_cache_max_size See description above. Default: 32 (the minimum)
dds.data_writer.history.odbc_plugin.sample_cache_init_size See description above. Default: 32
dds.data_writer.history.odbc_plugin.restore This property indicates whether or not the persisted writer history must be restored once the com.rti.dds.publication.DataWriter is restarted. If the value is 0, the content of the database associated with the com.rti.dds.publication.DataWriter being restarted will be deleted. If the value is 1, the com.rti.dds.publication.DataWriter will restore its previous state from the database content. Default: 1
dds.data_writer.history.odbc_plugin.in_memory_state This property determines how much state will be kept in memory by the ODBC writer history in order to avoid accessing the database.

When in_memory_state is equal to 1, instance_cache_max_size is always equal to com.rti.dds.infrastructure.ResourceLimitsQosPolicy.max_instances (it cannot be changed). In addition, the ODBC writer history will keep in memory a fixed state overhead of 24 bytes per sample. In this operating mode, the ODBC writer history provides the best performance. However, the restore operation will be slower and the maximum number of samples that the writer history can manage will be limited by the available physical memory.

If in_memory_state is equal to 0, all the state will be kept in the underlying database. In this operating mode, the maximum number of samples in the writer history will not be limited by the physical memory available unless the underlying database is an in-memory database (TimesTen).

Default: 1

Configuring Durable Reader State

To configure a com.rti.dds.subscription.DataReader with durable reader state, use the PROPERTY QoS policy associated with the com.rti.dds.subscription.DataReader or com.rti.dds.domain.DomainParticipant.

A property defined in the com.rti.dds.domain.DomainParticipant will be applicable to all the com.rti.dds.subscription.DataReader belonging to the com.rti.dds.domain.DomainParticipant unless it is overwritten by the com.rti.dds.subscription.DataReader.

See also:
com.rti.dds.infrastructure.PropertyQosPolicy
The following table lists the supported durable reader state properties.

Durable Reader State Properties
Property Description
dds.data_reader.state.odbc.dsn The ODBC DSN (Data Source Name) associated with the database where the com.rti.dds.subscription.DataReader state must be persisted. This property is required.
dds.data_reader.state.filter_redundant_samples To enable durable reader state, this property must be set to 1. Otherwise, the reader state will not be kept and/or persisted. When the reader state is not maintained, RTI Connext does not filter duplicate samples that may be coming from the same virtual writer. By default, this property is set to 1.
dds.data_reader.state.odbc.driver This property is used to indicate which ODBC driver to load. If the property is not specified, RTI Connext will try to use the standard ODBC driver manager library: UnixOdbc (odbc32.dll) on UNIX/Linux systems; the Windows ODBC driver manager (libodbc.so) on Windows systems).
dds.data_reader.state.odbc.username This property configures the username used to connect to the database. This property is not used if it is unspecified. There is no default value.
dds.data_reader.state.odbc.password This property configures the password used to connect to the database. This property is not used if it is unspecified. There is no default value.
dds.data_reader.state.restore This property indicates if the persisted com.rti.dds.subscription.DataReader state must be restored or not once the com.rti.dds.subscription.DataReader is restarted. If this property is 0, the previous state will be deleted from the database. If it is 1, the com.rti.dds.subscription.DataReader will restore its previous state from the database content. Default: 1
dds.data_reader.state.checkpoint_frequency This property controls how often the reader state is stored in the database. A value of N means to store the state once every N samples.

A high frequency will provide better performance. However, if the reader is restarted it may receive some duplicate samples. These samples will be filtered by the middleware and they will not be propagated to the application.

Default: 1

dds.data_reader.state.persistence_service.request_depth This property indicates the number of most recent historical samples that the persisted com.rti.dds.subscription.DataReader wants to receive when it starts up.

Default: 0



Configuring Data Durability

RTI Connext implements DurabilityQosPolicyKind.TRANSIENT_DURABILITY_QOS and DurabilityQosPolicyKind.PERSISTENT_DURABILITY_QOS durability using RTI Persistence Service, available for purchase as a separate RTI product.

For more information on RTI Persistence Service, refer to the User's Manual, or the RTI Persistence Service online documentation.

See also:
DURABILITY

RTI Connext Java API Version 4.5f Copyright © 17 Mar 2012 Real-Time Innovations, Inc