JBoss logo


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.

JBossTS 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, JBossTS 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. JBossTS 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 service, simply:

  1. Open a command prompt
  2. cd to the directory <jbossts_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 <jbossts_install_root>\services\bin\windows
  3. Type recoverymanagerservice.bat

UNIX

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

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

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

The JBossTS 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 JBossTS 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, JBossTS requires the ability to reconnect to the resource managers 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 JBossTS interface com.arjuna.ats.jta.recovery.XAResourceRecovery.

To inform the recovery system about each of the XAResourceRecovery instances, it is necessary to specify their class names through property variables in the jbossjts-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 transaction recovery it is necessary to tell JBossTS which types of Xid it can recover. Each Xid that JBossTS creates has a unique node identifier encoded within it and JBossTS will only recover transactions and states that match a specified node identifier. The node identifier to use should be provided to JBossTS via a property that starts with the name com.arjuna.ats.jta.xaRecoveryNode (multiple values may be provided). A value of * will force JBossTS 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 JBossTS 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 jbossjts-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 jbossjts-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 JBoss 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 jbossjts-properties.xml. See here for more information on how to configure the JBossTS 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 jbossjts-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 jbossjts-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 <jbossts_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 JBoss 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 JBossTS 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 jbossjts-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. Copyright 2008 JBoss, a division of Red Hat. All Rights Reserved.