<?xml version="1.0"?>
<!--
  JBoss, Home of Professional Open Source
  Copyright 2006, Red Hat Middleware LLC, and individual contributors
  as indicated by the @author tags.
  See the copyright.txt in the distribution for a full listing
  of individual contributors.
  This copyrighted material is made available to anyone wishing to use,
  modify, copy, or redistribute it subject to the terms and conditions
  of the GNU Lesser General Public License, v. 2.1.
  This program is distributed in the hope that it will be useful, but WITHOUT A
  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
  PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
  You should have received a copy of the GNU Lesser General Public License,
  v.2.1 along with this distribution; if not, write to the Free Software
  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  MA  02110-1301, USA.


  (C) 2005-2006,
  @author JBoss Inc.
-->
<page title="JBossTS Trail map: Failure Recovery" rootpath="../..">
	<header>
        Trail map: JBossTS - Failure Recovery
    </header>
	<content>
		<navigation>
			<links include="includes/www_arjuna_com_navigation.xml"/>
			<links include="includes/trailmap_navigation.xml"/>
			<links title="Navigation">
				<link ref="index.html">Home</link>
			</links>
			<links include="includes/trailmap_additional.xml"/>
		</navigation>
		<area title="JBossTS Failure Recovery">
			<html>
				<p>The failure recovery subsystem of JBossTS will ensure that results of
a transaction are applied consistently to all resources affected by the
transaction, even if any of the application processes or the machine hosting
them crash or lose network connectivity. In the case of machine (system)
crash or network failure, the recovery will not take place until the system
or network are restored, but the original application does not need to
be restarted recovery responsibility is delegated to the Recovery Manager
process (see below). Recovery after failure requires that information about
the transaction and the resources involved survives the failure and is
accessible afterward: this information is held in the ActionStore, which
is part of the ObjectStore. If the ObjectStore is destroyed or modified,
recovery may not be possible.
<br>Until the recovery procedures are complete, resources affected by a
transaction that was in progress at the time of the failure may be inaccessible.
For database resources, this may be reported as tables or rows held by
"in-doubt transactions". </br>
				</p>
				<h4>The Recovery Manager</h4>
The Recovery Manager is a daemon process responsible for performing crash
recovery. Only one Recovery Manager runs per node. The Object Store provides
persistent data storage for transactions to log data. During normal transaction
processing each transaction will log persistent data needed for the commit
phase to the Object Store. On successfully committing a transaction this
data is removed, however if the transaction fails then this data remains
within the Object Store.
<br>The Recovery Manager functions by:</br>
				<ul>
					<li>
Periodically scanning the Object Store for transactions that may have failed.
Failed transactions are indicated by the presence of log data after a period
of time that the transaction would have normally been expected to finish.</li>
					<li>
Checking with the application process which originated the transaction
whether the transaction is still in progress or not.</li>
					<li>
Recovering the transaction by re-activating the transaction and then replaying
phase two of the commit protocol.</li>
				</ul>
To start the Recovery Manager issue the following command:

<pre>
java com.arjuna.ats.arjuna.recovery.RecoveryManager
</pre>

If the -test flag is used with the Recovery Manager then it will display a "Ready" message when initialised, i.e.,

<pre>
java com.arjuna.ats.arjuna.recovery.RecoveryManager -test
</pre>

On initialization the Recovery Manager first loads in configuration information
via a properties file. This configuration includes a number of recovery
activators and recovery modules, which are then dynamically loaded.
<br>Each recovery activator, which implements the
<font face="Courier New,Courier">com.arjuna.ats.arjuna.recovery.RecoveryActivator</font>
interface, is used to instantiate a recovery class related to the underlying
communication protocol. Indeed, since the version 3.0 of JBossTS, the
Recovery Manager is not specifically tied to an Object Request Broker or
ORB, which is to specify a recovery instance able to manage the OTS recovery
protocol the new interface RecoveryActivator is provided to identify specific
transaction protocol. For instance, when used with OTS, the RecoveryActivitor
has the responsibility to create a RecoveryCoordinator object able to respond
to the replay_completion operation.</br>
				<br>
All RecoveryActivator instances inherit the same interface. They are loaded via
the following recovery extension property:
</br>
				<pre>
&lt;property
  name="com.arjuna.ats.arjuna.recovery.recoveryActivator_&lt;number>"
  value="RecoveryClass"/>
