[jboss-svn-commits] JBL Code SVN: r35920 - in labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US: extras and 1 other directory.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Tue Nov 9 02:04:31 EST 2010
Author: misty at redhat.com
Date: 2010-11-09 02:04:30 -0500 (Tue, 09 Nov 2010)
New Revision: 35920
Added:
labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/BasicXARecovery_Config_Example.xml
labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/JDBCXARecovery_Config_Example.xml
labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/XAResourceRecoveryHelper.java
labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/XAResourceRecovery_implementation.java
Modified:
labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/Transaction_Recovery.xml
Log:
Transactin Recovery chapter converted
Modified: labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/Transaction_Recovery.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/Transaction_Recovery.xml 2010-11-09 00:18:34 UTC (rev 35919)
+++ labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/Transaction_Recovery.xml 2010-11-09 07:04:30 UTC (rev 35920)
@@ -4,6 +4,250 @@
%BOOK_ENTITIES;
]>
<chapter>
- <title></title>
+ <title>Transaction Recovery</title>
+
+ <section>
+ <title>Failure recovery</title>
+ <para>
+ During recovery, the Transaction Manager must communicate with all resource managers being used by the
+ applications in the system. For each resource manager, the Transaction Manager uses the
+ <methodname>XAResource.recover</methodname> method to retrieve the list of transactions that are currently in a
+ <systemitem>prepared</systemitem> or <systemitem>heuristically completed</systemitem> state. Typically, a system
+ administrator, rather than a developer, configures all transactional resource factories that are used by the
+ applications deployed on the system. The JDBC <interfacename>XADataSource</interfacename> object, which is a
+ factory for JDBC <interfacename>XAConnection</interfacename> objects, is such an example..
+ </para>
+ <para>
+ <interfacename>XAResource</interfacename> objects are not persistent across system failures, so the Transaction
+ Manager needs a way to acquire the <interfacename>XAResource</interfacename> objects representing the resource
+ managers which might have participated in the transactions before a system failure. For example, a Transaction
+ Manager might use the JNDI lookup mechanism to acquire a connection from each of the transactional resource
+ factories, before obtaining the corresponding <interfacename>XAResource</interfacename> object for each
+ connection. The Transaction Manager then invokes the <methodname>XAResource.recover</methodname> method, which
+ requests each resource manager to return the transactions that are currently in a
+ <systemitem>prepared</systemitem> or <systemitem>heuristically completed</systemitem> state.
+ </para>
+ <para>
+ XA recovery necessitates informing JBossTS which types of Xid to recover. Each Xid that JBossTS
+ creates has a unique node identifier encoded within it, and JBossTS only recovers transactions and states that
+ match a specified node identifier. Provide the node identifier to JBossTS with the property
+ <varname>JTAEnvironmentBean.xaRecoveryNodes</varname>. You can pass multiple values in a list.
+ </para>
+ <warning>
+ <para>
+ Setting <varname>JTAEnvironmentBean.xaRecoveryNodes</varname> to <literal>*</literal> forces JBossTS to recover,
+ and possibly roll back, all transactions, regardless of their node identifiers. Use this value only with extreme
+ caution.
+ </para>
+ </warning>
+ <para>
+ If you use the JBossJTA JDBC driver, JBossJTA manages all XAResource crash recovery
+ automatically. Otherwise one of the following recovery mechanisms is used.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ If the <interfacename>XAResource</interfacename> is serializable, the serialized form is saved during
+ transaction commitment, and used during recovery. The recreated <interfacename>XAResource</interfacename> is
+ assumed to be valid, and you can use it to drive recovery on the associated database.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Otherwise, interfaces <interfacename>com.arjuna.ats.jta.recovery.XAResourceRecovery</interfacename>,
+ <interfacename>com.arjuna.ats.jta.recovery.XARecoveryResourceManager</interfacename>, and
+ <methodname>com.arjuna.ats.jta.recovery.XARecoveryResource</methodname> are used. Each is documented in the
+ JDBC chapters on failure recovery.<!-- Where is this? -->
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Recovering XA connections</title>
+ <para>
+ During failure recovery, JBossJTA needs the ability to reconnect to databases that were in use prior to the
+ failures, to resolve any outstanding transactions. Most connection information is saved by the transaction service
+ during its normal execution, and can be used during recovery to recreate the connection. However, sometimes a
+ failure occurs before all of the information can be saved, but after the database connection is used. For JBossTS
+ to recreate connections in this type of scenario, you need to provide implementations of JBossJTA interface
+ <interfacename>com.arjuna.ats.jta.recovery.XAResourceRecovery</interfacename> for each database in use by your
+ applications.
+ </para>
+ <note>
+ <para>
+ The transactional JDBC driver provided with JBossJTA does all of this work for you.
+ </para>
+ </note>
+ <para>
+ To inform the recovery system about each of the <interfacename>XAResourceRecovery</interfacename> instances,
+ specify their class names through the <varname>JTAEnvironmentBean.xaResourceRecoveryInstances</varname> property
+ variable, as a list of space-separated strings. Each string is a classname followed by optional configuration
+ information.
+ </para>
+ <example>
+ <title>Example <varname>JTAEnvironmentBean.xaResourceRecoveryInstances</varname> value</title>
+ <para>
+ Without configuration information:
+ </para>
+ <screen>JTAEnvironmentBean.xaResourceRecoveryInstances=com.foo.barRecovery</screen>
+ <para>
+ With configuration information:
+ </para>
+ <screen>JTAEnvironmentBean.xaResourceRecoveryInstances=com.foo.barRecovery;myData=hello</screen>
+ </example>
+ <para>
+ These properties need to go into the JTA section of the property file. Any errors will be reported during
+ recovery.
+ </para>
+
+ <example>
+ <title>Example <interfacename>XAResourceRecovery</interfacename> implementation</title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/XAResourceRecovery_implementation.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+
+ <table>
+ <title>Return values for <interfacename>XAResourceRecovery</interfacename> methods</title>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>initialise</entry>
+ <entry>
+ <para>
+ After the instance is created, any additional information found after the first semi-colon is passed to
+ the object. The object can then use this information in an implementation-specific manner to initialise
+ itself, or for another purpose.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>hasMoreResources</entry>
+ <entry>
+ <para>
+ Each <interfacename>XAResourceRecovery</interfacename> implementation may provide multiple
+ <interfacename>XAResource</interfacename> instances. Before any call to method
+ <methodname>getXAResource</methodname> is made, method <methodname>hasMoreResources</methodname> is
+ called to determine whether there are any further connections to be obtained. If this returns
+ <literal>false</literal>, <methodname>getXAResource</methodname> is not called again during this
+ recovery sweep, and the instance is not used again until the next recovery scan. The implementation must
+ maintain the internal state backing this method and reset the iteration as required. Otherwise, the
+ second and subsequent recovery sweeps in the lifetime of the JVM do not attempt recovery.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>getXAResource</entry>
+ <entry>
+ <para>
+ Returns an instance of the XAResource object. The <interfacename>XAResourceRecovery</interfacename>
+ implementation determines how the instance is created, and how the parameters to its constructors are
+ obtained. The parameters to the constructors of this class are similar to the ones used when creating
+ the initial driver or data source, and must be sufficient to create new
+ <interfacename>XAResource</interfacename>s to drive recovery.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <note>
+ <title>Calling <interfacename>XAResourRecovery</interfacename> during each sweep</title>
+ <para>
+ To ensure that your <interfacename>XAResourceRecovery</interfacename> instance is called during each sweep of the
+ recovery manager, make sure that once method <methodname>hasMoreResources</methodname> returns
+ <literal>false</literal> to indicate the end of work for the current scan, it returns <literal>true</literal> for
+ the next recovery scan.
+ </para>
+ </note>
+ </section>
+
+ <section>
+ <title>Alternative to XAResourceRecovery</title>
+ <para>
+ The iterator-based approach used by <interfacename>XAResourceRecovery</interfacename> requires implementations to
+ manage state, which adds complexity. Starting with JBossTS 4.4, you can provide an implementation of public
+ interface <interfacename>XAResourceRecoveryHelper</interfacename>:
+ </para>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/XAResourceRecoveryHelper.java" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
+
+ <para>
+ During each recovery sweep, method <methodname>getXAResources</methodname> is called and recovery is attempted on
+ each element of the array. For the majority of resource managers, only one
+ <interfacename>XAResource</interfacename> is needed in the array, because the <methodname>recover()</methodname>
+ call on it can return multiple Xids.
+ </para>
+ <para>
+ Unlike <interfacename>XAResourceRecovery</interfacename> instances, which are configured via the XML properties
+ file and instantiated by JBossTS, instances of <interfacename>XAResourceRecoveryHelper</interfacename> are
+ constructed by the application code and registered with JBossTS by calling
+ <methodname>XARecoveryModule.addXAResourceRecoveryHelper</methodname>.
+ </para>
+ <para>
+ Method <methodname>initialize</methodname> is not called by JBossTS in the current implementation. It is provided
+ to allow for the addition of further configuration options in later releases.
+ </para>
+ <para>
+ You can register <interfacename>XAResourceRecoveryHelper</interfacename> instances with the
+ <methodname>XARecoverModule.removeXAResourceRecoveryHelper</methodname> method. After registration, they are no
+ longer called by the recovery manager. Deregistration may block for a time if a recovery scan is in progress.
+ </para>
+ <para>
+ The ability to dynamically add and remove instances of <interfacename>XAResourceRecoveryHelper</interfacename>
+ while the system is running is an attractive option for environments where datasources may be deployed or
+ undeployed, such as application servers. Take care with classloading behaviour in such cases.
+ </para>
+ </section>
+
+ <section>
+ <title>Shipped XAResourceRecovery implementations</title>
+ <para>
+ Recovery of XA datasources can sometimes be implementation-dependent, requiring you to provide your own
+ <interfacename>XAResourceRecovery</interfacename> instances. However, JBossTS ships with several useful
+ implementations.
+ </para>
+ <para>
+ These <interfacename>XAResourceRecovery</interfacename> instances are primarily intended for when running JBossTS
+ outside of a container such as JBossAS or another application server. This is because they rely upon
+ <interfacename>XADataSources</interfacename> as the primary handle to drive recovery. If you are runing JBossTS
+ inside an application server or other container, consult the relevant integration documentation, to be sure to use
+ the right recovery modules.
+ </para>
+
+ <section>
+ <title>com.arjuna.ats.internal.jdbc.recovery.BasicXARecovery</title>
+ <para>
+ <interfacename>com.arjuna.ats.internal.jdbc.recovery.BasicXARecovery</interfacename> expects you to specify an
+ XML property file upon creation. It uses this file to read the configuration properties for the datasouce.
+ </para>
+ <example>
+ <title>Example</title>
+ <programlisting language="XML" role="XML"><xi:include href="extras/BasicXARecovery_Config_Example.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ </section>
+
+ <section>
+ <title>com.arjuna.ats.internal.jdbc.recovery.JDBCXARecovery</title>
+ <para>
+ <interfacename>com.arjuna.ats.internal.jdbc.recovery.JDBCXARecovery</interfacename> should work on any
+ datasource that is exposed via JNDI. It expects an XML property file to be specified upon creation, and uses the
+ file to read the database JNDI name, username and password.
+ </para>
+ <example>
+ <title>Example</title>
+ <programlisting language="XML" role="XML"><xi:include href="extras/JDBCXARecovery_Config_Example.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ </section>
+ <section>
+ <title>Initializing the Implementations</title>
+ <para>
+ Because these classes are <interfacename>XAResourceRecovery</interfacename> instances, they receive any
+ necessary initialization information from the <methodname>initialise</methodname> operation. In the case of
+ <interfacename>BasicXARecovery</interfacename> and <methodname>JDBCXARecovery</methodname>, the information is
+ the location of a property file, and is specified in the JBossTS configuration file. For example:
+ </para>
+ <screen>
+com.arjuna.ats.jta.recovery.XAResourceRecoveryJDBC=com.arjuna.ats.internal.jdbc.recovery.JDBCXAResourceRecovery;thePropertyFile
+ </screen>
+ </section>
+ </section>
</chapter>
-
Added: labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/BasicXARecovery_Config_Example.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/BasicXARecovery_Config_Example.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/BasicXARecovery_Config_Example.xml 2010-11-09 07:04:30 UTC (rev 35920)
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd"><
+<properties>
+ <entry key="DB_X_DatabaseUser">username</entry>
+ <entry key="DB_X_DatabasePassword">password"</entry>
+ <entry key="DB_X_DatabaseDynamicClass">DynamicClass</entry>
+ <entry key="DB_X_DatabaseURL">theURL</entry>
+</properties>
Added: labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/JDBCXARecovery_Config_Example.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/JDBCXARecovery_Config_Example.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/JDBCXARecovery_Config_Example.xml 2010-11-09 07:04:30 UTC (rev 35920)
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd"><
+<properties>
+ <entry key="DatabaseJNDIName">java:ExampleDS</entry>
+ <entry key="UserName">username</entry>
+ <entry key="Password">password</entry>
+</properties>
+
\ No newline at end of file
Added: labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/XAResourceRecoveryHelper.java
===================================================================
--- labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/XAResourceRecoveryHelper.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/XAResourceRecoveryHelper.java 2010-11-09 07:04:30 UTC (rev 35920)
@@ -0,0 +1,5 @@
+com.arjuna.ats.jta.recovery.XAResourceRecoveryHelper
+{
+ public boolean initialise(String p) throws Exception;
+ public XAResource[] getXAResources() throws Exception;
+}
Added: labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/XAResourceRecovery_implementation.java
===================================================================
--- labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/XAResourceRecovery_implementation.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/XAResourceRecovery_implementation.java 2010-11-09 07:04:30 UTC (rev 35920)
@@ -0,0 +1,8 @@
+public interface XAResourceRecovery
+{
+ public XAResource getXAResource () throws SQLException;
+
+ public boolean initialise (String p);
+
+ public boolean hasMoreResources ();
+};
\ No newline at end of file
More information about the jboss-svn-commits
mailing list