[jboss-svn-commits] JBL Code SVN: r32438 - labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Tue Apr 6 03:38:51 EDT 2010
Author: misty at redhat.com
Date: 2010-04-06 03:38:50 -0400 (Tue, 06 Apr 2010)
New Revision: 32438
Added:
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Errors_And_Exceptions.xml
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Failure_Recovery.xml
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Initializing_JBossTS_Applications.xml
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Intro.xml
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/ORB_Specific_Configurations.xml
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Objectstore_Management.xml
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Runtime_Information.xml
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Selecting_the_JTA_Implementation.xml
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Starting_and_Stopping.xml
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Transaction_Service_Management.xml
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Web_Service_Specific_Management.xml
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/XA_Specific_Service_Managenent.xml
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/xa_recovery.xml
Removed:
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Chapter.xml
Modified:
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/JBoss_Transactions_Administrators_Guide.xml
Log:
Updated the guide to be divided into chapters. Also updated the Failure & Recovery chapter to address JBPAPP-3851
Deleted: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Chapter.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Chapter.xml 2010-04-06 07:37:56 UTC (rev 32437)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Chapter.xml 2010-04-06 07:38:50 UTC (rev 32438)
@@ -1,661 +0,0 @@
-<?xml version='1.0'?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
-
-
-<chapter><title>Introduction</title>
- <para>Apart from ensuring that the run-time system is executing normally, there is little continuous administration needed for the JBoss Transactions software. There are a few points however, that should be made:</para>
- <para><orderedlist>
- <listitem>
- <para>The present implementation of the JBoss TA system provides no security or protection for data. The objects stored in the JBoss Transactions object store are (typically) owned by the user who ran the application that created them. The Object Store and Object Manager facilities make no attempt to enforce even the limited form of protection that Unix/Windows provides. There is no checking of user or group IDs on access to objects for either reading or writing.</para>
- </listitem>
- <listitem>
- <para>Persistent objects created in the Object Store never go away unless the StateManager.destroy method is invoked on the object or some application program explicitly deletes them. This means that the Object Store gradually accumulates garbage (especially during application development and testing phases). At present we have no automated garbage collection facility. Further, we have not addressed the problem of dangling references. That is, a persistent object, A, may have stored a Uid for another persistent object, B, in its passive representation on disk. There is nothing to prevent an application from deleting B even though A still contains a reference to it. When A is next activated and attempts to access B, a run-time error will occur.</para>
- </listitem>
- <listitem>
- <para>There is presently no support for version control of objects or database reconfiguration in the event of class structure changes. This is a complex research area that we have not addressed. At present, if you change the definition of a class of persistent objects, you are entirely responsible for ensuring that existing instances of the object in the Object Store are converted to the new representation. The JBoss Transactions software can neither detect nor correct references to old object state by new operation versions or vice versa.</para>
- </listitem>
- <listitem>
- <para>Object store management is critically important to the transaction service.</para>
- </listitem>
- </orderedlist></para>
-
-<section>
- <title>Starting and Stopping the transaction manager</title>
- <para>
- By default the transaction manager starts up in an active state such that new transactions can be created immediately. If you wish to have more control over this it is possible to set the <property>com.arjuna.ats.arjuna.coordinator.startDisabled</property> configuration option to <literal>YES</literal>, in which case no transactions can be created until the transaction manager is enabled (via a call to <methodname>TxControl.enable</methodname>).
- </para>
- <para>
- It is possible to stop the creation of new transactions at any time by calling <methodname>TxControl.disable</methodname>. Transactions that are currently executing will not be affected. By default recovery will be allowed to continue and the transaction system will still be available to manage recovery requests from other instances in a distributed environment. (See the Failure Recovery Guide for further details). However, if you wish to disable recovery as well as remove any resources it maintains, then you can pass true to <methodname>TxControl.disable</methodname>; the default is to use <literal>false</literal>.
- </para>
- <para>
- If you wish to shut the system down completely then it may also be necessary to terminate the background transaction reaper (see the Programmers Guide for information about what the reaper does.) In order to do this you may want to first prevent the creation of new transactions (if you are not creating transactions with timeouts then this step is not necessary) using <methodname>TxControl.disable</methodname>. Then you should call <methodname>TransactionReaper.terminate</methodname>. This method takes a boolean parameter: if true then the method will wait for the normal timeout periods associated with any transactions to expire before terminating the transactions; if false then transactions will be forced to terminate (rollback or have their outcome set such that they can only ever rollback) immediately.
- </para>
- <important>
- <para>
- If you intent to restart the recovery manager later after having terminated it then you <emphasis>must</emphasis> use the <methodname>terminate</methodname> method with <property>asynchronous behavior</property> set to <literal>false</literal> when shutting down the recovery manager.
- </para>
- </important>
-</section>
-<section><title>ObjectStore management</title>
- <para>Within the transaction service installation, the object store is updated regularly whenever transactions are created, or when Transactional Objects for Java is used. In a failure free environment, the only object states which should reside within the object store are those representing objects created with the Transactional Objects for Java API. However, if failures occur, transaction logs may remain in the object store until crash recovery facilities have resolved the transactions they represent. As such it is very important that the contents of the object store are not deleted without due care and attention, as this will make it impossible to resolve in doubt transactions. In addition, if multiple users share the same object store it is important that they realise this and do not simply delete the contents of the object store assuming it is an exclusive resource.</para>
- <para>
- Apart from ensuring that the run-time system is executing normally, there is little continuous administration needed for the JBossTS software. There are a few points however, that should be made:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- The present implementation of the JBossTS system provides no security or protection for data. It is recommended that the objects stored in the JBossTS are owned by user arjuna. The Object Store and Object Manager facilities make no attempt to enforce even the limited form of protection that Unix and Windows provides. There is no checking of user or group IDs on access to objects for either reading or writing.
- </para>
- </listitem>
- <listitem>
- <para>
- Persistent objects created in the Object Store never go away unless the <methodname>StateManager.destroy</methodname> method is invoked on the object or some application program explicitly deletes them. This means that the Object Store gradually accumulates garbage (especially during application development and testing phases). At present we have no automated garbage collection facility. Further, we have not addressed the problem of dangling references. That is, a persistent object, A, may have stored a UID for another persistent object, B, in its passive representation on disk. There is nothing to prevent an application from deleting B even though A still contains a reference to it. When A is next activated and attempts to access B, a run-time error will occur.
- </para>
- </listitem>
- <listitem>
- <para>
- There is presently no support for version control of objects or database reconfiguration in the event of class structure changes. This is a complex research area that we have not addressed. At present, if you change the definition of a class of persistent objects, you are entirely responsible for ensuring that existing instances of the object in the Object Store are converted to the new representation. The JBossTS software can neither detect nor correct references to old object state by new operation versions or vice versa.
- </para>
- </listitem>
- <listitem>
- <para>
- Object store management is critically important to the transaction service.
- </para>
- </listitem>
- </itemizedlist>
-</section>
-
-<section>
- <title>OTS and J2EE Transaction service management </title>
- <section>
- <title>Starting the run-time system</title>
- <para>
- The JBossTS run-time support consists of run-time packages and the OTS transaction manager server. By default JBossTS does not use a separate transaction manager server: transaction managers are co-located with each application process to improve performance and improve application fault-tolerance (the application is no longer dependant upon another service in order to function correctly).
- </para>
- <para>
- When running applications which require a separate transaction manager, you must set the <varname>com.arjuna.ats.jts.transactionManager</varname> environment variable to have the value <literal>yes</literal>. The system will then locate the transaction manager server in a manner specific to the ORB being used. The server can be located in a number of ways: by being registered with a name server, added to the ORB’s initial references, via a JBossTS specific references file, or by the ORB’s specific location mechanism (if applicable).
- </para>
- <para>
- It is possible to override the default registration mechanism by using the <varname>com.arjuna.orbportability.resolveService</varname> environment variable. This can have one of the following values:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>CONFIGURATION_FILE</literal>: the default, this causes the system to use the <filename>CosServices.cfg</filename> file.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>NAME_SERVICE</literal>: JBossTS will attempt to use a name service to register the transaction factory. If this is not supported, an exception will be thrown.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>BIND_CONNECT</literal>: JBossTS will use the ORB-specific bind mechanism. If this is not supported, an exception will be thrown.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>RESOLVE_INITIAL_REFERENCES</literal>: JBossTS will attempt to register the transaction service with the ORBs initial service references.
- </para>
- </listitem>
- </itemizedlist>
- <note>
- <para>
- This may not be supported on all ORBs. An exception will be thrown in that case and another option will have to be used.
- </para>
- </note>
- <formalpara>
- <title>OTS configuration file</title>
- <para>
- Similar to the resolve_initial_references, JBossTS supports an initial reference file where references for specific services can be stored and used at runtime. The file, CosServices.cfg, consists of two columns: the service name (in the case of the OTS server TransactionService) and the IOR, separated by a single space. CosServices.cfg normally resides in the etc directory of the JBossTS installation; the actual location is determined at runtime by searching the CLASSPATH for an old copy of the file resident within an etc directory, or, if one is not found, the location of the TransactionService properties file directory.
- </para>
- </formalpara>
- <para>
- The OTS server will automatically register itself in this file (creating it if necessary) if this option is being used. Stale information is also automatically removed. Machines which wish to share the same transaction server should have access to (or a copy of) this file.
- </para>
- <para>
- The name and location of the file can be overridden using the <property>com.arjuna.orbportability.initialReferencesFile</property> and <property>com.arjuna.orbportability.initialReferencesRoot</property> property variables, respectively. It is recommended that the <property>com.arjuna.orbportability.initialReferencesRoot</property> variable is set. For example:
- </para>
-<screen>
-com.arjuna.orbportability.initialReferencesFile=myFile
-com.arjuna.orbportability.initialReferencesRoot=c:\\temp
-</screen>
- <formalpara>
- <title>Name Service</title>
- <para>
- If the ORB you are using supports a name service, and JBossTS has been configured to use it, then the transaction manager will automatically be registered with it. There is no further work required. This option is not used for JacORB
- </para>
- </formalpara>
- <formalpara>
- <title>resolve_initial_references</title>
- <para>
- Currently this option is only supported for JacORB.
- </para>
- </formalpara>
- <formalpara>
- <title>Resolution service table</title>
- <para>
- The following table summarizes the different ways in which the OTS transaction manager may be located on specific ORBs:
- </para>
- </formalpara>
- <table>
- <title>Locating the OTS transaction manager server</title>
- <tgroup cols='2' align='left' colsep='1' rowsep='1'>
- <thead>
- <row>
- <entry>Resolution Mechanism</entry>
- <entry>ORB</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>OTS configuration file</entry>
- <entry>All available ORBs</entry>
- </row>
- <row>
- <entry>Name Service</entry>
- <entry>JacORB</entry>
- </row>
- <row>
- <entry>resolve_initial_references</entry>
- <entry>JacORB</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
- <section>
- <title>XA specific management</title>
- <para>
- Each XA Xid that JBossTS creates must have 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 the <property>com.arjuna.ats.arjuna.xa.nodeIdentifier</property> property. You must make sure this value is unique across your JBossTS instances. If you do not provide a value, then JBossTS will fabricate one and report the value via the logging infrastructure.
- </para>
- <para>
- When running XA recovery it is therefore 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 <property>com.arjuna.ats.jta.xaRecoveryNode</property>; multiple values may be provided. A value of <code>*</code> will force JBossTS to recover (and possibly rollback) all transactions irrespective of their node identifier and should be used with caution.
- </para>
- </section>
-</section>
-<section>
- <title>Web Service Transaction service management</title>
- <para>
- The basic building blocks of a transactional Web Services application are the application itself, the Web services that the application consumes, the Transaction Manager, and the transaction participants which support those Web services. Though it is unlikely in a typical deployment that a single developer will be expected to support all of these roles, the concepts are presented here so that a global model can be visualized. It will often be the case that developers will produce services, or applications that consume services, whilst system administrators will run the transaction-management infrastructure.
- </para>
- <section>
- <title>The Transaction Manager</title>
- <para>
- The transaction manager is a Web service which coordinates JBossTS transactions. It is the only software component in JBossTS that is meant to be run directly as a network service, rather than to support end-user code. The transaction manager runs as a JAXM request/response Web service.
- </para>
- <important>
- <para>
- When starting up an application server instance that has JBossTS deployed within it, you may see various <emphasis>error</emphasis> messages in the console or log. For example <code>16:53:38,850 ERROR [STDERR] Message Listener Service: started, message listener jndi name activationcoordinator</code>. These are for information purposes only and are not actual errors.
- </para>
- </important>
- <formalpara>
- <title>Configuring the Transaction Manager</title>
- <para>
- The Transaction Manager and related infrastructure are configured by means of properties files: <filename>wscf.xml</filename>, <filename>wst.xml</filename> and <filename>wstx.xml</filename>. These files can be found in the conf directory and are used for configuring the demo application and the standalone module.
- </para>
- </formalpara>
- <para>
- For the most part the default values in these files need not be altered. However, the <property>com.arjuna.ats.arjuna.objectstore.objectStoreDir</property> property determines the location of the persistent store used to record transaction state. The default value of <filename>C:/temp/ObjectStore</filename> should be changed to a value appropriate to your system. For production environments this directory should reside on fault tolerant media such as a RAID array.
- </para>
- <para>
- When a standalone coordinator is being used by an application it is necessary to enable and modify two further properties in <filename>wstx.xml</filename>, <property>com.arjuna.mw.wst.coordinatorURL</property> and <property>com.arjuna.mw.wst.terminatorURL</property>. These contain the URLs necessary for the client application to contact the standalone coordinator and should be configured with the correct hostname and port of the standalone coordinator.
- </para>
- <para>
- JBossTS is highly modular so in order to allow for flexible deployment of individual components, the same property values are sometimes required to appear in more than one configuration file. For the majority of configurations, you should maintain consistent values for properties that are defined in more than one file.
- </para>
- <formalpara>
- <title>Deploying the Transaction Manager</title>
- <para>
- The JBossTS Web Service Transaction Manager component consists of a number of JAR files containing the application’s class files, plus Web service (WAR) files which expose the necessary services. Programmers will typically include all these components in their application EAR file during application development, simplifying deployment of the transaction infrastructure. For production usage the Transaction Manager may be installed as an application in its own right, allowing for centralized configuration and management at the server level, independent of specific applications. The demonstration application shipped with JBossTS provides a sample deployment descriptor illustrating how the Transaction Manager components can be included in an application.
- </para>
- </formalpara>
- <para>
- JBossTS 4.0 uses fixed endpoints for its underlying protocol communication. Therefore, problems may arise if multiple applications using JBossTS are deployed to the same server concurrently. If you wish to deploy several transactional applications in the same server, the Transaction Manger must be deployed as a separate application and not embedded within the deployment of individual applications.
- </para>
- <para>
- The coordinator directory in the JBossTS installation has been provided to assist in the configuration and deployment of a stand-alone transaction manager. In order to use this, you must:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Have JBoss Enterprise Application Platform 5 installed
- </para>
- </listitem>
- <listitem>
- <para>
- Install ant 1.4 or later.
- </para>
- </listitem>
- </itemizedlist>
- <important>
- <para>
- It is important that a separate application server installation be used from the one that clients and services are deployed into since otherwise conflicts may occur between the various JBossTS components.
- </para>
- </important>
- <para>
- You must then edit the build.xml included with coordinator to point to the application server installation where the transaction coordinator will be deployed and the location of the JBossTS installation. The files <filename>ws-c_jaxm_web-app.xml</filename> and <filename>ws-t_jaxm_web-app.xml</filename> in the <filename>dd</filename> directory of coordinator are the deployment descriptors for the WS-C and WS-T WAR files. These files contain templated URLs. During the build phase, ant will substitute the hostname and port values you specify in the <filename>build.xml</filename> into these files.
- </para>
- <para>
- Run <code>ant</code>, with <code>target deploy-weblogic</code>, <code>deploy-jboss</code> or <code>deploy-webmethods</code>, to create and deploy a new coordinator into the correct application server installation.
- </para>
- <para>
- Now all you need to do is point your client at the required coordinator. To do this, generate the demo application specifying the port and hostname of the coordinator.
- </para>
- <formalpara>
- <title>Deployment descriptors</title>
- <para>
- In general, it should not be necessary to change the contents of the various deployment descriptors used by JBossTS. However, if you do need to modify them they are all included in the coordinator module.
- </para>
- </formalpara>
- <para>
- Not all JBossTS components have ready access to the information in the deployment descriptors. Therefore, if you modify the JNDI names used by any of the WS-C or WS-T deployment descriptors you may need to inform other JBossTS components at runtime. This can be accomplished by setting an appropriate property in the <filename>wstx.xml</filename> configuration file.
- </para>
- <para>
- The following table shows the default JNDI name used by the deployment descriptors and the corresponding property to set if the default value is changed.
- </para>
- <table>
- <title>Deployment descriptor values and properties</title>
- <tgroup cols='2' align='left' colsep='1' rowsep='1'>
- <thead>
- <row>
- <entry>JNDI Name</entry>
- <entry>Property</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>Activationrequester</entry>
- <entry>com.arjuna.mw.wst.at.activationrequester</entry>
- </row>
- <row>
- <entry>Activationcoordinator</entry>
- <entry>com.arjuna.mw.wst.at.activationcoordinator</entry>
- </row>
- <row>
- <entry>Completionparticipant</entry>
- <entry>com.arjuna.mw.wst.at.completionparticipant</entry>
- </row>
- <row>
- <entry>Registrationrequester</entry>
- <entry>com.arjuna.mw.wst.at.registrationrequester</entry>
- </row>
- <row>
- <entry>durable2pcdispatcher</entry>
- <entry>com.arjuna.mw.wst.at.durable2pcdispatcher</entry>
- </row>
- <row>
- <entry>durable2pcparticipant</entry>
- <entry>com.arjuna.mw.wst.at.durable2pcparticipant</entry>
- </row>
- <row>
- <entry>volatile2pcdispatcher</entry>
- <entry>com.arjuna.mw.wst.at.volatile2pcdispatcher</entry>
- </row>
- <row>
- <entry>volatile2pcparticipant</entry>
- <entry>com.arjuna.mw.wst.at.volatile2pcparticipant</entry>
- </row>
- <row>
- <entry>businessagreementwithparticipantcompletiondispatcher</entry>
- <entry>com.arjuna.mw.wst.ba.businessagreementwpcdispatcher</entry>
- </row>
- <row>
- <entry>businessagreementwithparticipantcompletionparticipant</entry>
- <entry>com.arjuna.mw.wst.ba.businessagreementwpcparticipant</entry>
- </row>
- <row>
- <entry>businessagreementwithcoordinatorcompletiondispatcher</entry>
- <entry>com.arjuna.mw.wst.ba.businessagreementwccdispatcher</entry>
- </row>
- <row>
- <entry>businessagreementwithcoordinatorcompletionparticipant</entry>
- <entry>com.arjuna.mw.wst.ba.businessagreementwccparticipant</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-</section>
-<section><title>JBoss Transactions runtime information</title>
- <para>Each module that comprises JBoss Transactions possesses a class called Info. These classes all provide a single toString method that returns an XML document representing the configuration information for that module. So, for example:</para>
-
- <programlisting><module-info name="arjuna">
- <source-identifier>unknown</source-identifier>
- <build-information>
- Arjuna Technologies [mlittle] (Windows 2000 5.0)
- </build-information>
- <version>unknown</version>
- <date>2002/06/15 04:06 PM</date>
- <notes></notes>
- <configuration>
- <properties-file dir="null">arjuna.properties</properties-file>
- <object-store-root>null</object-store-root>
- </configuration>
-</module-info></programlisting>
-</section>
-
-<section><title>Failure recovery administration</title>
- <para>The failure recovery subsystem of JBoss Transactions 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.</para>
- <para><orderedlist>
- <listitem>
- <para>If the ObjectStore is destroyed or modified, recovery may not be possible.</para>
- </listitem>
- </orderedlist></para>
- <para>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”. For TransactionalObjects for Java resources, an attempt to activate the Transactional Object (as when trying to get a lock) will fail.</para>
-
- <section><title>The Recovery Manager</title>
- <para>The failure recovery subsystem of JBoss Transactions requires that the stand-alone Recovery Manager process be running for each ObjectStore (typically one for each node on the network that is running JBoss Transactions applications). The RecoveryManager file is located in the arjunacore jar file within the package <classname>com.arjuna.ats.arjuna.recovery.RecoveryManager</classname>. To start the Recovery Manager issue the following command:</para>
- <para><command>java com.arjuna.ats.arjuna.recovery.RecoveryManager</command></para>
- <para>If the <literal>-test</literal> flag is used with the Recovery Manager then it will display a “Ready” message when initialised, i.e.,</para>
- <para><command>java com.arjuna.ats.arjuna.recovery.RecoveryManager -test</command></para>
- </section>
-
- <section><title>Configuring the Recovery Manager</title>
- <para>The RecoveryManager reads the properties defined in the <filename>arjuna.properties</filename> file and then also reads the property file <filename>RecoveryManager.properties</filename>, from the same directory as it found the arjuna properties file. An entry for a property in the RecoveryManager properties file will override an entry for the same property in the main TransactionService properties file. Most of the entries are specific to the Recovery Manager.</para>
- <para>A default version of <filename>RecoveryManager.properties</filename> is supplied with the distribution – this can be used without modification, except possibly the debug tracing fields (see below, Output). The rest of this section discusses the issues relevant in setting the properties to other values (in the order of their appearance in the default version of the file)</para>
-
- <section><title>Output</title>
- <para>
- It is likely that installations will want to have some form of output from the RecoveryManager, to provide a record of what recovery activity has taken place. RecoveryManager uses the logging tracing mechanism provided by the Arjuna Common Logging Framework (CLF), which provides a high level interface that hides differences that exist between existing logging APIs such Jakarta log4j or JDK 1.4 logging API. CLF indirects all logging via the Apache Commons Logging framework and configuration is assumed to occur through that framework.
- </para>
- <para>
- With the CLF applications make logging calls on logger objects. Loggers may use logging Levels to decide if they are interested in a particular log message. Each log message has an associated log Level, that gives the importance and urgency of a log message. The set of possible Log Levels are DEBUG, INFO, WARN, ERROR and FATAL. Defined Levels are ordered according to their integer values as follows: DEBUG < INFO < WARN < ERROR < FATAL.
- </para>
- <para>
- The CLF provides an extension to filter logging messages according to finer granularity an application may define. That is, when a log message is provided to the logger with the DEBUG level, additional conditions can be specified to determine if the log message is enabled or not.
- </para>
- <para>
- <orderedlist>
- <listitem>
- <para>These conditions are applied if and only the DEBUG level is enabled and the log request performed by the application specifies debugging granularity. </para>
- </listitem>
- </orderedlist>
- </para>
- <para>When enabled, Debugging is filtered conditionally on three variables: </para>
- <para><orderedlist>
- <listitem>
- <para>Debugging level: this is where the log request with the DEBUG Level is generated from, e.g., constructors or basic methods. </para>
- </listitem>
- <listitem>
- <para>Visibility level: the visibility of the constructor, method, etc. that generates the debugging. </para>
- </listitem>
- <listitem>
- <para>Facility code: for instance the package or sub-module within which debugging is generated, e.g., the object store. </para>
- </listitem>
- </orderedlist></para>
- <para>According to these variables the CLF defines three interfaces. A particular product may implement its own classes according to its own finer granularity. JBoss Transactions uses the default Debugging level and the default Visibility level provided by CLF, but it defines its own Facility Code. JBoss Transactions uses the default level assigned to its logger objects (DEBUG). However, it uses the finer debugging features to disable or enable debug messages. Finer debugging values used by the JBoss Transactions are defined below:</para>
- <para>Debugging level – JBoss Transactions uses the default values defined in the class <classname>com.arjuna.common.util.logging.DebugLevel</classname></para>
- <para><orderedlist>
- <listitem>
- <para>NO_DEBUGGING: No diagnostics. A logger object assigned with this values discard all debug requests </para>
- </listitem>
- <listitem>
- <para>FULL_DEBUGGING: Full diagnostics. A Logger object assigned with this value allows all debug requests if the facility code and the visibility level match those allowed by the logger.</para>
- </listitem>
- </orderedlist></para>
- <para>Additional Debugging Values are: </para>
- <para><orderedlist>
- <listitem>
- <para>CONSTRUCTORS: Diagnostics from constructors. </para>
- </listitem>
- <listitem>
- <para>DESTRUCTORS: Diagnostics from finalizers. </para>
- </listitem>
- <listitem>
- <para>CONSTRUCT_AND_DESTRUCT: Diagnostics from constructors and finalizers. </para>
- </listitem>
- <listitem>
- <para>FUNCTIONS: Diagnostics from functions. </para>
- </listitem>
- <listitem>
- <para>OPERATORS: Diagnostics from operators, such as equals. </para>
- </listitem>
- <listitem>
- <para>FUNCS_AND_OPS: Diagnostics from functions and operations. </para>
- </listitem>
- <listitem>
- <para>ALL_NON_TRIVIAL: Diagnostics from all non-trivial operations. </para>
- </listitem>
- <listitem>
- <para>TRIVIAL_FUNCS: Diagnostics from trivial functions. </para>
- </listitem>
- <listitem>
- <para>TRIVIAL_OPERATORS: Diagnostics from trivial operations, and operators. </para>
- </listitem>
- <listitem>
- <para>ALL_TRIVIAL: Diagnostics from all trivial operations. </para>
- </listitem>
- </orderedlist></para>
- <para>Visibility level – JBoss Transactions uses the default values defined in the class <classname>com.arjuna.common.util.logging.VisibilityLevel</classname></para>
- <para><orderedlist>
- <listitem>
- <para>VIS_NONE: No Diagnostic </para>
- </listitem>
- <listitem>
- <para>VIS_PRIVATE : only from private methods. </para>
- </listitem>
- <listitem>
- <para>VIS_PROTECTED only from protected methods. </para>
- </listitem>
- <listitem>
- <para>VIS_PUBLIC only from public methods. </para>
- </listitem>
- <listitem>
- <para>VIS_PACKAGE only from package methods. </para>
- </listitem>
- <listitem>
- <para>VIS_ALL: Full Diagnostic </para>
- </listitem>
- </orderedlist></para>
- <para>Facility Code – JBoss Transactions uses the following values defined in the class <classname>com.arjuna.common.util.logging.VisibilityLevel</classname></para>
- <para><orderedlist>
- <listitem>
- <para>FAC_ATOMIC_ACTION = 0x0000001 (atomic action core module).</para>
- </listitem>
- <listitem>
- <para>FAC_BUFFER_MAN = 0x00000004 (state management (buffer) classes).</para>
- </listitem>
- <listitem>
- <para>FAC_ABSTRACT_REC = 0x00000008 (abstract records).</para>
- </listitem>
- <listitem>
- <para>FAC_OBJECT_STORE = 0x00000010 (object store implementations).</para>
- </listitem>
- <listitem>
- <para>FAC_STATE_MAN = 0x00000020 (state management and StateManager).</para>
- </listitem>
- <listitem>
- <para>FAC_SHMEM = 0x00000040 (shared memory implementation classes).</para>
- </listitem>
- <listitem>
- <para>FAC_GENERAL = 0x00000080 (general classes).</para>
- </listitem>
- <listitem>
- <para>FAC_CRASH_RECOVERY = 0x00000800 (detailed trace of crash recovery module and classes).</para>
- </listitem>
- <listitem>
- <para>FAC_THREADING = 0x00002000 (threading classes).</para>
- </listitem>
- <listitem>
- <para>AC_JDBC = 0x00008000 (JDBC 1.0 and 2.0 support).</para>
- </listitem>
- <listitem>
- <para>FAC_RECOVERY_NORMAL = 0x00040000 (normal output for crash recovery manager).</para>
- </listitem>
- </orderedlist></para>
- <para>To ensure appropriate output, it is necessary to set some of the finer debug properties explicitly in the <filename>CommonLogging.xml</filename> file, to enable logging messages issued by the JBoss Transactions module.</para>
- <para>Messages describing the start and the periodical behavior made by the RecoveryManager are output using the INFO level. If other debug tracing is wanted, the finer debugging level should be set appropriately. For instance, the following configuration, in the CommonLogging.xml, enables all debug messages related to the Crash Recovery protocol and issued by the JBoss Transactions module. </para>
-
- <programlisting><!-- Common logging related properties. -->
-<property
- name="com.arjuna.common.util.logging.DebugLevel"
- value="0x00000000"/>
-<propertyname="com.arjuna.common.util.logging.FacilityLevel"
- value="0xffffffff"/>
-<propertyname="com.arjuna.common.util.logging.VisibilityLevel"
- value="0xffffffff"/></programlisting>
- <para><orderedlist>
- <listitem>
- <para>Two logger objects are provided, one manages I18N messages and a second does not.</para>
- </listitem>
- </orderedlist></para>
- <para>Setting the normal recovery messages to the INFO level allows the RecoveryManager producing a moderate level of reporting. If nothing is going on, it just reports the entry into each module for each periodic pass. To disable INFO messages produced by the Recovery Manager, the logging level could be set to the higher level: ERROR. Setting the level to ERROR means that the RecoveryManager will only produce error, warning or fatal messages.</para>
- </section>
-</section>
-
- <section><title>Periodic Recovery</title>
- <para>The RecoveryManager scans the ObjectStore and other locations of information, looking for transactions and resources that require, or may require recovery. The scans and recovery processing are performed by recovery modules, (instances of classes that implement the com.arjuna.ats.arjuna.recovery.RecoveryModule interface), each with responsibility for a particular category of transaction or resource. The set of recovery modules used are dynamically loaded, using properties found in the RecoveryManager property file.</para>
- <para>The interface has two methods: <literal>periodicWorkFirstPass</literal> and <literal>periodicWorkSecondPass</literal>. At an interval (defined by property <classname>com.arjuna.ats.arjuna.recovery.periodicRecoveryPeriod</classname>), the RecoveryManager will call the first pass method on each property, then wait for a brief period (defined by property <classname>com.arjuna.ats.arjuna.recovery.recoveryBackoffPeriod</classname>), then call the second pass of each module. Typically, in the first pass, the module scans (e.g. the relevant part of the ObjectStore) to find transactions or resources that are in-doubt (i.e. are part way through the commitment process). On the second pass, if any of the same items are still in-doubt, it is possible the original application process has crashed and the item is a candidate for recovery. </para>
- <para>An attempt, by the RecoveryManager, to recover a transaction that is still progressing in the original process(es) is likely to break the consistency. Accordingly, the recovery modules use a mechanism (implemented in the <classname>com.arjuna.ats.arjuna.recovery.TransactionStatusManager</classname> package) to check to see if the original process is still alive, and if the transaction is still in progress. The RecoveryManager only proceeds with recovery if the original process has gone, or, if still alive, the transaction is completed. (If a server process or machine crashes, but the transaction-initiating process survives, the transaction will complete, usually generating a warning. Recovery of such a transaction is the RecoveryManager’s responsibility).</para>
- <para>It is clearly important to set the interval periods appropriately. The total iteration time will be the sum of the <literal>periodicRecoveryPeriod</literal>, <literal>recoveryBackoffPeriod</literal> and the length of time it takes to scan the stores and to attempt recovery of any in-doubt transactions found, for all the recovery modules. The recovery attempt time may include connection timeouts while trying to communicate with processes or machines that have crashed or are inaccessible (which is why there are mechanisms in the recovery system to avoid trying to recover the same transaction for ever). The total iteration time will affect how long a resource will remain inaccessible after a failure – <literal>periodicRecoveryPeriod</literal> should be set accordingly (default is 120 seconds). The <literal>recoveryBackoffPeriod</literal> can be comparatively short (default is 10 seconds) – its purpose is mainly to reduce the number of transactions that are candidat!
es for recovery and which thus require a “call to the original process to see if they are still in progress</para>
- <para><orderedlist>
- <listitem>
- <para>In previous versions of JBoss Transactions there was no contact mechanism, and the backoff period had to be long enough to avoid catching transactions in flight at all. From 3.0, there is no such risk.</para>
- </listitem>
- </orderedlist></para>
- <para>Two recovery modules (implementations of the <classname>com.arjuna.ats.arjuna.recovery.RecoveryModule</classname> interface) are supplied with JBoss Transactions, supporting various aspects of transaction recovery including JDBC recovery. It is possible for advanced users to create their own recovery modules and register them with the Recovery Manager. The recovery modules are registered with the RecoveryManager using properties that begin with “<classname>com.arjuna.ats.arjuna.recovery.RecoveryExtension</classname>”. These will be invoked on each pass of the periodic recovery in the sort-order of the property names – it is thus possible to predict the ordering (but note that a failure in an application process might occur while a periodic recovery pass is in progress). The default Recovery Extension settings are:</para>
-
- <programlisting>com.arjuna.ats.arjuna.recovery.recoveryExtension1 =
- com.arjuna.ats.internal.ts.arjuna.recovery.AtomicActionRecoveryModule
-
-com.arjuna.ats.arjuna.recovery.recoveryExtension2 =
- com.arjuna.ats.txoj.recovery.TORecoveryModule</programlisting>
- </section>
-
- <section><title>Expired entry removal</title>
- <para>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 <classname>com.arjuna.ats.arjuna.recovery.ExpiryScanner</classname> interface. Implementations of this interface are loaded by giving the class name as the value of a property whose name begins with <classname>com.arjuna.ats.arjuna.recovery.expiryScanner</classname>. The RecoveryManager calls the <command>scan()</command> method on each loaded Expiry Scanner implementation at an interval determined by the property <classname>com.arjuna.ats.arjuna.recovery.expiryScanInterval</classname>. This value is given in hours – default is 12. An <classname>expiryScanInterval</classname> 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)</para>
- <para>The kinds of item that are scanned for expiry are:</para>
- <para>TransactionStatusManager items : one of these is created by every application process that uses JBoss Transactions – they contain the information that allows the RecoveryManager to determine if the process that initiated the transaction is still alive, and what the transaction status is. The expiry time for these is set by the property <classname>com.arjuna.ats.arjuna.recovery.transactionStatusManagerExpiryTime</classname> (in hours – default is 12, zero means never expire). The expiry time should be greater than the lifetime of any single JBoss Transactions-using process.</para>
- <para>The Expiry Scanner properties for these are:</para>
-
- <programlisting>com.arjuna.ats.arjuna.recovery.expiryScannerTransactionStatusManager =
- com.arjuna.ats.internal.ts.arjuna.recovery.ExpiredTransactionStatusManagerScanner</programlisting></section>
-</section>
-
-<section><title>Selecting the JTA implementation</title>
- <para>Two variants of the JTA implementation are now provided and accessible through the same interface. These are:</para>
- <para><orderedlist>
- <listitem>
- <para>A purely local JTA, which only allows non-distributed JTA transactions to be executed. This is the only version available with the JBoss Transactions product.</para>
- </listitem>
- <listitem>
- <para>A remote, CORBA-based JTA, which allows distributed JTA transactions to be executed. This version is only available with the ArjunaJTS product and requires a supported CORBA ORB.</para>
- </listitem>
-
- <listitem>
- <para>both of these implementations are fully compatible with the transactional JDBC driver provided with JBoss Transactions.</para>
- </listitem>
- </orderedlist></para>
- <para>In order to select the local JTA implementation it is necessary to perform the following steps:</para>
- <para><orderedlist>
- <listitem>
- <para>make sure the property <literal>com.arjuna.ats.jta.jtaTMImplementation</literal> is set to <literal>com.arjuna.ats.internal.jta.transaction.arjunacore.TransactionManagerImple</literal>.</para>
- </listitem>
- <listitem>
- <para>make sure the property <literal>com.arjuna.ats.jta.jtaUTImplementation</literal> is set to <literal>com.arjuna.ats.internal.jta.transaction.arjunacore.UserTransactionImple</literal>.</para>
- </listitem>
-
- <listitem>
- <para>these settings are the default values for the properties and do not need to be specified if the local implementation is required.</para>
- </listitem>
- </orderedlist>
- </para>
-</section>
-
-<section>
- <title>ORB specific configurations</title>
- <formalpara>
- <title>JacORB</title>
- <para>
- For JacORB to function correctly it is necessary to ensure there is a valid <filename>jacorb.properties</filename> or <filename>.jacorb_properties</filename> file in one of the following places:
- </para>
- </formalpara>
- <itemizedlist>
- <listitem>
- <para>
- The classpath.
- </para>
- </listitem>
- <listitem>
- <para>
- The home directory of the user running the JBoss Transaction Service. The home directory is retrieved using <code>System.getProperty( “user.home” );</code>
- </para>
- </listitem>
- <listitem>
- <para>
- The current directory.
- </para>
- </listitem>
- <listitem>
- <para>
- The <filename>lib</filename> directory of the JDK used to run your application. This is retrieved using <code>System.getProperty( “java.home” );</code>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- The above places are searched in the order given. A template <filename>jacorb.properties</filename> file can be found in the JacORB installation directory.
- </para>
- <para>
- Within the JacORB properties file there are two important properties which must be tailored to suit your application, they are:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <property>jacorb.poa.thread_pool_max</property>
- </para>
- </listitem>
- <listitem>
- <para>
- <property>jacorb.poa.thread_pool_min</property>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- These properties specify the minimum and maximum number of request processing threads that JacORB will use in its thread pool. If there aren’t a sufficient number of threads available in this thread pool then the application may appear to become deadlocked. For more information on configuring JacORB please reference the JacORB documentation.
- </para>
- <note>
- <para>
- JacORB comes with its own implementation of the classes defined in the <filename>CosTransactions.idl</filename> file. Unfortunately these are incompatible with the version shipped with JBossTS. Therefore, it is important that the JBossTS jar files appear in the <code>CLASSPATH</code> before any JacORB jars.
- </para>
- </note>
- <para>
- When running the recovery manager it is important that it always uses the same well known port for each machine on which it runs. You should not use the OAPort property provided by JacORB unless the recovery manager has its own <filename>jacorb.properties</filename> file or this is provided on the command line when starting the recovery manager. If the recovery manager and other components of JBossTS share the same <filename>jacorb.properties</filename> file, then you should use the <filename>com.arjuna.ats.jts.recoveryManagerPort</filename> and <filename>com.arjuna.ats.jts.recoveryManagerAddress</filename> properties.
- </para>
-</section>
-
-<section>
- <title>Initializing JBossTS applications</title>
- <para>
- It is important that JBossTS is correctly initialized prior to any application object being created. In order to guarantee this, the programmer should use the <methodname>ORB_init</methodname> and <methodname>create_POA</methodname> methods. <!-- described in the Orb Portability Guide. Consult the Orb Portability Guide if direct use of the <methodname>ORB_init</methodname> and <methodname>create_POA</methodname> methods provided by the underlying ORB is required. -->
- </para>
-</section>
-
-<section><title>Errors and Exceptions</title>
- <para>In this section we shall cover the types of errors and exceptions which may be thrown or reported during a transactional application and give probable indications of their causes.</para>
- <para><orderedlist>
- <listitem>
- <para>NO_MEMORY: the application has run out of memory (thrown an <classname>OutOfMemoryError</classname>) and JBoss Transactions has attempted to do some cleanup (by running the garbage collector) before re-throwing the exception. This is probably a transient problem and retrying the invocation should succeed.</para>
- </listitem>
- <listitem>
- <para>com.arjuna.ats.arjuna.exceptions.FatalError: an error has occurred which means that the transaction system must shut down. Prior to this error being thrown the transaction service will have ensured that all running transactions have rolled back. If caught, the application should tidy up and exit. If further work is attempted, application consistency may be violated.</para>
- </listitem>
- <listitem>
- <para>com.arjuna.ats.arjuna.exceptions.LicenceError: an attempt has been made to use the transaction service in a manner inconsistent with the current licence. The transaction service will not allow further forward progress for existing or new transactions.</para>
- </listitem>
- <listitem>
- <para>com.arjuna.ats.arjuna.exceptions.ObjectStoreError: an error occurred while the transaction service attempted to use the object store. Further forward progress is not possible.</para>
- </listitem>
- <listitem>
- <para>Object store warnings about access problems on states may occur during the normal execution of crash recovery. This is the result of multiple concurrent attempts to perform recovery on the same transaction. It can be safely ignored. </para>
- </listitem>
- </orderedlist></para>
-</section>
-</chapter>
-
-
-
-
-
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Errors_And_Exceptions.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Errors_And_Exceptions.xml (rev 0)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Errors_And_Exceptions.xml 2010-04-06 07:38:50 UTC (rev 32438)
@@ -0,0 +1,26 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<chapter>
+<title>Errors and Exceptions</title>
+ <para>In this section we shall cover the types of errors and exceptions which may be thrown or reported during a transactional application and give probable indications of their causes.</para>
+ <para><orderedlist>
+ <listitem>
+ <para>NO_MEMORY: the application has run out of memory (thrown an <classname>OutOfMemoryError</classname>) and JBoss Transactions has attempted to do some cleanup (by running the garbage collector) before re-throwing the exception. This is probably a transient problem and retrying the invocation should succeed.</para>
+ </listitem>
+ <listitem>
+ <para>com.arjuna.ats.arjuna.exceptions.FatalError: an error has occurred which means that the transaction system must shut down. Prior to this error being thrown the transaction service will have ensured that all running transactions have rolled back. If caught, the application should tidy up and exit. If further work is attempted, application consistency may be violated.</para>
+ </listitem>
+ <listitem>
+ <para>com.arjuna.ats.arjuna.exceptions.LicenceError: an attempt has been made to use the transaction service in a manner inconsistent with the current licence. The transaction service will not allow further forward progress for existing or new transactions.</para>
+ </listitem>
+ <listitem>
+ <para>com.arjuna.ats.arjuna.exceptions.ObjectStoreError: an error occurred while the transaction service attempted to use the object store. Further forward progress is not possible.</para>
+ </listitem>
+ <listitem>
+ <para>Object store warnings about access problems on states may occur during the normal execution of crash recovery. This is the result of multiple concurrent attempts to perform recovery on the same transaction. It can be safely ignored. </para>
+ </listitem>
+ </orderedlist></para>
+
+
+</chapter>
\ No newline at end of file
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Failure_Recovery.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Failure_Recovery.xml (rev 0)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Failure_Recovery.xml 2010-04-06 07:38:50 UTC (rev 32438)
@@ -0,0 +1,203 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<chapter>
+<title>Failure recovery administration</title>
+ <para>The failure recovery subsystem of JBoss Transactions 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.</para>
+ <para><orderedlist>
+ <listitem>
+ <para>If the ObjectStore is destroyed or modified, recovery may not be possible.</para>
+ </listitem>
+ </orderedlist></para>
+ <para>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”. For TransactionalObjects for Java resources, an attempt to activate the Transactional Object (as when trying to get a lock) will fail.</para>
+
+ <section><title>The Recovery Manager</title>
+ <para>The failure recovery subsystem of JBoss Transactions requires that the stand-alone Recovery Manager process be running for each ObjectStore (typically one for each node on the network that is running JBoss Transactions applications). The RecoveryManager file is located in the arjunacore jar file within the package <classname>com.arjuna.ats.arjuna.recovery.RecoveryManager</classname>. To start the Recovery Manager issue the following command:</para>
+ <para><command>java com.arjuna.ats.arjuna.recovery.RecoveryManager</command></para>
+ <para>If the <literal>-test</literal> flag is used with the Recovery Manager then it will display a “Ready” message when initialised, i.e.,</para>
+ <para><command>java com.arjuna.ats.arjuna.recovery.RecoveryManager -test</command></para>
+ </section>
+
+ <section><title>Configuring the Recovery Manager</title>
+ <para>The RecoveryManager reads the properties defined in the <filename>arjuna.properties</filename> file and then also reads the property file <filename>RecoveryManager.properties</filename>, from the same directory as it found the arjuna properties file. An entry for a property in the RecoveryManager properties file will override an entry for the same property in the main TransactionService properties file. Most of the entries are specific to the Recovery Manager.</para>
+ <para>A default version of <filename>RecoveryManager.properties</filename> is supplied with the distribution – this can be used without modification, except possibly the debug tracing fields (see below, Output). The rest of this section discusses the issues relevant in setting the properties to other values (in the order of their appearance in the default version of the file)</para>
+
+ <section><title>Output</title>
+ <para>
+ It is likely that installations will want to have some form of output from the RecoveryManager, to provide a record of what recovery activity has taken place. RecoveryManager uses the logging tracing mechanism provided by the Arjuna Common Logging Framework (CLF), which provides a high level interface that hides differences that exist between existing logging APIs such Jakarta log4j or JDK 1.4 logging API. CLF indirects all logging via the Apache Commons Logging framework and configuration is assumed to occur through that framework.
+ </para>
+ <para>
+ With the CLF applications make logging calls on logger objects. Loggers may use logging Levels to decide if they are interested in a particular log message. Each log message has an associated log Level, that gives the importance and urgency of a log message. The set of possible Log Levels are DEBUG, INFO, WARN, ERROR and FATAL. Defined Levels are ordered according to their integer values as follows: DEBUG < INFO < WARN < ERROR < FATAL.
+ </para>
+ <para>
+ The CLF provides an extension to filter logging messages according to finer granularity an application may define. That is, when a log message is provided to the logger with the DEBUG level, additional conditions can be specified to determine if the log message is enabled or not.
+ </para>
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>These conditions are applied if and only the DEBUG level is enabled and the log request performed by the application specifies debugging granularity. </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ <para>When enabled, Debugging is filtered conditionally on three variables: </para>
+ <para><orderedlist>
+ <listitem>
+ <para>Debugging level: this is where the log request with the DEBUG Level is generated from, e.g., constructors or basic methods. </para>
+ </listitem>
+ <listitem>
+ <para>Visibility level: the visibility of the constructor, method, etc. that generates the debugging. </para>
+ </listitem>
+ <listitem>
+ <para>Facility code: for instance the package or sub-module within which debugging is generated, e.g., the object store. </para>
+ </listitem>
+ </orderedlist></para>
+ <para>According to these variables the CLF defines three interfaces. A particular product may implement its own classes according to its own finer granularity. JBoss Transactions uses the default Debugging level and the default Visibility level provided by CLF, but it defines its own Facility Code. JBoss Transactions uses the default level assigned to its logger objects (DEBUG). However, it uses the finer debugging features to disable or enable debug messages. Finer debugging values used by the JBoss Transactions are defined below:</para>
+ <para>Debugging level – JBoss Transactions uses the default values defined in the class <classname>com.arjuna.common.util.logging.DebugLevel</classname></para>
+ <para><orderedlist>
+ <listitem>
+ <para>NO_DEBUGGING: No diagnostics. A logger object assigned with this values discard all debug requests </para>
+ </listitem>
+ <listitem>
+ <para>FULL_DEBUGGING: Full diagnostics. A Logger object assigned with this value allows all debug requests if the facility code and the visibility level match those allowed by the logger.</para>
+ </listitem>
+ </orderedlist></para>
+ <para>Additional Debugging Values are: </para>
+ <para><orderedlist>
+ <listitem>
+ <para>CONSTRUCTORS: Diagnostics from constructors. </para>
+ </listitem>
+ <listitem>
+ <para>DESTRUCTORS: Diagnostics from finalizers. </para>
+ </listitem>
+ <listitem>
+ <para>CONSTRUCT_AND_DESTRUCT: Diagnostics from constructors and finalizers. </para>
+ </listitem>
+ <listitem>
+ <para>FUNCTIONS: Diagnostics from functions. </para>
+ </listitem>
+ <listitem>
+ <para>OPERATORS: Diagnostics from operators, such as equals. </para>
+ </listitem>
+ <listitem>
+ <para>FUNCS_AND_OPS: Diagnostics from functions and operations. </para>
+ </listitem>
+ <listitem>
+ <para>ALL_NON_TRIVIAL: Diagnostics from all non-trivial operations. </para>
+ </listitem>
+ <listitem>
+ <para>TRIVIAL_FUNCS: Diagnostics from trivial functions. </para>
+ </listitem>
+ <listitem>
+ <para>TRIVIAL_OPERATORS: Diagnostics from trivial operations, and operators. </para>
+ </listitem>
+ <listitem>
+ <para>ALL_TRIVIAL: Diagnostics from all trivial operations. </para>
+ </listitem>
+ </orderedlist></para>
+ <para>Visibility level – JBoss Transactions uses the default values defined in the class <classname>com.arjuna.common.util.logging.VisibilityLevel</classname></para>
+ <para><orderedlist>
+ <listitem>
+ <para>VIS_NONE: No Diagnostic </para>
+ </listitem>
+ <listitem>
+ <para>VIS_PRIVATE : only from private methods. </para>
+ </listitem>
+ <listitem>
+ <para>VIS_PROTECTED only from protected methods. </para>
+ </listitem>
+ <listitem>
+ <para>VIS_PUBLIC only from public methods. </para>
+ </listitem>
+ <listitem>
+ <para>VIS_PACKAGE only from package methods. </para>
+ </listitem>
+ <listitem>
+ <para>VIS_ALL: Full Diagnostic </para>
+ </listitem>
+ </orderedlist></para>
+ <para>Facility Code – JBoss Transactions uses the following values defined in the class <classname>com.arjuna.common.util.logging.VisibilityLevel</classname></para>
+ <para><orderedlist>
+ <listitem>
+ <para>FAC_ATOMIC_ACTION = 0x0000001 (atomic action core module).</para>
+ </listitem>
+ <listitem>
+ <para>FAC_BUFFER_MAN = 0x00000004 (state management (buffer) classes).</para>
+ </listitem>
+ <listitem>
+ <para>FAC_ABSTRACT_REC = 0x00000008 (abstract records).</para>
+ </listitem>
+ <listitem>
+ <para>FAC_OBJECT_STORE = 0x00000010 (object store implementations).</para>
+ </listitem>
+ <listitem>
+ <para>FAC_STATE_MAN = 0x00000020 (state management and StateManager).</para>
+ </listitem>
+ <listitem>
+ <para>FAC_SHMEM = 0x00000040 (shared memory implementation classes).</para>
+ </listitem>
+ <listitem>
+ <para>FAC_GENERAL = 0x00000080 (general classes).</para>
+ </listitem>
+ <listitem>
+ <para>FAC_CRASH_RECOVERY = 0x00000800 (detailed trace of crash recovery module and classes).</para>
+ </listitem>
+ <listitem>
+ <para>FAC_THREADING = 0x00002000 (threading classes).</para>
+ </listitem>
+ <listitem>
+ <para>AC_JDBC = 0x00008000 (JDBC 1.0 and 2.0 support).</para>
+ </listitem>
+ <listitem>
+ <para>FAC_RECOVERY_NORMAL = 0x00040000 (normal output for crash recovery manager).</para>
+ </listitem>
+ </orderedlist></para>
+ <para>To ensure appropriate output, it is necessary to set some of the finer debug properties explicitly in the <filename>CommonLogging.xml</filename> file, to enable logging messages issued by the JBoss Transactions module.</para>
+ <para>Messages describing the start and the periodical behavior made by the RecoveryManager are output using the INFO level. If other debug tracing is wanted, the finer debugging level should be set appropriately. For instance, the following configuration, in the CommonLogging.xml, enables all debug messages related to the Crash Recovery protocol and issued by the JBoss Transactions module. </para>
+
+ <programlisting><!-- Common logging related properties. -->
+ <property
+ name="com.arjuna.common.util.logging.DebugLevel"
+ value="0x00000000"/>
+ <propertyname="com.arjuna.common.util.logging.FacilityLevel"
+ value="0xffffffff"/>
+ <propertyname="com.arjuna.common.util.logging.VisibilityLevel"
+ value="0xffffffff"/></programlisting>
+ <para><orderedlist>
+ <listitem>
+ <para>Two logger objects are provided, one manages I18N messages and a second does not.</para>
+ </listitem>
+ </orderedlist></para>
+ <para>Setting the normal recovery messages to the INFO level allows the RecoveryManager producing a moderate level of reporting. If nothing is going on, it just reports the entry into each module for each periodic pass. To disable INFO messages produced by the Recovery Manager, the logging level could be set to the higher level: ERROR. Setting the level to ERROR means that the RecoveryManager will only produce error, warning or fatal messages.</para>
+</section>
+</section>
+
+<section><title>Periodic Recovery</title>
+<para>The RecoveryManager scans the ObjectStore and other locations of information, looking for transactions and resources that require, or may require recovery. The scans and recovery processing are performed by recovery modules, (instances of classes that implement the com.arjuna.ats.arjuna.recovery.RecoveryModule interface), each with responsibility for a particular category of transaction or resource. The set of recovery modules used are dynamically loaded, using properties found in the RecoveryManager property file.</para>
+<para>The interface has two methods: <literal>periodicWorkFirstPass</literal> and <literal>periodicWorkSecondPass</literal>. At an interval (defined by property <classname>com.arjuna.ats.arjuna.recovery.periodicRecoveryPeriod</classname>), the RecoveryManager will call the first pass method on each property, then wait for a brief period (defined by property <classname>com.arjuna.ats.arjuna.recovery.recoveryBackoffPeriod</classname>), then call the second pass of each module. Typically, in the first pass, the module scans (e.g. the relevant part of the ObjectStore) to find transactions or resources that are in-doubt (i.e. are part way through the commitment process). On the second pass, if any of the same items are still in-doubt, it is possible the original application process has crashed and the item is a candidate for recovery. </para>
+<para>An attempt, by the RecoveryManager, to recover a transaction that is still progressing in the original process(es) is likely to break the consistency. Accordingly, the recovery modules use a mechanism (implemented in the <classname>com.arjuna.ats.arjuna.recovery.TransactionStatusManager</classname> package) to check to see if the original process is still alive, and if the transaction is still in progress. The RecoveryManager only proceeds with recovery if the original process has gone, or, if still alive, the transaction is completed. (If a server process or machine crashes, but the transaction-initiating process survives, the transaction will complete, usually generating a warning. Recovery of such a transaction is the RecoveryManager’s responsibility).</para>
+<para>It is clearly important to set the interval periods appropriately. The total iteration time will be the sum of the <literal>periodicRecoveryPeriod</literal>, <literal>recoveryBackoffPeriod</literal> and the length of time it takes to scan the stores and to attempt recovery of any in-doubt transactions found, for all the recovery modules. The recovery attempt time may include connection timeouts while trying to communicate with processes or machines that have crashed or are inaccessible (which is why there are mechanisms in the recovery system to avoid trying to recover the same transaction for ever). The total iteration time will affect how long a resource will remain inaccessible after a failure – <literal>periodicRecoveryPeriod</literal> should be set accordingly (default is 120 seconds). The <literal>recoveryBackoffPeriod</literal> can be comparatively short (default is 10 seconds) – its purpose is mainly to reduce the number of transactions that are candidates!
for recovery and which thus require a “call to the original process to see if they are still in progress</para>
+<para><orderedlist>
+ <listitem>
+ <para>In previous versions of JBoss Transactions there was no contact mechanism, and the backoff period had to be long enough to avoid catching transactions in flight at all. From 3.0, there is no such risk.</para>
+ </listitem>
+</orderedlist></para>
+<para>Two recovery modules (implementations of the <classname>com.arjuna.ats.arjuna.recovery.RecoveryModule</classname> interface) are supplied with JBoss Transactions, supporting various aspects of transaction recovery including JDBC recovery. It is possible for advanced users to create their own recovery modules and register them with the Recovery Manager. The recovery modules are registered with the RecoveryManager using properties that begin with “<classname>com.arjuna.ats.arjuna.recovery.RecoveryExtension</classname>”. These will be invoked on each pass of the periodic recovery in the sort-order of the property names – it is thus possible to predict the ordering (but note that a failure in an application process might occur while a periodic recovery pass is in progress). The default Recovery Extension settings are:</para>
+
+<programlisting>com.arjuna.ats.arjuna.recovery.recoveryExtension1 =
+com.arjuna.ats.internal.ts.arjuna.recovery.AtomicActionRecoveryModule
+
+com.arjuna.ats.arjuna.recovery.recoveryExtension2 =
+com.arjuna.ats.txoj.recovery.TORecoveryModule</programlisting>
+</section>
+
+<section><title>Expired entry removal</title>
+<para>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 <classname>com.arjuna.ats.arjuna.recovery.ExpiryScanner</classname> interface. Implementations of this interface are loaded by giving the class name as the value of a property whose name begins with <classname>com.arjuna.ats.arjuna.recovery.expiryScanner</classname>. The RecoveryManager calls the <command>scan()</command> method on each loaded Expiry Scanner implementation at an interval determined by the property <classname>com.arjuna.ats.arjuna.recovery.expiryScanInterval</classname>. This value is given in hours – default is 12. An <classname>expiryScanInterval</classname> value of zero will suppress any expiry scanning. If the value as supplied is positive, the first scan i!
s performed when RecoveryManager starts; if the value is negative, the first scan is delayed until after the first interval (using the absolute value)</para>
+<para>The kinds of item that are scanned for expiry are:</para>
+<para>TransactionStatusManager items : one of these is created by every application process that uses JBoss Transactions – they contain the information that allows the RecoveryManager to determine if the process that initiated the transaction is still alive, and what the transaction status is. The expiry time for these is set by the property <classname>com.arjuna.ats.arjuna.recovery.transactionStatusManagerExpiryTime</classname> (in hours – default is 12, zero means never expire). The expiry time should be greater than the lifetime of any single JBoss Transactions-using process.</para>
+<para>The Expiry Scanner properties for these are:</para>
+
+<programlisting>com.arjuna.ats.arjuna.recovery.expiryScannerTransactionStatusManager =
+com.arjuna.ats.internal.ts.arjuna.recovery.ExpiredTransactionStatusManagerScanner</programlisting></section>
+
+</chapter>
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Initializing_JBossTS_Applications.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Initializing_JBossTS_Applications.xml (rev 0)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Initializing_JBossTS_Applications.xml 2010-04-06 07:38:50 UTC (rev 32438)
@@ -0,0 +1,11 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<chapter>
+ <title>Initializing JBossTS applications</title>
+ <para>
+ It is important that JBossTS is correctly initialized prior to any application object being created. In order to guarantee this, the programmer should use the <methodname>ORB_init</methodname> and <methodname>create_POA</methodname> methods. <!-- described in the Orb Portability Guide. Consult the Orb Portability Guide if direct use of the <methodname>ORB_init</methodname> and <methodname>create_POA</methodname> methods provided by the underlying ORB is required. -->
+ </para>
+
+
+</chapter>
\ No newline at end of file
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Intro.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Intro.xml (rev 0)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Intro.xml 2010-04-06 07:38:50 UTC (rev 32438)
@@ -0,0 +1,20 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<chapter><title>Introduction</title>
+<para>Apart from ensuring that the run-time system is executing normally, there is little continuous administration needed for the JBoss Transactions software. There are a few points however, that should be made:</para>
+<para><orderedlist>
+ <listitem>
+ <para>The present implementation of the JBoss TA system provides no security or protection for data. The objects stored in the JBoss Transactions object store are (typically) owned by the user who ran the application that created them. The Object Store and Object Manager facilities make no attempt to enforce even the limited form of protection that Unix/Windows provides. There is no checking of user or group IDs on access to objects for either reading or writing.</para>
+ </listitem>
+ <listitem>
+ <para>Persistent objects created in the Object Store never go away unless the StateManager.destroy method is invoked on the object or some application program explicitly deletes them. This means that the Object Store gradually accumulates garbage (especially during application development and testing phases). At present we have no automated garbage collection facility. Further, we have not addressed the problem of dangling references. That is, a persistent object, A, may have stored a Uid for another persistent object, B, in its passive representation on disk. There is nothing to prevent an application from deleting B even though A still contains a reference to it. When A is next activated and attempts to access B, a run-time error will occur.</para>
+ </listitem>
+ <listitem>
+ <para>There is presently no support for version control of objects or database reconfiguration in the event of class structure changes. This is a complex research area that we have not addressed. At present, if you change the definition of a class of persistent objects, you are entirely responsible for ensuring that existing instances of the object in the Object Store are converted to the new representation. The JBoss Transactions software can neither detect nor correct references to old object state by new operation versions or vice versa.</para>
+ </listitem>
+ <listitem>
+ <para>Object store management is critically important to the transaction service.</para>
+ </listitem>
+</orderedlist></para>
+</chapter>
\ No newline at end of file
Modified: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/JBoss_Transactions_Administrators_Guide.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/JBoss_Transactions_Administrators_Guide.xml 2010-04-06 07:37:56 UTC (rev 32437)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/JBoss_Transactions_Administrators_Guide.xml 2010-04-06 07:38:50 UTC (rev 32438)
@@ -5,7 +5,26 @@
<book>
<xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Chapter.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+<!-- <xi:include href="Chapter.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />-->
+ <xi:include href="Intro.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Objectstore_Management.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Transaction_Service_Management.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="XA_Specific_Service_Managenent.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Web_Service_Specific_Management.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Runtime_Information.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <!--<xi:include href="Failure_Recovery.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />-->
+ <xi:include href="xa_recovery.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="Selecting_the_JTA_Implementation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="ORB_Specific_Configurations.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Initializing_JBossTS_Applications.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Errors_And_Exceptions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+
+
+
+
+
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Revision_History.xml"/>
</book>
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/ORB_Specific_Configurations.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/ORB_Specific_Configurations.xml (rev 0)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/ORB_Specific_Configurations.xml 2010-04-06 07:38:50 UTC (rev 32438)
@@ -0,0 +1,65 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<chapter>
+ <title>ORB specific configurations</title>
+ <formalpara>
+ <title>JacORB</title>
+ <para>
+ For JacORB to function correctly it is necessary to ensure there is a valid <filename>jacorb.properties</filename> or <filename>.jacorb_properties</filename> file in one of the following places:
+ </para>
+ </formalpara>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The classpath.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The home directory of the user running the JBoss Transaction Service. The home directory is retrieved using <code>System.getProperty( “user.home” );</code>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The current directory.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <filename>lib</filename> directory of the JDK used to run your application. This is retrieved using <code>System.getProperty( “java.home” );</code>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ The above places are searched in the order given. A template <filename>jacorb.properties</filename> file can be found in the JacORB installation directory.
+ </para>
+ <para>
+ Within the JacORB properties file there are two important properties which must be tailored to suit your application, they are:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <property>jacorb.poa.thread_pool_max</property>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <property>jacorb.poa.thread_pool_min</property>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ These properties specify the minimum and maximum number of request processing threads that JacORB will use in its thread pool. If there aren’t a sufficient number of threads available in this thread pool then the application may appear to become deadlocked. For more information on configuring JacORB please reference the JacORB documentation.
+ </para>
+ <note>
+ <para>
+ JacORB comes with its own implementation of the classes defined in the <filename>CosTransactions.idl</filename> file. Unfortunately these are incompatible with the version shipped with JBossTS. Therefore, it is important that the JBossTS jar files appear in the <code>CLASSPATH</code> before any JacORB jars.
+ </para>
+ </note>
+ <para>
+ When running the recovery manager it is important that it always uses the same well known port for each machine on which it runs. You should not use the OAPort property provided by JacORB unless the recovery manager has its own <filename>jacorb.properties</filename> file or this is provided on the command line when starting the recovery manager. If the recovery manager and other components of JBossTS share the same <filename>jacorb.properties</filename> file, then you should use the <filename>com.arjuna.ats.jts.recoveryManagerPort</filename> and <filename>com.arjuna.ats.jts.recoveryManagerAddress</filename> properties.
+ </para>
+
+
+</chapter>
\ No newline at end of file
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Objectstore_Management.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Objectstore_Management.xml (rev 0)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Objectstore_Management.xml 2010-04-06 07:38:50 UTC (rev 32438)
@@ -0,0 +1,33 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<chapter>
+ <title>ObjectStore management</title>
+ <para>Within the transaction service installation, the object store is updated regularly whenever transactions are created, or when Transactional Objects for Java is used. In a failure free environment, the only object states which should reside within the object store are those representing objects created with the Transactional Objects for Java API. However, if failures occur, transaction logs may remain in the object store until crash recovery facilities have resolved the transactions they represent. As such it is very important that the contents of the object store are not deleted without due care and attention, as this will make it impossible to resolve in doubt transactions. In addition, if multiple users share the same object store it is important that they realise this and do not simply delete the contents of the object store assuming it is an exclusive resource.</para>
+ <para>
+ Apart from ensuring that the run-time system is executing normally, there is little continuous administration needed for the JBossTS software. There are a few points however, that should be made:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The present implementation of the JBossTS system provides no security or protection for data. It is recommended that the objects stored in the JBossTS are owned by user arjuna. The Object Store and Object Manager facilities make no attempt to enforce even the limited form of protection that Unix and Windows provides. There is no checking of user or group IDs on access to objects for either reading or writing.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Persistent objects created in the Object Store never go away unless the <methodname>StateManager.destroy</methodname> method is invoked on the object or some application program explicitly deletes them. This means that the Object Store gradually accumulates garbage (especially during application development and testing phases). At present we have no automated garbage collection facility. Further, we have not addressed the problem of dangling references. That is, a persistent object, A, may have stored a UID for another persistent object, B, in its passive representation on disk. There is nothing to prevent an application from deleting B even though A still contains a reference to it. When A is next activated and attempts to access B, a run-time error will occur.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ There is presently no support for version control of objects or database reconfiguration in the event of class structure changes. This is a complex research area that we have not addressed. At present, if you change the definition of a class of persistent objects, you are entirely responsible for ensuring that existing instances of the object in the Object Store are converted to the new representation. The JBossTS software can neither detect nor correct references to old object state by new operation versions or vice versa.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Object store management is critically important to the transaction service.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+</chapter>
\ No newline at end of file
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Runtime_Information.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Runtime_Information.xml (rev 0)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Runtime_Information.xml 2010-04-06 07:38:50 UTC (rev 32438)
@@ -0,0 +1,23 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<chapter>
+<title>JBoss Transactions runtime information</title>
+ <para>Each module that comprises JBoss Transactions possesses a class called Info. These classes all provide a single toString method that returns an XML document representing the configuration information for that module. So, for example:</para>
+
+ <programlisting><module-info name="arjuna">
+ <source-identifier>unknown</source-identifier>
+ <build-information>
+ Arjuna Technologies [mlittle] (Windows 2000 5.0)
+ </build-information>
+ <version>unknown</version>
+ <date>2002/06/15 04:06 PM</date>
+ <notes></notes>
+ <configuration>
+ <properties-file dir="null">arjuna.properties</properties-file>
+ <object-store-root>null</object-store-root>
+ </configuration>
+ </module-info></programlisting>
+
+
+</chapter>
\ No newline at end of file
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Selecting_the_JTA_Implementation.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Selecting_the_JTA_Implementation.xml (rev 0)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Selecting_the_JTA_Implementation.xml 2010-04-06 07:38:50 UTC (rev 32438)
@@ -0,0 +1,36 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<chapter>
+<title>Selecting the JTA implementation</title>
+ <para>Two variants of the JTA implementation are now provided and accessible through the same interface. These are:</para>
+ <para><orderedlist>
+ <listitem>
+ <para>A purely local JTA, which only allows non-distributed JTA transactions to be executed. This is the only version available with the JBoss Transactions product.</para>
+ </listitem>
+ <listitem>
+ <para>A remote, CORBA-based JTA, which allows distributed JTA transactions to be executed. This version is only available with the ArjunaJTS product and requires a supported CORBA ORB.</para>
+ </listitem>
+
+ <listitem>
+ <para>both of these implementations are fully compatible with the transactional JDBC driver provided with JBoss Transactions.</para>
+ </listitem>
+ </orderedlist></para>
+ <para>In order to select the local JTA implementation it is necessary to perform the following steps:</para>
+ <para><orderedlist>
+ <listitem>
+ <para>make sure the property <literal>com.arjuna.ats.jta.jtaTMImplementation</literal> is set to <literal>com.arjuna.ats.internal.jta.transaction.arjunacore.TransactionManagerImple</literal>.</para>
+ </listitem>
+ <listitem>
+ <para>make sure the property <literal>com.arjuna.ats.jta.jtaUTImplementation</literal> is set to <literal>com.arjuna.ats.internal.jta.transaction.arjunacore.UserTransactionImple</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para>these settings are the default values for the properties and do not need to be specified if the local implementation is required.</para>
+ </listitem>
+ </orderedlist>
+ </para>
+
+
+
+</chapter>
\ No newline at end of file
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Starting_and_Stopping.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Starting_and_Stopping.xml (rev 0)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Starting_and_Stopping.xml 2010-04-06 07:38:50 UTC (rev 32438)
@@ -0,0 +1,22 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<chapter>
+ <title>Starting and Stopping the transaction manager</title>
+
+ <para>
+ By default the transaction manager starts up in an active state such that new transactions can be created immediately. If you wish to have more control over this it is possible to set the <property>com.arjuna.ats.arjuna.coordinator.startDisabled</property> configuration option to <literal>YES</literal>, in which case no transactions can be created until the transaction manager is enabled (via a call to <methodname>TxControl.enable</methodname>).
+ </para>
+ <para>
+ It is possible to stop the creation of new transactions at any time by calling <methodname>TxControl.disable</methodname>. Transactions that are currently executing will not be affected. By default recovery will be allowed to continue and the transaction system will still be available to manage recovery requests from other instances in a distributed environment. (See the Failure Recovery Guide for further details). However, if you wish to disable recovery as well as remove any resources it maintains, then you can pass true to <methodname>TxControl.disable</methodname>; the default is to use <literal>false</literal>.
+ </para>
+ <para>
+ If you wish to shut the system down completely then it may also be necessary to terminate the background transaction reaper (see the Programmers Guide for information about what the reaper does.) In order to do this you may want to first prevent the creation of new transactions (if you are not creating transactions with timeouts then this step is not necessary) using <methodname>TxControl.disable</methodname>. Then you should call <methodname>TransactionReaper.terminate</methodname>. This method takes a boolean parameter: if true then the method will wait for the normal timeout periods associated with any transactions to expire before terminating the transactions; if false then transactions will be forced to terminate (rollback or have their outcome set such that they can only ever rollback) immediately.
+ </para>
+ <important>
+ <para>
+ If you intent to restart the recovery manager later after having terminated it then you <emphasis>must</emphasis> use the <methodname>terminate</methodname> method with <property>asynchronous behavior</property> set to <literal>false</literal> when shutting down the recovery manager.
+ </para>
+ </important>
+
+</chapter>
\ No newline at end of file
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Transaction_Service_Management.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Transaction_Service_Management.xml (rev 0)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Transaction_Service_Management.xml 2010-04-06 07:38:50 UTC (rev 32438)
@@ -0,0 +1,106 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<chapter>
+ <title>OTS and J2EE Transaction service management </title>
+
+ <section>
+ <title>Starting the run-time system</title>
+ <para>
+ The JBossTS run-time support consists of run-time packages and the OTS transaction manager server. By default JBossTS does not use a separate transaction manager server: transaction managers are co-located with each application process to improve performance and improve application fault-tolerance (the application is no longer dependant upon another service in order to function correctly).
+ </para>
+ <para>
+ When running applications which require a separate transaction manager, you must set the <varname>com.arjuna.ats.jts.transactionManager</varname> environment variable to have the value <literal>yes</literal>. The system will then locate the transaction manager server in a manner specific to the ORB being used. The server can be located in a number of ways: by being registered with a name server, added to the ORB’s initial references, via a JBossTS specific references file, or by the ORB’s specific location mechanism (if applicable).
+ </para>
+ <para>
+ It is possible to override the default registration mechanism by using the <varname>com.arjuna.orbportability.resolveService</varname> environment variable. This can have one of the following values:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>CONFIGURATION_FILE</literal>: the default, this causes the system to use the <filename>CosServices.cfg</filename> file.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>NAME_SERVICE</literal>: JBossTS will attempt to use a name service to register the transaction factory. If this is not supported, an exception will be thrown.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>BIND_CONNECT</literal>: JBossTS will use the ORB-specific bind mechanism. If this is not supported, an exception will be thrown.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>RESOLVE_INITIAL_REFERENCES</literal>: JBossTS will attempt to register the transaction service with the ORBs initial service references.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <note>
+ <para>
+ This may not be supported on all ORBs. An exception will be thrown in that case and another option will have to be used.
+ </para>
+ </note>
+ <formalpara>
+ <title>OTS configuration file</title>
+ <para>
+ Similar to the resolve_initial_references, JBossTS supports an initial reference file where references for specific services can be stored and used at runtime. The file, CosServices.cfg, consists of two columns: the service name (in the case of the OTS server TransactionService) and the IOR, separated by a single space. CosServices.cfg normally resides in the etc directory of the JBossTS installation; the actual location is determined at runtime by searching the CLASSPATH for an old copy of the file resident within an etc directory, or, if one is not found, the location of the TransactionService properties file directory.
+ </para>
+ </formalpara>
+ <para>
+ The OTS server will automatically register itself in this file (creating it if necessary) if this option is being used. Stale information is also automatically removed. Machines which wish to share the same transaction server should have access to (or a copy of) this file.
+ </para>
+ <para>
+ The name and location of the file can be overridden using the <property>com.arjuna.orbportability.initialReferencesFile</property> and <property>com.arjuna.orbportability.initialReferencesRoot</property> property variables, respectively. It is recommended that the <property>com.arjuna.orbportability.initialReferencesRoot</property> variable is set. For example:
+ </para>
+ <screen>
+ com.arjuna.orbportability.initialReferencesFile=myFile
+ com.arjuna.orbportability.initialReferencesRoot=c:\\temp
+ </screen>
+ <formalpara>
+ <title>Name Service</title>
+ <para>
+ If the ORB you are using supports a name service, and JBossTS has been configured to use it, then the transaction manager will automatically be registered with it. There is no further work required. This option is not used for JacORB
+ </para>
+ </formalpara>
+ <formalpara>
+ <title>resolve_initial_references</title>
+ <para>
+ Currently this option is only supported for JacORB.
+ </para>
+ </formalpara>
+ <formalpara>
+ <title>Resolution service table</title>
+ <para>
+ The following table summarizes the different ways in which the OTS transaction manager may be located on specific ORBs:
+ </para>
+ </formalpara>
+ <table>
+ <title>Locating the OTS transaction manager server</title>
+ <tgroup cols='2' align='left' colsep='1' rowsep='1'>
+ <thead>
+ <row>
+ <entry>Resolution Mechanism</entry>
+ <entry>ORB</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>OTS configuration file</entry>
+ <entry>All available ORBs</entry>
+ </row>
+ <row>
+ <entry>Name Service</entry>
+ <entry>JacORB</entry>
+ </row>
+ <row>
+ <entry>resolve_initial_references</entry>
+ <entry>JacORB</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+</chapter>
\ No newline at end of file
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Web_Service_Specific_Management.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Web_Service_Specific_Management.xml (rev 0)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/Web_Service_Specific_Management.xml 2010-04-06 07:38:50 UTC (rev 32438)
@@ -0,0 +1,148 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<chapter>
+ <title>Web Service Transaction service management</title>
+ <para>
+ The basic building blocks of a transactional Web Services application are the application itself, the Web services that the application consumes, the Transaction Manager, and the transaction participants which support those Web services. Though it is unlikely in a typical deployment that a single developer will be expected to support all of these roles, the concepts are presented here so that a global model can be visualized. It will often be the case that developers will produce services, or applications that consume services, whilst system administrators will run the transaction-management infrastructure.
+ </para>
+ <section>
+ <title>The Transaction Manager</title>
+ <para>
+ The transaction manager is a Web service which coordinates JBossTS transactions. It is the only software component in JBossTS that is meant to be run directly as a network service, rather than to support end-user code. The transaction manager runs as a JAXM request/response Web service.
+ </para>
+ <important>
+ <para>
+ When starting up an application server instance that has JBossTS deployed within it, you may see various <emphasis>error</emphasis> messages in the console or log. For example <code>16:53:38,850 ERROR [STDERR] Message Listener Service: started, message listener jndi name activationcoordinator</code>. These are for information purposes only and are not actual errors.
+ </para>
+ </important>
+ <formalpara>
+ <title>Configuring the Transaction Manager</title>
+ <para>
+ The Transaction Manager and related infrastructure are configured by means of properties files: <filename>wscf.xml</filename>, <filename>wst.xml</filename> and <filename>wstx.xml</filename>. These files can be found in the conf directory and are used for configuring the demo application and the standalone module.
+ </para>
+ </formalpara>
+ <para>
+ For the most part the default values in these files need not be altered. However, the <property>com.arjuna.ats.arjuna.objectstore.objectStoreDir</property> property determines the location of the persistent store used to record transaction state. The default value of <filename>C:/temp/ObjectStore</filename> should be changed to a value appropriate to your system. For production environments this directory should reside on fault tolerant media such as a RAID array.
+ </para>
+ <para>
+ When a standalone coordinator is being used by an application it is necessary to enable and modify two further properties in <filename>wstx.xml</filename>, <property>com.arjuna.mw.wst.coordinatorURL</property> and <property>com.arjuna.mw.wst.terminatorURL</property>. These contain the URLs necessary for the client application to contact the standalone coordinator and should be configured with the correct hostname and port of the standalone coordinator.
+ </para>
+ <para>
+ JBossTS is highly modular so in order to allow for flexible deployment of individual components, the same property values are sometimes required to appear in more than one configuration file. For the majority of configurations, you should maintain consistent values for properties that are defined in more than one file.
+ </para>
+ <formalpara>
+ <title>Deploying the Transaction Manager</title>
+ <para>
+ The JBossTS Web Service Transaction Manager component consists of a number of JAR files containing the application’s class files, plus Web service (WAR) files which expose the necessary services. Programmers will typically include all these components in their application EAR file during application development, simplifying deployment of the transaction infrastructure. For production usage the Transaction Manager may be installed as an application in its own right, allowing for centralized configuration and management at the server level, independent of specific applications. The demonstration application shipped with JBossTS provides a sample deployment descriptor illustrating how the Transaction Manager components can be included in an application.
+ </para>
+ </formalpara>
+ <para>
+ JBossTS 4.0 uses fixed endpoints for its underlying protocol communication. Therefore, problems may arise if multiple applications using JBossTS are deployed to the same server concurrently. If you wish to deploy several transactional applications in the same server, the Transaction Manger must be deployed as a separate application and not embedded within the deployment of individual applications.
+ </para>
+ <para>
+ The coordinator directory in the JBossTS installation has been provided to assist in the configuration and deployment of a stand-alone transaction manager. In order to use this, you must:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Have JBoss Enterprise Application Platform 5 installed
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Install ant 1.4 or later.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <important>
+ <para>
+ It is important that a separate application server installation be used from the one that clients and services are deployed into since otherwise conflicts may occur between the various JBossTS components.
+ </para>
+ </important>
+ <para>
+ You must then edit the build.xml included with coordinator to point to the application server installation where the transaction coordinator will be deployed and the location of the JBossTS installation. The files <filename>ws-c_jaxm_web-app.xml</filename> and <filename>ws-t_jaxm_web-app.xml</filename> in the <filename>dd</filename> directory of coordinator are the deployment descriptors for the WS-C and WS-T WAR files. These files contain templated URLs. During the build phase, ant will substitute the hostname and port values you specify in the <filename>build.xml</filename> into these files.
+ </para>
+ <para>
+ Run <code>ant</code>, with <code>target deploy-weblogic</code>, <code>deploy-jboss</code> or <code>deploy-webmethods</code>, to create and deploy a new coordinator into the correct application server installation.
+ </para>
+ <para>
+ Now all you need to do is point your client at the required coordinator. To do this, generate the demo application specifying the port and hostname of the coordinator.
+ </para>
+ <formalpara>
+ <title>Deployment descriptors</title>
+ <para>
+ In general, it should not be necessary to change the contents of the various deployment descriptors used by JBossTS. However, if you do need to modify them they are all included in the coordinator module.
+ </para>
+ </formalpara>
+ <para>
+ Not all JBossTS components have ready access to the information in the deployment descriptors. Therefore, if you modify the JNDI names used by any of the WS-C or WS-T deployment descriptors you may need to inform other JBossTS components at runtime. This can be accomplished by setting an appropriate property in the <filename>wstx.xml</filename> configuration file.
+ </para>
+ <para>
+ The following table shows the default JNDI name used by the deployment descriptors and the corresponding property to set if the default value is changed.
+ </para>
+ <table>
+ <title>Deployment descriptor values and properties</title>
+ <tgroup cols='2' align='left' colsep='1' rowsep='1'>
+ <thead>
+ <row>
+ <entry>JNDI Name</entry>
+ <entry>Property</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Activationrequester</entry>
+ <entry>com.arjuna.mw.wst.at.activationrequester</entry>
+ </row>
+ <row>
+ <entry>Activationcoordinator</entry>
+ <entry>com.arjuna.mw.wst.at.activationcoordinator</entry>
+ </row>
+ <row>
+ <entry>Completionparticipant</entry>
+ <entry>com.arjuna.mw.wst.at.completionparticipant</entry>
+ </row>
+ <row>
+ <entry>Registrationrequester</entry>
+ <entry>com.arjuna.mw.wst.at.registrationrequester</entry>
+ </row>
+ <row>
+ <entry>durable2pcdispatcher</entry>
+ <entry>com.arjuna.mw.wst.at.durable2pcdispatcher</entry>
+ </row>
+ <row>
+ <entry>durable2pcparticipant</entry>
+ <entry>com.arjuna.mw.wst.at.durable2pcparticipant</entry>
+ </row>
+ <row>
+ <entry>volatile2pcdispatcher</entry>
+ <entry>com.arjuna.mw.wst.at.volatile2pcdispatcher</entry>
+ </row>
+ <row>
+ <entry>volatile2pcparticipant</entry>
+ <entry>com.arjuna.mw.wst.at.volatile2pcparticipant</entry>
+ </row>
+ <row>
+ <entry>businessagreementwithparticipantcompletiondispatcher</entry>
+ <entry>com.arjuna.mw.wst.ba.businessagreementwpcdispatcher</entry>
+ </row>
+ <row>
+ <entry>businessagreementwithparticipantcompletionparticipant</entry>
+ <entry>com.arjuna.mw.wst.ba.businessagreementwpcparticipant</entry>
+ </row>
+ <row>
+ <entry>businessagreementwithcoordinatorcompletiondispatcher</entry>
+ <entry>com.arjuna.mw.wst.ba.businessagreementwccdispatcher</entry>
+ </row>
+ <row>
+ <entry>businessagreementwithcoordinatorcompletionparticipant</entry>
+ <entry>com.arjuna.mw.wst.ba.businessagreementwccparticipant</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+
+</chapter>
\ No newline at end of file
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/XA_Specific_Service_Managenent.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/XA_Specific_Service_Managenent.xml (rev 0)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/XA_Specific_Service_Managenent.xml 2010-04-06 07:38:50 UTC (rev 32438)
@@ -0,0 +1,13 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<chapter>
+ <title>XA specific management</title>
+ <para>
+ Each XA Xid that JBossTS creates must have 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 the <property>com.arjuna.ats.arjuna.xa.nodeIdentifier</property> property. You must make sure this value is unique across your JBossTS instances. If you do not provide a value, then JBossTS will fabricate one and report the value via the logging infrastructure.
+ </para>
+ <para>
+ When running XA recovery it is therefore 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 <property>com.arjuna.ats.jta.xaRecoveryNode</property>; multiple values may be provided. A value of <code>*</code> will force JBossTS to recover (and possibly rollback) all transactions irrespective of their node identifier and should be used with caution.
+ </para>
+
+</chapter>
\ No newline at end of file
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/xa_recovery.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/xa_recovery.xml (rev 0)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Administrators_Guide/en-US/xa_recovery.xml 2010-04-06 07:38:50 UTC (rev 32438)
@@ -0,0 +1,220 @@
+<chapter>
+ <title>Resource Recovery in JBoss Transaction Service</title>
+ <section>
+ <title>Introduction</title>
+ <para>
+ JBoss Enterprise Application Platform 4.2.0 and newer releases include JBoss Transaction Service, a crash tolerant transaction manager. When enlisting XAResources such as JDBC connections defined with <xa-datasource> or JMS connections using JBoss Messaging in a 2-phase transaction, JBoss Transaction Service keeps a transaction log that allows recovery should the application server crash during a transaction. If an appropriate recovery module is configured, most failed transactions can be recovered automatically once all resources become available again.
+ </para>
+ </section>
+
+ <section>
+ <title>Assumptions</title>
+ <para>
+ The configuration options in this document are contained by default in the file <filename>jbossjta-properties.xml</filename> (<filename>jbossts-propeties.xml</filename> in 5.x), located in your server configuration's conf directory. For a server installed at <replaceable>JBOSS_HOME</replaceable> using the "default" configuration, the correct file path is:
+ <code><filename><replaceable>JBOSS_HOME</replaceable>/server/default/conf/jbossjta-properties.xml</filename></code>
+ </para>
+ </section>
+ <section>
+ <title>A Note About Clusters</title>
+ <para>
+ Each app server instance is responsible for recovering transactions it was coordinating. Commonly, a single database will serve multiple app servers and thus participate in transactions from multiple coordinators. During recovery, JBoss Transaction Service asks each resource manager for a list of in-doubt transactions which it can potentially recover. The database responds to this by returning all in-doubt transactions, including ones that may not have been coordinated by a given instance. To effectively separate each node's transactions, you must configure a unique node id for each app server instance that will share a common database. To do this, set a unique value for the following property:
+ </para>
+ <programlisting>
+ <property name="com.arjuna.ats.arjuna.xa.nodeIdentifier" value="1"/>
+ </programlisting>
+ <para>
+ A single element that tells the recovery manager what node to recover for is also needed. Naturally, this needs to match the nodeIdentifier configured above.
+ </para>
+ <programlisting>
+ <property name="com.arjuna.ats.jta.xaRecoveryNode" value="1"/>
+ </programlisting>
+ </section>
+
+ <section>
+ <title>Recovery Modules</title>
+ <para>
+ Each XA resource for which recovery is desired needs a corresponding recovery module configured in the "jta" section of <filename>jbossjta-properties.xml</filename>. Each recovery module must extend <methodname>com.arjuna.ats.jta.recovery.XAResourceRecovery</methodname>. We provide implementations for JDBC and JMS XA resources.
+ </para>
+
+ <section>
+ <title>JDBC Recovery</title>
+ <para>
+ We provide a generic recovery module for use with JDBC datasources. Configure one instance per datasource so that each resource can be recovered. If configuring recovery for more than one datasource please note the property's "name" must be unique. For an <xa-datasource> whose <jndi-name> name is "DefaultDS" use the following XML:
+ </para>
+ <programlisting>
+ <property name="com.arjuna.ats.jta.recovery.XAResourceRecoveryJDBC"
+ value="com.arjuna.ats.internal.jbossatx.jta.AppServerJDBCXARecovery;jndiname=DefaultDS"/>
+ </programlisting>
+ <para>
+ The AppServerJDBCXARecovery module uses the "JMX Invoker" to acquire a javax.transaction.xa.XAResource from the datasource so if the JMX Invoker is secured then supply the appropriate username and password with this syntax:
+ </para>
+
+ <programlisting>
+ <property name="com.arjuna.ats.jta.recovery.XAResourceRecoveryJDBC"
+ value="com.arjuna.ats.internal.jbossatx.jta.AppServerJDBCXARecovery;jndiname=DefaultDS,username=<replaceable>USER</replaceable>,password=<replaceable>PASS</replaceable>"/>
+ </programlisting>
+ <para>
+ The security for the JMX Invoker is configured in <filename><replaceable>JBOSS_HOME</replaceable>/server/<profile>/deploy/jmx-invoker-service.xml>/profile></filename> via the securityDomain on the org.jboss.jmx.connector.invoker.AuthenticationInterceptor for the "invoke" operation.
+ </para>
+ <para>
+ It is possible to configure multiple datasources which connect to the same physical database. When this happens make sure that only one datasource has recovery configured.
+ </para>
+ <note>
+ <para>Recovery works at the database level, not the datasource level. If the same database has multiple datasources with recovery configured then the database will be inspected by the recovery manager multiple times in a single pass and recovery will not function properly.
+ </para>
+ </note>
+
+
+ <section>
+ <title>Vendor-Specific Database Information</title>
+ <variablelist>
+ <varlistentry>
+ <term>Oracle</term>
+ <listitem>
+ <para>
+ If Oracle is configured incorrectly, you will experience the following error in your log files:
+ </para>
+ <screen>
+ WARN [com.arjuna.ats.jta.logging.loggerI18N] [com.arjuna.ats.internal.jta.recovery.xarecovery1] Local XARecoveryModule.xaRecovery got XA exception javax.transaction.xa.XAException, XAException.XAER_RMERR
+ </screen>
+ <para>
+ To resolve this error, be sure that the Oracle user has access to the appropriate tables to accomplish the recovery:
+ </para>
+ <programlisting>
+ GRANT SELECT ON sys.dba_pending_transactions TO <replaceable>user</replaceable>;
+ GRANT SELECT ON sys.pending_trans$ TO <replaceable>user</replaceable>;
+ GRANT SELECT ON sys.dba_2pc_pending TO <replaceable>user</replaceable>;
+ GRANT EXECUTE ON sys.dbms_xa TO <replaceable>user</replaceable>;
+ </programlisting>
+
+ <para>
+ The above assumes that <replaceable>user</replaceable> is the user defined to connect from JBoss to Oracle. It also assumes that either Oracle 10g R2 (patched for bug 5945463) or 11g is in use. If an unpatched version prior to 11g is used then change the last GRANT EXECUTE to:
+ </para>
+ <programlisting>
+ GRANT EXECUTE ON sys.dbms_system TO <replaceable>user</replaceable>;
+ </programlisting>
+
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PostgreSQL</term>
+ <listitem>
+ <para>
+ See the PostgreSQL for instructions on enabling prepared (i.e. XA) transactions. Version 8.4-701 of PostgreSQL's JDBC driver has a bug in <systemitem>org.postgresql.xa.PGXAConnection</systemitem> which breaks recovery in certain situations. A fix has been committed to PostgreSQL's CVS, but a new driver had not been released at the time of this writing.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>MySQL</term>
+ <listitem>
+ <para>
+ Based on http://bugs.mysql.com/bug.php?id=12161, XA transaction recovery does not appear to be possible using MySQL. See also JBPAPP-2576 in the release notes for JBoss Enterprise Application Platform 5.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>DB2</term>
+ <listitem>
+ <para>
+ DB2 expects <systemitem>XAResource.recover</systemitem> calls only during designated resynchronization stage which occurs when application server is restared after crash/failure. This is a design flaw in DB2, and out of the scope of this documentation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ </section>
+ <section>
+ <title>JMS Recovery</title>
+ <warning>
+ <para>
+ Transaction failure recovery for JMS XA resources is not available in JBoss EAP 4.2. This functionality is present in JBoss EAP 4.3 CP04 and later.
+ </para>
+ </warning>
+ <para>
+ Enabling the JBoss Transaction Service Recovery Manager to recover JBoss Messaging XA resources is a simple matter and involves adding this line to <filename>jbossjta-properties.xml</filename>:
+ </para>
+ <programlisting>
+ <property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.JBMESSAGING1"
+ value="org.jboss.jms.server.recovery.MessagingXAResourceRecovery;java:/DefaultJMSProvider"/>
+ </programlisting>
+ <para>
+ In the above example the recovery manager attempts to recover JMS resources using the JMSProviderLoader "DefaultJMSProvider." DefaultJMSProvider is the default JMS provider loader that ships with JBoss EAP and is defined in <filename><replaceable>JBOSS_HOME</replaceable>/server/<profile>/deploy/*jms-ds.xml</profile></filename>. To recover using a different JMS provider loader (e.g. one corresponding to a remote JMS provider), add another line and instead of DefaultJMSProvider specify the name of the remote JMS provider as defined in its MBean configuration.
+ </para>
+ <para>
+ For each module configured, the <emphasis>name</emphasis> must be unique:
+ </para>
+ <programlisting>
+ <property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.JBMESSAGING2"
+ value="org.jboss.jms.server.recovery.MessagingXAResourceRecovery;java:/RemoteJMSProvider"/>
+ </programlisting>
+ <para>
+ If the JMS provider is secured, authentication credentials can be passed. For example:
+ </para>
+ <programlisting>
+ <property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.JBMESSAGING1"
+ value="org.jboss.jms.server.recovery.MessagingXAResourceRecovery;java:/DefaultJMSProvider,USER,PASS"/>
+ </programlisting>
+ </section>
+ </section>
+ <section>
+ <title>Notes for JMS clusters</title>
+ <para>
+ When one node in JBoss Messaging cluster goes down its buddy in the cluster hears about it and will load all of the dead server's messages from the database.
+ </para>
+ <para>
+ If the dead node was performing an XA transaction when it went down it is possible that the transaction log was written but the associated messages get moved to another server in the cluster.
+ </para>
+ <para>
+ When the dead server comes back to life the recovery manager may try to recover the transactions stored in the transaction log. If the messages were moved to another server it's impossible to acquire the proper XAResource from the local JMS provider because the associated messages are no longer on that server. The result is that JBoss Transaction Service returns:
+ </para>
+ <screen>
+ Could not find new XAResource to use for recovering non-serializable XAResource
+ </screen>
+ <para>
+ To resolve this, add a JMS provider and a Recovery Manager for each node in the cluster. For example, if the cluster had three nodes, add this to <filename>jbossjta-properties.xml</filename>:
+ </para>
+ <programlisting>
+ <property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.JBMESSAGINGREMOTE1"
+ value="org.jboss.jms.server.recovery.MessagingXAResourceRecovery;java:/RemoteJMSProvider1"/>
+
+ <property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.JBMESSAGINGREMOTE2"
+ value="org.jboss.jms.server.recovery.MessagingXAResourceRecovery;java:/RemoteJMSProvider2"/>
+ </programlisting>
+ <para>
+ The remote providers can be configured in <filename><replaceable>JBOSS_HOME</replaceable>/server/default/deploy/jms-ds.xml</filename>:
+ </para>
+ <programlisting>
+ <mbean code="org.jboss.jms.jndi.JMSProviderLoader"
+ name="jboss.jms:service=JMSProviderLoader,name=RemoteProvider1">
+ <attribute name="ProviderName">RemoteProvider1</attribute>
+ <attribute name="ProviderAdapterClass">org.jboss.jms.jndi.JNDIProviderAdapter</attribute>
+ <attribute name="FactoryRef">XAConnectionFactory</attribute>
+ <attribute name="QueueFactoryRef">XAConnectionFactory</attribute>
+ <attribute name="TopicFactoryRef">XAConnectionFactory</attribute>
+ <attribute name="Properties">
+ java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory
+ java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces
+ java.naming.provider.url=RemoteHost1:1099
+ </attribute>
+ </mbean>
+
+ <mbean code="org.jboss.jms.jndi.JMSProviderLoader"
+ name="jboss.jms:service=JMSProviderLoader,name=RemoteProvider2">
+ <attribute name="ProviderName">RemoteProvider2</attribute>
+ <attribute name="ProviderAdapterClass">org.jboss.jms.jndi.JNDIProviderAdapter</attribute>
+ <attribute name="FactoryRef">XAConnectionFactory</attribute>
+ <attribute name="QueueFactoryRef">XAConnectionFactory</attribute>
+ <attribute name="TopicFactoryRef">XAConnectionFactory</attribute>
+ <attribute name="Properties">
+ java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory
+ java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces
+ java.naming.provider.url=RemoteHost2:1099
+ </attribute>
+ </mbean>
+ </programlisting>
+ <para>
+ Notice the JNDI properties are configured to connect to the remote servers (i.e. the other nodes in the cluster). Add providers and recovery managers to each node in the cluster for all the other nodes of the cluster in order to get proper recovery.
+ </para>
+ </section>
+</chapter>
\ No newline at end of file
More information about the jboss-svn-commits
mailing list