</pre>
				<p>For instance the RecoveryActivator provided in the distribution of JTS/OTS,   which shall not be commented, is as follow : </p>
				<pre>
&lt;property
  name="com.arjuna.ats.arjuna.recovery.recoveryActivator_1"
  value="com.arjuna.ats.internal.jts.
     orbspecific.recovery.RecoveryEnablement"/>
</pre>
Each recovery module, which implements the <font face="Courier New,Courier">com.arjuna.ats.arjuna.recovery.RecoveryModule</font>
interface, is used to recover a different type of transaction/resource,
however each recovery module inherits the same basic behaviour.
<br>Recovery consists of two separate passes/phases separated by two timeout
periods. The first pass examines the object store for potentially failed
transactions; the second pass performs crash recovery on failed transactions.
The timeout between the first and second pass is known as the backoff period.
The timeout between the end of the second pass and the start of the first
pass is the recovery period. The recovery period is larger than the backoff
period.</br>
				<br>The Recovery Manager invokes the first pass upon each recovery module,
applies the backoff period timeout, invokes the second pass upon each recovery
module and finally applies the recovery period timeout before restarting
the first pass again.</br>
				<br>The recovery modules are loaded via the following recovery extension property:</br>
				<pre>
com.arjuna.ats.arjuna.recovery.recoveryExtension&lt;number>=&lt;RecoveryClass>
</pre>
The default RecoveryExtension settings are:

<pre>
&lt;property name="com.arjuna.ats.arjuna.recovery.recoveryExtension1"
  value="com.arjuna.ats.internal.
     arjuna.recovery.AtomicActionRecoveryModule"/>
&lt;property name="com.arjuna.ats.arjuna.recovery.recoveryExtension2"
  value="com.arjuna.ats.internal.
     txoj.recovery.TORecoveryModule"/>
&lt;property name="com.arjuna.ats.arjuna.recovery.recoveryExtension3"
  value="com.arjuna.ats.internal.
     jts.recovery.transactions.TopLevelTransactionRecoveryModule"/>
&lt;property  name="com.arjuna.ats.arjuna.recovery.recoveryExtension4"
  value="com.arjuna.ats.internal.
     jts.recovery.transactions.ServerTransactionRecoveryModule"/>
</pre>
				<h4>Configuring the Recovery Manager</h4>
				<h5>Periodic Recovery</h5>
The backoff period and recovery period are set using the following properties:

<pre>
com.arjuna.ats.arjuna.recovery.recoveryBackoffPeriod (default 10 secs)
com.arjuna.ats.arjuna.recovery.periodicRecovery (default 120 secs)
</pre>
				<h5>Expired entry removal</h5>
The operation of the recovery subsystem will cause some entries to be made
in the ObjectStore that will not be removed in normal progress. The RecoveryManager
has a facility for scanning for these and removing items that are very
old. Scans and removals are performed by implementations of the <font face="Courier New,Courier">com.arjuna.ats.arjuna.recovery.ExpiryScanner</font>.
Implementations of this interface are loaded by giving the class name as
the value of a property whose name begins with <font face="Courier New,Courier">ExperyScanner</font>.
<br>The RecoveryManager calls the scan() method on each loaded ExpiryScanner
implementation at an interval determined by the property <font face="Courier New,Courier">com.arjuna.ats.arjuna.recovery.expiryScanInterval</font>.
This value is given in hours default is 12. An EXPIRY_SCAN_INTERVAL value
of zero will suppress any expiry scanning. If the value as supplied is
positive, the first scan is performed when RecoveryManager starts; if the
value is negative, the first scan is delayed until after the first interval
(using the absolute value)</br>
				<br>The default ExpiryScanner is:</br>
				<pre>
&lt;property
  name="com.arjuna.ats.arjuna.recovery.
        expiryScannerTransactionStatusManager"
  value="com.arjuna.ats.internal.arjuna.recovery.
       ExpiredTransactionStatusManagerScanner"/>
 </pre>
				<p>The following table summarize properties used by the Recovery Manager. These
  properties are defined by default the properties file named RecoveryManager-properties.xml.
