JMS/XLA as a Replication Mechanism

About Using JMS/XLA as a Replication Mechanism

TimesTen replication is sufficient for most customer needs; however, it is also possible to use JMS/XLA to replicate updates from one database to another.

Implementing your own replication scheme on top of JMS/XLA in this way is fairly complicated, but can be considered if TimesTen replication is not feasible for some reason.

Overview of TimesTen Replication in the Oracle TimesTen In-Memory Database Replication Guide describes TimesTen replication.

Applying JMS/XLA Messages to a Target Database

The source database generates JMS/XLA messages. To apply the messages to a target database, you must extract the XLA descriptor from them.

Use the MapMessage interface to extract the update descriptor:

MapMessage message;
/*
 *...other code
 */
try {
  byte[]updateMessage=
    mapMessage.getBytes(XlaConstants.UPDATE_DESCRIPTOR_FIELD);
}
catch (JMSException jex){
/*
 *...other code
 */
}

The target database may reside on a different system from the source database. The update descriptor is returned as a byte array and can be serialized for network transmission.

You must create a target database object that represents the target database so you can apply the objects from the source database. You can create a target database object named myTargetDataStore as an instance of the TargetDataStoreImpl class. For example:

TargetDataStore myTargetDataStore=
   new TargetDataStoreImpl("DSN=sampledb");

Apply messages to myTargetDataStore by using the TargetDataStore method apply(). For example:

myTargetDataStore.apply(updateDescriptor);

By default, TimesTen checks for conflicts on the target database before applying the update. If the target database has information that is later than the update, TargetDataStore throws an exception. If you do not want TimesTen to check for conflicts, use the TargetDataStore method setUpdateConflictCheckFlag() to change the behavior.

By default, TimesTen commits the update to the database based on commit flags and transaction boundaries contained in the update descriptor. If you want the application to perform manual commits instead, use the setAutoCommitFlag() method to change the autocommit flag. To perform a manual commit on myTargetDataStore, use the following command:

myTargetDataStore.commit();

You can perform a rollback if errors occur during the application of the update. Use the following command for myTargetDataStore:

myTargetDataStore.rollback();

Close myTargetDataStore by using the following command:

myTargetDataStore.close();

See JMS/XLA Replication API.

TargetDataStore Error Recovery

Invoking TargetDataStore can yield transient and permanent errors.

This section discusses error recovery.

TargetDataStore methods return a nonzero value when transient errors occur. The application can retry the operation and is responsible for monitoring update descriptors that must be reapplied. For more information about transient XLA errors, see XLA Error Handling in Oracle TimesTen In-Memory Database C Developer's Guide.

TargetDataStore methods return a JMSException object for permanent errors. If the application receives a permanent error, it should verify that the database is valid. If the database is invalid, the target database object should be closed and a new one should be created. Other types of permanent errors may require manual intervention.

The following example shows how to recover errors from a TargetDataStore object.

TargetDataStore theTargetDataStore;
byte[] updateDescriptor;
int rc;

// Other code
try {
  ...
  if ( (rc = theTargetDataStore.apply(updateDescriptor) ) == 0 ) {
    // Apply successful.
  }
  else {
    // Transient error. Retry later.
  }
 }
catch (JMSException jex) {
  if (theTargetDataStore.isDataStoreValid() ) {
    // Database valid; permanent error that may need Administrator intervention.
  }
  else {
    try {
      theTargetDataStore.close();
  }
  catch (JMSException closeEx) {
    // Close errors are not usual. This may need Administrator intervention.
  }
}