arjuna logoarjuna strap line


print this page
email this page

Recovery is the mechanism which preserves the transaction atomicity in presence of failures. The basic technique for implementing transactions in presence of failures is based on the use of logs. That is, a transaction system has to record enough information to ensure that it can be able to return to a previous state in case of failure or to ensure that changes committed by a transaction are properly stored.

ATS ensures that results of a transaction are applied consistently to all resources involved in a transaction, even in the presence of failure. To recover from failure, ATS relies on its Recovery Manager.

Basically, the Recovery Manager is a daemon process that invokes a set of well known Recovery Modules periodically in two steps; a first to determine transactions in doubt state and a second step to continue the completion of those transactions found in the first step. Since different type of resources may be involved in a transaction, different type of Recovery Modules may exist. ATS provides several type of modules that manage resources according to their position in the transaction tree (root, subordinate, leaf) or the nature of the data itself, transactional object for java or XAResource as seen in the previous trail.

Whatever the nature of the involved resource, recovery is based on information or logs held in the Object Store, which contains specific subdirectory holding information according to the nature of the participant.

This section provides only brief information on running the recovery manager from provided scripts. For complete information on the recovery manager (including how to configure it), click here.

Windows

To run the Recovery Manager as a Windows NT service, simply:

  1. Open a command prompt
  2. cd to the directory <arjunats_install_root>\services\bin\windows
  3. Type InstallRecoveryManagerService-NT.bat

Note: This directory also contains the uninstall script which is ran in the same manner.

To launch the Recovery Manager as a Windows process, simply:

  1. Open a command prompt
  2. cd to the directory <arjunats_install_root>\services\bin\windows
  3. Type recoverymanagerservice.bat

UNIX

To launch the Recovery Manager on a UNIX platform, simply:

  1. Open a command prompt
  2. cd to the directory <arjunats_install_root>\services\bin\[platform]
  3. Type recoverymanagerservice.sh start

Note: To uninstall the recovery manager, rerun the script specifying the stop flag.

The Arjuna recovery manager provides support for recovering XAResources whether or not they are Serializable. XAResources that do implement the Serializable interface are handled without requiring additional programmer defined classes. For those XAResources that need to recover but which cannot implement Serializable, it is possible to provide a small class which is used to help recover them.

This example shows the Arjuna recovery manager recovering a Serializable XAResource and a non-Serializable XAResource.

The demo's components

The application consists of four classes. Each class is well documented and it is recommended that the provided code is inspected to gain useful insight into some of the nuances of the recovery process.

XAResourceRecovery registration

When recovering from failures, Arjuna requires the ability to reconnect to the XAResource that were in use prior to the failures in order to resolve any outstanding transactions. In order to recreate those connections for non-Serializable XAResources it is necessary to provide implementations of the following Arjuna interface com.arjuna.ats.jta.waitForRecovery.XAResourceRecovery.

To inform the waitForRecovery system about each of the XAResourceRecovery instances, it is necessary to specify their class names through property variables in the arjunajts-properties.xml file. Any property variable which starts with the name XAResourceRecovery will be assumed to represent one of these instances, and its value should be the class name.

When running XA waitForRecovery it is necessary to tell Arjuna which types of Xid it can recover. Each Xid that Arjuna creates has a unique node identifier encoded within it and Arjuna will only recover transactions and states that match a specified node identifier. The node identifier to use should be provided to Arjuna via a property that starts with the name com.arjuna.ats.jta.xaRecoveryNode (multiple values may be provided). A value of * will force Arjuna to recover (and possibly rollback) all transactions irrespective of their node identifier and should be used with caution.

The recovery module for the non-Serializable XAResource must be deployed in order to provide support to recover the non-Serializable XAResource. If this step was missed out the Serializable XAResource would recover OK but Arjuna would have no knowledge of the non-Serializable XAResource and so it could not recover it. To register the non-Serializable XAResource XAResourceRecovery module, add an entry to the arjunajts-properties.xml.

Under the element <properties depends="jts" name="jta">, add:

<property name="com.arjuna.ats.jta.recovery.XAResourceRecovery1" value= "com.arjuna.demo.recovery.xaresource.NonSerializableExampleXAResourceRecovery"/> <property name="com.arjuna.ats.jta.xaRecoveryNode" value="*"/>

Configure the recovery manager scan period