</p>
				<table BORDER="" WIDTH="100%">
					<tr ALIGN="CENTER" BGCOLOR="#66FFFF">
						<td width="38%">
							<b>Name</b>
						</td>
						<td width="34%">
							<b>Description</b>
						</td>
						<td width="9%">
							<b>Possible Value</b>
						</td>
						<td width="19%">
							<b>Default Value</b>
						</td>
					</tr>
					<tr>
						<td>
							<font size="-7">com.arjuna.ats.arjuna.<br/>
						  recovery.periodicRecoveryPeriod</font>
						</td>
						<td>
							<font size="-7">Interval in seconds between initiating the periodic recovery modules</font>
						</td>
						<td>
							<font size="-7">Value in seconds</font>
						</td>
						<td>
							<font size="-7">120</font>
						</td>
					</tr>
					<tr>
						<td>
							<font size="-7">com.arjuna.ats.arjuna.<br/>
						  recovery.recoveryBackoffPeriod</font>
						</td>
						<td>
							<font size="-7">Interval in seconds between first and second pass of periodic recovery</font>
						</td>
						<td>
							<font size="-7">Value in seconds</font>
						</td>
						<td>
							<font size="-7">10</font>
						</td>
					</tr>
					<tr>
						<td>
							<font size="-7">com.arjuna.ats.arjuna.<br/>
						  recovery.recoveryExtensionX</font>
						</td>
						<td>
							<font size="-7">Indicates a periodic recovery module to use. X is the occurence number
      of the recovery module among a set of recovery modules. These modules are
      invoked in sort-order of names</font>
						</td>
						<td>
							<font size="-6">The class name of the periodic recovery module </font>
						</td>
						<td>
							<font size="-8">JBossTS provides a set classes given in the RecoveryManager-properties.xml file</font>
						</td>
					</tr>
					<tr>
						<td>
							<font size="-7">com.arjuna.ats.arjuna.<br/>
						  recovery.recoveryActivator_X</font>
						</td>
						<td>
							<font size="-7">Indicates a recovery activator to use. X is the occurence number of the
      recovery activator among a set of recovery activators. </font>
						</td>
						<td>
							<font size="-7">The class name of the periodic recovery activator</font>
						</td>
						<td>
							<font size="-7">JBossTS provide one class that manages the recovery protocol specified
      by the OTS specification </font>
						</td>
					</tr>
					<tr>
						<td>
							<font size="-7">com.arjuna.ats.arjuna.<br/>
						  recovery.expiryScannerXXX</font>
						</td>
						<td>
							<font size="-7">Expiry scanners to use (order of invocation is random). Names must begin
      with &quot;com.arjuna.ats.arjuna.<br/>recovery.expiryScanner&quot;</font>
						</td>
						<td>
							<font size="-7">Class name</font>
						</td>
						<td>
							<font size="-7">JBossTS provides one class given in the RecoveryManager-properties.xml file</font>
						</td>
					</tr>
					<tr>
						<td>
							<font size="-7">com.arjuna.ats.arjuna.<br/>
						  recovery.expiryScanInterval</font>
						</td>
						<td>
							<font size="-7">Interval, in hours, between running the expiry scanners. This can be
      quite long. The absolute value determines the interval - if the value is
      negative, the scan will NOT be run until after one interval has elapsed.
      If positive the first scan will be immediately
      after startup. Zero will prevent any scanning. </font>
						</td>
						<td>
							<font size="-7">Value in hours</font>
						</td>
						<td>
							<font size="-7">12 </font>
						</td>
					</tr>
					<tr>
						<td>
							<font size="-7">com.arjuna.ats.arjuna.recovery.<br/>
						  transactionStatusManagerExpiryTime</font>
						</td>
						<td>
							<font size="-7">Age, in hours, for removal of transaction status manager item. This should
      be longer than any ts-using process will remain running. Zero = Never removed.
    </font>
						</td>
						<td>
							<font size="-7">Value in Hours</font>
						</td>
						<td>
							<font size="-7">12 </font>
						</td>
					</tr>
					<tr>
						<td>
							<font size="-7">com.arjuna.ats.arjuna.recovery<br/>
						 transactionStatusManagerPort</font>
						</td>
						<td>
							<font size="-7">Use this to fix the port on which the TransactionStatusManager listens</font>
						</td>
						<td>
							<font size="-7">Port number (short) </font>
						</td>
						<td>
							<font size="-7">use a free port</font>
						</td>
					</tr>
				</table>
			</html>
		</area>
	</content>
	<footer/>
</page>
