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
- Open a command prompt
- cd to the directory <jbossts_install_root>\trail_map
- Type java com.arjuna.demo.recovery.xaresource.TestXAResourceRecovery
- View the output noting the crash during commit.
- Inspect the current working directory to note that the applications have created several log files which you may like to review.
- Type java com.arjuna.demo.recovery.xaresource.TestXAResourceRecovery -waitForRecovery
- Wait for the two resources to be recovered and committed.
- 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.