By default, the recovery manager is configured to perform a pass over resources to be recovered every two minutes. It will then wait for ten seconds before re-checking the resources. Although the test will run OK with this configuration, it is possible to configure the recovery manager scan times to reduce the time waiting. To configure the intervals, edit the arjunajts-properties.xml as follows:

  • Edit the property "com.arjuna.ats.arjuna.recovery.periodicRecoveryPeriod" to change the value from 120 to 5.
  • Edit the property "com.arjuna.ats.arjuna.recovery.recoveryBackoffPeriod" to change the value from 10 to 5.

Specify the transaction manager type to use

The recovery manager will work in the same manner for either the JTA or JTS implementation. By default the Arjuna Transaction Service is configured to use a JTS transaction manager, in order to configure it to use a JTA transaction manager a change must again be made to the arjunajts-properties.xml. See here for more information on how to configure the ATS transaction manager to use JTA rather than JTS.

If you do change the transaction manager type remember to reconfigure the recovery manager as follows:

If you are using the ArjunaCore (raw JTA) transaction manager implementation comment out the element in arjunajts-properties.xml containing the following text:

internal.jta.recovery.jts.XARecoveryModule

If you are using the JTS transaction manager implementation comment out the element in arjunajts-properties.xml containing the following text:

internal.jta.recovery.arjunacore.XARecoveryModule

Launching the demo

To launch the Test Recovery Module, execute the following java program

  1. Open a command prompt
  2. cd to the directory <arjunats_install_root>\trail_map
  3. Type java com.arjuna.demo.recovery.xaresource.TestXAResourceRecovery
  4. View the output noting the crash during commit.
  5. Inspect the current working directory to note that the applications have created several log files which you may like to review.
  6. Type java com.arjuna.demo.recovery.xaresource.TestXAResourceRecovery -waitForRecovery
  7. Wait for the two resources to be recovered and committed.
  8. Re-review the log files from the working directory, if wanted.

Note: As you can see, the Serializable XAResource does not need it's recover() method called as the transaction manager is aware of all the information about this resource.

WARNING: Implementing a RecoveryModule and AbstractRecord is a very advanced feature of the transaction service. It should only be performed by users familiar with the all the concepts used in the Arjuna Transactions product. Please see the ArjunaCore guide for more information about RecoveryModules and AbstractRecords.

The following sample gives an overview how the Recovery Manager invokes a module to recover from failure. This basic sample does not aim to present a complete process to recover from failure, but mainly to illustrate the way to implement a recovery module. More details can be found in "Failure Recovery Guide".

The application used here consists to create an atomic transaction, to register a participant within the created transaction and finally to terminate it either by commit or abort. A set of arguments are provided:
  • to decide committing or aborting the transaction,
  • to decide generating a crash during the commitment process.

The demo's components

The application consists of three programs
  • The code of the main class that control the application (TestRecoveryModule.java), which consists to give the choice to either commit or abort the transaction and also to generate a crash.
  • The registered participant (SimpleRecord.java) has the following behaviour:
    - During the prepare phase, it writes a simple message - "I'm prepared" - on the disk such The message is written in a well known file
    - During the commit phase, it writes another message - "I'm committed" - in the same file used during prepare
    - If it receives an abort message, it removes from the disk the file used for prepare if any.
    - if a crash has been decided for the test, then it crashes during the commit phase - the file remains with the message "I'm prepared".
  • A Recovery Module (SimpleRecoveryModule.java) that consists to read the content of the file used to store the status of the participant, to determine that status and print a message indicating if a recovery action is needed or not.
Using the provided ATS Recovery Modules ensures that resources are correctly recovered. This sample illustrates how to define and register its own module. It's the responsibility of the module to re-create the appropriate objects using information retrieved from a log.

Recovery Module registration

The recovery module should now be deployed in order to be called by the Recovery Manager. To do so, we just need to add an entry in the arjunajts-properties.xml by adding a new property as follow:
<property name="com.arjuna.ats.arjuna.recovery.recoveryExtension<i>" value="com.arjuna.demo.recoverymodule.SimpleRecoveryModule"/>
Where <i> represent the new occurrence number that follows the last that already exists in the file. Once started, the Recovery Manager will automatically load the added Recovery module.

Starting the Recovery Manager

In a separate window launch the Recovery Manager, as follow.
java com.arjuna.ats.arjuna.recovery.RecoveryManager -test

Launching the demo

To launch the Test Recovery Module, execute the following java program

java com.arjuna.demo.recoverymodule.TestRecoveryModule 
		[-commit|-abort] [-crash]

Copyright 2002-2005 Arjuna Technologies All Rights Reserved.
info@arjuna.com +44 191 243 0676