[jboss-svn-commits] JBL Code SVN: r36934 - in labs/jbosstm/trunk: ArjunaCore/docs/failure_recovery_guide/en-US and 16 other directories.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Thu Apr 14 09:13:00 EDT 2011
Author: tomjenkinson
Date: 2011-04-14 09:12:59 -0400 (Thu, 14 Apr 2011)
New Revision: 36934
Added:
labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/About_This_Guide.xml
labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/About_This_Guide.xml
labs/jbosstm/trunk/ArjunaJTS/docs/development_guide/en-US/extras/exampleRMICDeclaration.xml
labs/jbosstm/trunk/docs/development_guide/en-US/About_This_Guide.xml
labs/jbosstm/trunk/docs/development_guide/en-US/Configuration_Options.xml
labs/jbosstm/trunk/docs/development_guide/en-US/Development_Guide.ent
labs/jbosstm/trunk/docs/development_guide/en-US/Development_Guide.xml
labs/jbosstm/trunk/docs/development_guide/en-US/General_Transaction_Issues.xml
labs/jbosstm/trunk/docs/development_guide/en-US/Tools.xml
labs/jbosstm/trunk/docs/development_guide/en-US/extras/CheckedAction.java
labs/jbosstm/trunk/docs/development_guide/en-US/extras/EnvironmentBeans.xml
labs/jbosstm/trunk/docs/development_guide/en-US/extras/LastResourceRecord.java
labs/jbosstm/trunk/docs/development_guide/en-US/extras/TxStats.java
labs/jbosstm/trunk/docs/development_guide/en-US/extras/abstract_record_subclass.java
labs/jbosstm/trunk/docs/development_guide/en-US/extras/array_get_method.java
labs/jbosstm/trunk/docs/development_guide/en-US/extras/array_set_method.java
labs/jbosstm/trunk/docs/development_guide/en-US/extras/defaultTimeout.java
labs/jbosstm/trunk/docs/development_guide/en-US/extras/osv-plugin-ant.xml
labs/jbosstm/trunk/docs/development_guide/en-US/extras/osv_plugin.java
labs/jbosstm/trunk/docs/development_guide/en-US/images/independent_top_level_action.png
Removed:
labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/Configuration_Options.xml
labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/Tools.xml
labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/Java_Transaction_API.xml
labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/The_Resource_Manager.xml
labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/Transaction_Recovery.xml
labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/Transactions.xml
labs/jbosstm/trunk/docs/development_guide/en-US/Examples.xml
labs/jbosstm/trunk/docs/development_guide/en-US/JBossJTA_Development_Guide.ent
labs/jbosstm/trunk/docs/development_guide/en-US/JBossJTA_Development_Guide.xml
labs/jbosstm/trunk/docs/development_guide/en-US/JDBC.xml
labs/jbosstm/trunk/docs/development_guide/en-US/Java_Transaction_API.xml
labs/jbosstm/trunk/docs/development_guide/en-US/Transaction_Recovery.xml
labs/jbosstm/trunk/docs/development_guide/en-US/Using_JBossTA_In_Application_Servers.xml
Modified:
labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/ArjunaCore_Development_Guide.ent
labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/ArjunaCore_Development_Guide.xml
labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/Book_Info.xml
labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/Constructing_A_Transactional_Objects_For_Java_Application.xml
labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/General_Transaction_Issues.xml
labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/Preface.xml
labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/Revision_History.xml
labs/jbosstm/trunk/ArjunaCore/docs/failure_recovery_guide/en-US/ArjunaCore_Failure_Recovery_Guide.xml
labs/jbosstm/trunk/ArjunaJTA/docs/administration_guide/en-US/JBossJTA_Administration_Guide.ent
labs/jbosstm/trunk/ArjunaJTA/docs/administration_guide/en-US/JBossJTA_Administration_Guide.xml
labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/JBossJTA_Development_Guide.ent
labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/JBossJTA_Development_Guide.xml
labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/Revision_History.xml
labs/jbosstm/trunk/ArjunaJTA/docs/installation_guide/en-US/JBossJTA_Installation_Guide.ent
labs/jbosstm/trunk/ArjunaJTA/docs/installation_guide/en-US/JBossJTA_Installation_Guide.xml
labs/jbosstm/trunk/ArjunaJTA/docs/quick_start/en-US/JBossJTA_Quick_Start_Guide.xml
labs/jbosstm/trunk/ArjunaJTS/docs/administration_guide/en-US/JBossJTS_Administration_Guide.ent
labs/jbosstm/trunk/ArjunaJTS/docs/administration_guide/en-US/JBossJTS_Administration_Guide.xml
labs/jbosstm/trunk/ArjunaJTS/docs/development_guide/en-US/Failure_Recovery.xml
labs/jbosstm/trunk/ArjunaJTS/docs/development_guide/en-US/JBossJTS_Development_Guide.ent
labs/jbosstm/trunk/ArjunaJTS/docs/development_guide/en-US/JBossJTS_Development_Guide.xml
labs/jbosstm/trunk/ArjunaJTS/docs/development_guide/en-US/Revision_History.xml
labs/jbosstm/trunk/ArjunaJTS/docs/development_guide/en-US/Tools.xml
labs/jbosstm/trunk/ArjunaJTS/docs/orbportability/en-US/JBossJTS_ORB_Portability_Guide.xml
labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/JBossJTS_Quick_Start_Guide.xml
labs/jbosstm/trunk/XTS/docs/Transactions_XTS_Administration_And_Development_Guide/en-US/Transactions_XTS_Administration_And_Development_Guide.ent
labs/jbosstm/trunk/XTS/docs/Transactions_XTS_Administration_And_Development_Guide/en-US/Transactions_XTS_Administration_And_Development_Guide.xml
labs/jbosstm/trunk/docs/development_guide/en-US/Author_Group.xml
labs/jbosstm/trunk/docs/development_guide/en-US/Book_Info.xml
labs/jbosstm/trunk/docs/development_guide/en-US/Chapter.xml
labs/jbosstm/trunk/docs/development_guide/en-US/Preface.xml
labs/jbosstm/trunk/docs/development_guide/en-US/Revision_History.xml
labs/jbosstm/trunk/docs/development_guide/en-US/The_Resource_Manager.xml
labs/jbosstm/trunk/docs/development_guide/en-US/Transactions.xml
labs/jbosstm/trunk/docs/failure_recovery_guide/en-US/About_This_Guide.xml
labs/jbosstm/trunk/docs/release_notes/en-US/Release_Notes.ent
labs/jbosstm/trunk/docs/release_notes/en-US/Release_Notes.xml
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Transactions_Overview_Guide.xml
Log:
JBTM-820 converted the programmers guides
Added: labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/About_This_Guide.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/About_This_Guide.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/About_This_Guide.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -0,0 +1,45 @@
+<?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" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "JBossJTA_Development_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>About This Guide</title>
+ <para>
+ The TxCore and TXOJ Programmers Guide contains information on how to use &PRODUCT;.
+ This document provides a detailed look at the design and operation of the TxCore
+ transaction
+ engine and the Transactional Objects for Java toolkit. It describes the architecture
+ and the
+ interaction of components within this architecture.
+ </para>
+ <section>
+ <title>Audience</title>
+ <para>
+ This guide is most relevant to engineers who want to use &PRODUCT;
+ in
+ installations that are not covered elsewhere. It is assumed that the reader is already
+ familiar with the core &PRODUCT;
+ documentation set.
+ </para>
+ </section>
+ <section>
+ <title>Prerequisites</title>
+ <para>
+ This guide assumes a basic familiarity with Java service development and object-oriented
+ programming.
+ A
+ fundamental level of understanding in the following areas will also be useful:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>General understanding of the APIs, components, and objects that are present in Java
+ applications.</para>
+ </listitem>
+ <listitem>
+ <para>A general understanding of the Windows and UNIX operating systems.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+</chapter>
+
Modified: labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/ArjunaCore_Development_Guide.ent
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/ArjunaCore_Development_Guide.ent 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/ArjunaCore_Development_Guide.ent 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,4 +1,4 @@
<!ENTITY PRODUCT "Documentation">
<!ENTITY BOOKID "ArjunaCore_Development_Guide">
-<!ENTITY YEAR "2010">
+<!ENTITY YEAR "2011">
<!ENTITY HOLDER "jboss.org">
Modified: labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/ArjunaCore_Development_Guide.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/ArjunaCore_Development_Guide.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/ArjunaCore_Development_Guide.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -5,19 +5,17 @@
]>
<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 xmlns:xi="http://www.w3.org/2001/XInclude" href="Preface.xml" />
+ <xi:include href="About_This_Guide.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Overview.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Using_TxCore.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="General_Transaction_Issues.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Hints_and_Tips.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Tools.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Constructing_A_Transactional_Objects_For_Java_Application.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Configuration_Options.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Constructing_A_Transactional_Objects_For_Java_Application.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Appendix_Object_Store_Implementations.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Appendix_Class_Definitions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <index />
+ <!-- <index /> -->
</book>
Modified: labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/Book_Info.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/Book_Info.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/Book_Info.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -5,7 +5,7 @@
]>
<bookinfo id="book-ArjunaCore_Development_Guide-ArjunaCore_Development_Guide">
<title>ArjunaCore Development Guide</title>
- <subtitle>Building Applications with ArjunaCore</subtitle>
+ <subtitle>TxCore and TXOJ Programmers Guide</subtitle>
<productname>ArjunaCore</productname>
<productnumber>4.15.0</productnumber>
<edition>0</edition>
Deleted: labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/Configuration_Options.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/Configuration_Options.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/Configuration_Options.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,226 +0,0 @@
-<?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" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "ArjunaCore_Development_Guide.ent">
-%BOOK_ENTITIES;
-]>
-<chapter id="chap-configuration-options">
- <title>Configuration options</title>
-
- <section>
- <title>Loading a configuration</title>
- <para>
- Each module of the system contains a <classname><replaceable>module</replaceable>propertyManager</classname>
- class., which provides static getter methods for one or more
- <classname><replaceable>name</replaceable>EnvironmentBean</classname> classes. An example is
- <classname>com.arjuna.ats.arjuna.commmon.arjPropertyManager</classname>. These environment beans are standard
- JavaBean containing properties for each configuration option in the system. Typical usage is of the form:
- </para>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/defaultTimeout.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- <para>
- These beans are singletons, instantiated upon first access, using the following algorithm.
- </para>
- <procedure>
- <title>Algorithm for environment bean instantiation</title>
- <step>
- <para>
- The properties are loaded and populated from a properties file named and located as follows:
- </para>
- <substeps>
- <step>
- <para>
- If the properties file name property is set, its value is used as the file name.
- </para>
- </step>
- <step>
- <para>
- If not, the default file name is used.
- </para>
- </step>
- </substeps>
- </step>
- <step>
- <para>
- The file thus named is searched for by, in order
- </para>
- <orderedlist>
- <listitem>
- <para>
- absolute path
- </para>
- </listitem>
- <listitem>
- <para>
- user.dir
- </para>
- </listitem>
- <listitem>
- <para>
- user.home
- </para>
- </listitem>
- <listitem>
- <para>
- java.home
- </para>
- </listitem>
- <listitem>
- <para>
- directories contained on the classpath
- </para>
- </listitem>
- <listitem>
- <para>
- a default file embedded in the product .jar file.
- </para>
- </listitem>
- </orderedlist>
- </step>
- <step>
- <para>
- The file is treated as being of standard java.util.Properties xml format and loaded accordingly. The entry
- names are of the form EnvironmentBeanClass.propertyName:<code><entry
- key="CoordinatorEnvironmentBean.commitOnePhase">YES</entry></code>. Valid values for Boolean
- properties are case-insensitive, and may be one of:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- NO
- </para>
- </listitem>
- <listitem>
- <para>
- YES
- </para>
- </listitem>
- <listitem>
- <para>
- FALSE
- </para>
- </listitem>
- <listitem>
- <para>
- TRUE
- </para>
- </listitem>
- <listitem>
- <para>
- OFF
- </para>
- </listitem>
- <listitem>
- <para>
- ON
- </para>
- </listitem>
- </itemizedlist>
- <para>
- In the case of properties that take multiple values, they are white-space-delimited.
- </para>
- <example>
- <title>Example Environment Bean</title>
- <programlisting language="XML" role="XML"> <xi:include href="extras/EnvironmentBeans.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
- </step>
- <step>
- <para>
- After the file is loaded, it is cached and is not re-read until the JVM is restarted. Changes to the
- properties file require a restart in order to take effect.
- </para>
- </step>
- <step>
- <para>
- After the properties are loaded, the EnvironmentBean is then inspected and, for each field, if the properties
- contains a matching key in the search order as follows, the <methodname>setter</methodname> method for that field is invoked with the
- value from the properties, or the system properties if different.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Fully.Qualified.NameEnvironmentBean.propertyName
- </para>
- </listitem>
- <listitem>
- <para>
- NameEnvironmentBean.propertyName (this is the preferred form used in the properties file)
- </para>
- </listitem>
- <listitem>
- <para>
- the old com.arjuna... properties key (deprecated, for backwards compatibility only).
- </para>
- </listitem>
- </itemizedlist>
- </step>
- <step>
- <para>
- The bean is then returned to the caller, which may further override values by calling setter methods.
- </para>
- </step>
- </procedure>
- <para>
- The implementation reads most bean properties only once, as the consuming component or class is instantiated. This
- usually happens the first time a transaction is run. As a result, calling <methodname>setter</methodname> methods
- to change the value of bean properties while the system is running typically has no effect, unless it is done
- prior to any use of the transaction system. Altered bean properties are not persisted back to the properties file.
- </para>
- <para>
- You can configure the system using a bean wiring system such as JBoss Microcontainer or Spring. Take care when
- instantiating beans, to obtain the singleton via the static getter (factory) method on the module property
- manager. Using a new bean instantiated with the default constructor is ineffective, since it is not possible to
- pass this configured bean back to the property management system.
- </para>
- </section>
-
-
- <section>
- <title>Options</title>
- <para>
- The canonical reference for configuration options is the Javadoc of the various
- <classname>EnvironmentBean</classname> classes, For ArjunaCore these are:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <classname>com.arjuna.common.internal.util.logging.LoggingEnvironmentBean.java </classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <classname>com.arjuna.common.internal.util.logging.basic.BasicLogEnvironmentBean.java </classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <classname>com.arjuna.ats.txoj.common.TxojEnvironmentBean.java </classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <classname>com.arjuna.ats.arjuna.common.CoordinatorEnvironmentBean.java </classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <classname>com.arjuna.ats.arjuna.common.ObjectStoreEnvironmentBean.java </classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <classname>com.arjuna.ats.arjuna.common.RecoveryEnvironmentBean.java </classname>
- </para>
- </listitem>
- <listitem>
- <para>
- <classname>com.arjuna.ats.arjuna.common.CoreEnvironmentBean.java </classname>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- Additional modules built on ArjunaCore may include further beans containing module-specific configuration
- options. Refer to the documentation for the specific modules for more information.
- </para>
- </section>
-
-</chapter>
-
Modified: labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/Constructing_A_Transactional_Objects_For_Java_Application.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/Constructing_A_Transactional_Objects_For_Java_Application.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/Constructing_A_Transactional_Objects_For_Java_Application.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -175,7 +175,7 @@
However, since the elements of the <systemitem>queue</systemitem> objects are not individually concurrency
controlled, certain combinations of concurrent operation invocations are executed serially, even though logically
they could be executed concurrently. An example of this is modifying the states of two different elements in the
- queue. <xref linkend="chap-configuration-options" /> addresses some of these issues.
+ queue. The platform Development Guide addresses some of these issues.
</para>
</section>
Modified: labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/General_Transaction_Issues.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/General_Transaction_Issues.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/General_Transaction_Issues.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -14,107 +14,6 @@
</para>
<section>
- <title>Checking transactions</title>
- <para>
- In a multi-threaded application, multiple threads may be associated with a transaction during its lifetime,
- sharing the context. In addition, it is possible that if one thread terminates a transaction, other threads may
- still be active within it. In a distributed environment, it can be difficult to guarantee that all threads have
- finished with a transaction when it is terminated. By default, TxCore will issue a warning if a thread terminates
- a transaction when other threads are still active within it. However, it will allow the transaction termination to
- continue.
- </para>
- <para>
- Other solutions to this problem are possible. One example would be to block the thread which is terminating the
- transaction until all other threads have disassociated themselves from the transaction context. Therefore, TxCore
- provides the <classname>com.arjuna.ats.arjuna.coordinator.CheckedAction</classname> class, which allows the thread
- or transaction termination policy to be overridden. Each transaction has an instance of this class associated with
- it, and application programmers can provide their own implementations on a per transaction basis.
- </para>
- <example>
- <title>Class <classname>CheckedAction</classname></title>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/CheckedAction.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
- <para>
- When a thread attempts to terminate the transaction and there are active threads within it, the system will invoke
- the <methodname>check</methodname> method on the transaction’s <systemitem>CheckedAction</systemitem> object. The
- parameters to the check method are:
- </para>
- <variablelist>
- <varlistentry>
- <term>isCommit</term>
- <listitem>
- <para>
- Indicates whether the transaction is in the process of committing or rolling back.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>actUid</term>
- <listitem>
- <para>
- The transaction identifier.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>list</term>
- <listitem>
- <para>
- A list of all of the threads currently marked as active within this transaction.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>
- When <methodname>check</methodname> returns, the transaction termination will continue. Obviously the state of the
- transaction at this point may be different from that when <methodname>check</methodname> was called, e.g., the
- transaction may subsequently have been committed.
- </para>
- <para>
- A <classname>CheckedAction</classname> instance is created for each transaction. As mentioned above, the default
- implementation simply issues warnings in the presence of multiple threads active on the transaction when it is
- terminated. However, a different instance can be provided to each transaction in one of the following ways:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Use the <methodname>setCheckedAction</methodname> method on the <classname>BasicAction</classname> instance.
- </para>
- </listitem>
- <listitem>
- <para>
- Define an implementation of the <interfacename>CheckedActionFactory</interfacename> interface, which has a
- single method <methodname>getCheckedAction</methodname>(<type>final Uid</type> <varname>txId</varname>,
- <type>final String</type> <varname>actionType</varname>) that returns a
- <classname>CheckedAction</classname>. The factory class name can then be provided to the Transaction Service
- at runtime by setting the <varname>CoordinatorEnvironmentBean.checkedActionFactory</varname> property.
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>Gathering statistics</title>
- <para>
- By default, the Transaction Service does not maintain any history information about transactions. However, by
- setting the <varname>CoordinatorEnvironmentBean.enableStatistics</varname> property variable to
- <literal>YES</literal>, the transaction service will maintain information about the number of transactions
- created, and their outcomes. This information can be obtained during the execution of a transactional application
- via the <classname>com.arjuna.ats.arjuna.coordinator.TxStats</classname> class.
- </para>
- <example>
- <title>Class <classname>TxStats</classname></title>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/TxStats.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
- <para>
- The class <classname>ActionManager</classname> gives further information about specific active transactions
- through the classes <classname>getTimeAdded</classname>, which returns the time (in milliseconds) when the
- transaction was created, and <classname>inflightTransactions</classname>, which returns the list of currently
- active transactions.
- </para>
- </section>
-
- <section>
<title>Last resource commit optimization (LRCO)</title>
<para>
In some cases it may be necessary to enlist participants that are not two-phase commit aware into a two-phase
Modified: labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/Preface.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/Preface.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/Preface.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,28 +1,13 @@
-<?xml version='1.0' encoding='utf-8' ?>
+<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "ArjunaCore_Development_Guide.ent">
-%BOOK_ENTITIES;
]>
<preface id="pref-ArjunaCore_Development_Guide-Preface">
- <title>Preface</title>
- <section>
- <title>Prerequisites</title>
- <para>
- This guide assumes a basic familiarity with Java service development and object-oriented programming. A
- fundamental level of understanding in the following areas will also be useful:
- </para>
- <itemizedlist>
- <listitem>
- <para>General understanding of the APIs, components, and objects that are present in Java applications.</para>
- </listitem>
- <listitem>
- <para>A general understanding of the Windows and UNIX operating systems.</para>
- </listitem>
- </itemizedlist>
- </section>
- <xi:include href="Common_Content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude"><xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude"><xi:include href="Common_Content/Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- </xi:fallback>
- </xi:include>
+ <title>Preface</title>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Common_Content/Conventions.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Feedback.xml">
+ <xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude">
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Common_Content/Feedback.xml"/>
+ </xi:fallback>
+ </xi:include>
</preface>
-
Modified: labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/Revision_History.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/Revision_History.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/Revision_History.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -4,25 +4,39 @@
%BOOK_ENTITIES;
]>
<appendix id="appe-ArjunaCore_Development_Guide-Revision_History">
- <title>Revision History</title>
- <simpara>
- <revhistory>
- <revision>
- <revnumber>0</revnumber>
- <date>Fri Sep 24 2010</date>
- <author>
- <firstname>Misty</firstname>
- <surname>Stanley-Jones</surname>
- <email>misty at redhat.com</email>
- </author>
- <revdescription>
- <simplelist>
- <member>Convert existing documentation to Publican.</member>
- <member>Update to 4.13.</member>
- </simplelist>
- </revdescription>
- </revision>
- </revhistory>
- </simpara>
+ <title>Revision History</title>
+ <simpara>
+ <revhistory>
+ <revision>
+ <revnumber>0</revnumber>
+ <date>Fri Sep 24 2010</date>
+ <author>
+ <firstname>Misty</firstname>
+ <surname>Stanley-Jones</surname>
+ <email>misty at redhat.com</email>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Convert existing documentation to Publican.</member>
+ <member>Update to 4.13.</member>
+ </simplelist>
+ </revdescription>
+ </revision>
+ <revision>
+ <revnumber>0</revnumber>
+ <date>Thu Apr 14 2011</date>
+ <author>
+ <firstname>Tom</firstname>
+ <surname>Jenkinson</surname>
+ <email>tom.jenkinson at redhat.com</email>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Moved some content to main developer's guide</member>
+ </simplelist>
+ </revdescription>
+ </revision>
+ </revhistory>
+ </simpara>
</appendix>
Deleted: labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/Tools.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/Tools.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/Tools.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,489 +0,0 @@
-<?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" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "ArjunaCore_Development_Guide.ent">
-%BOOK_ENTITIES;
-]>
-<chapter>
- <title>Tools</title>
- <para>
- This chapter explains how to start and use the tools framework and what tools are available.
- </para>
- <section>
- <title>Starting the Transaction Service tools</title>
- <para>
- The transaction service tools are started differently, depending on your operating system.
- </para>
-
- <procedure id="starting-tools">
- <title>Starting the Transaction Service Tools</title>
- <step>
- <title>Microsoft Windows</title>
- <substeps>
- <step>
- <para>
- Double click on the <guilabel>Start Tools</guilabel> link in the <guilabel>JBoss Transaction
- Service</guilabel> program group in the <guilabel>Start</guilabel> menu.
- </para>
- </step>
- </substeps>
- </step>
- <step>
- <title>Linux / UNIX</title>
- <substeps>
- <step>
- <para>
- In a graphical environment, Start a command prompt and change to the directory where JBoss Transaction
- Service is installed, henceforth referred to as <replaceable>JBOSSTS_INSTALL_DIRECTORY</replaceable>.
- </para>
- </step>
- <step>
- <para>
- Run the <command>run-tools.sh</command> command.
- </para>
- <screen>[user at localhost bin]$ ./run-tools.sh</screen>
- </step>
- </substeps>
- </step>
- <step>
- <title>Result</title>
- <para>
- The <guilabel>Tools</guilabel> window appears. This is the launch area for all of the tools shipped
- with the JBoss Transaction Service. At the top of the window you will notice a menu bar (see Figure 7).
- </para>
- </step>
- </procedure>
-
- </section>
-
- <section>
- <title>The Tools Window</title>
- <itemizedlist>
- <listitem><para>File</para>
- <variablelist>
- <varlistentry>
- <term>Open JMX Browser</term>
- <listitem>
- <para>
- Displays the <xref linkend="jmx-browser-window" />
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Open Object Store Browser</term>
- <listitem>
- <para>
- Displays the <xref linkend="object-store-browser" />.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Settings</term>
- <listitem>
- <para>
- Allows you to configure application settings.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Exit</term>
- <listitem>
- <para>
- Exits the application.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- <listitem><para>Performance</para>
- <variablelist>
- <varlistentry>
- <term>Open</term>
- <listitem>
- <para>
- Opens a <xref linkend="performance-tool" /> window.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Close All</term>
- <listitem>
- <para>
- Closes all open Performance windows.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- <listitem><para>Window</para>
- <variablelist>
- <varlistentry>
- <term>Cascade Windows</term>
- <listitem>
- <para>
- Arranges windows diagonally so that you can find a specific one.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Numbered list of open windows</term>
- <listitem>
- <para>
- Allows you to focus a window from the list of all open windows.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- <listitem><para>Help</para>
- <variablelist>
- <varlistentry>
- <term>About</term>
- <listitem>
- <para>
- Information about the Tools, including version, licensing, and credits.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </itemizedlist>
- </section>
-
- <section id="performance-tool">
- <title>Using the performance tool</title>
- <para>
- The performance tool can be used to display performance information about the transaction service. This
- information is gathered using the <systemitem>Performance</systemitem> JMX bean, so the transaction service needs
- to be integrated into an application server, such as JBoss Application Server, to give any performance
- information.
- </para>
- <para>
- The performance information is displayed via a multi-series graph. To view this graph, open a performance window
- by selecting <menuchoice><guimenu>Performance</guimenu><guimenu>Open</guimenu></menuchoice>.
- </para>
- <para>
- The multi-series graph displays a number of items. The items can be turned on or off from the
- <guimenu>Series</guimenu> menu. When series are enabled, they appear in the legend at the bottom of the graph.
- </para>
- <itemizedlist>
- <listitem><para>Number of transactions.</para></listitem>
- <listitem><para>Number of committed transactions.</para></listitem>
- <listitem><para>Number of aborted transactions.</para></listitem>
- <listitem><para>Number of nested transactions.</para></listitem>
- <listitem><para>Number of heuristics raised.</para></listitem>
- </itemizedlist>
- <para>
- The data shown is graphed against time. The <guilabel>Y-axis</guilabel> represents the number of transactions and
- the <guilabel>X-axis</guilabel> represents time.
- </para>
- <para>
- You can stop and restart the sampling of data at any time using the <guimenu>Sampling</guimenu> menu. You can save
- the data currently visible in the graph to a Comma Separate Values (CSV) file from the
- <menuchoice><guimenu>Data</guimenu><guimenu>Save to .csv</guimenu></menuchoice> option.
- </para>
- </section>
-
- <section id="jmx-browser-window">
- <title>Using the JMX Browser</title>
- <para>
- To open the JMX browser window, choose <menuchoice><guimenu>File</guimenu><guimenu>Open JMX
- Browser</guimenu></menuchoice>. The JMX browser window opens.
- </para>
-
- <para>
- The window has two main sections: the <guilabel>Details</guilabel> panel and the <guilabel>MBean</guilabel> panel.
- The <guilabel>MBean</guilabel> panel displays the MBeans exposed by the MBean server, grouped by domain name. The
- <guilabel>Details</guilabel> panel displays information about the currently selected MBean. To select an MBean,
- select its name with the mouse. Information about the MBean appears in the panel.
- </para>
- <itemizedlist>
- <title>MBean Details</title>
- <listitem><para>The total number of MBeans registered on this server.</para></listitem>
- <listitem><para>The number of constructors exposed by this MBean.</para></listitem>
- <listitem><para>The number of attributes exposed by this MBean.</para></listitem>
- <listitem><para>The number of operations exposed by this MBean.</para></listitem>
- <listitem><para>The number of notifications exposed by this MBean.</para></listitem>
- <listitem><para>A brief description of the MBean.</para></listitem>
- </itemizedlist>
- <para>
- Click the <guilabel>View</guilabel> link to display and operate on the attributes and operations exposed by this
- MBean. You can view readable attributes, alter writable attributes, and invoke operations.
- </para>
-
- <section>
- <title>Attributes and Operations</title>
- <para>
- When you click the <guilabel>View</guilabel> link, the <guilabel>View JMX Attributes and Operations</guilabel>
- window appears. You can view all readable attributes exposed by the selected MBean. You can also alter
- writable attributes. If an attribute is read-only then you cannot alter an attribute's value. To alter an
- attribute's value, just double-click the current value and enter the new value. If the
- <guibutton>Edit</guibutton> button is enabled, then you can click it to open an advanced editor. If the
- attribute type is a <systemitem>JMX object name</systemitem>, clicking this button displays the JMX attributes
- and operations for the object.
- </para>
- <para>
- Click the <guibutton>Refresh</guibutton> button to refresh the attribute values. If an exception occurs while
- retrieving the value of an attribute, the exception is displayed in place of the attribute's value.
- </para>
- <para>
- You can also invoke operations upon an MBean. A list of operations exposed by an MBean is displayed below the
- attributes list. To invoke an operation, select it from the list and click the <guibutton>Invoke</guibutton>
- button. If the operation requires parameters, a window will be displayed, prompting you for the values. You
- specify parameter values in the same way as you specify JMX attribute values. After you have specified a value
- for each of the parameters, click the <guibutton>Invoke</guibutton> button to perform the invocation.
- </para>
- <para>
- After the method invocation is complete, its return value is displayed.
- </para>
- </section>
-
-
- </section>
-
- <section id="object-store-browser">
- <title>Using the object store browser</title>
- <para>
- To open the Object Store browser, select <menuchoice><guimenu>File</guimenu><guimenu>Open Object State
- Browser</guimenu></menuchoice>.
- </para>
- <para>
- The Object Store Browser window is divided into four sections:
- </para>
- <variablelist>
- <varlistentry>
- <term>Object Store Roots</term>
- <listitem>
- <para>
- The currently available object store roots. Selecting an option from the list repopulate the Object Store
- Hierarchy with the contents of the selected root.
- </para>
- </listitem>
-
- </varlistentry>
- <varlistentry>
- <term>Object Store Hierarchy</term>
- <listitem>
- <para>
- A tree which shows the current object store hierarchy. Selecting a node from this tree displays the objects
- stored in that location.
- </para>
- </listitem>
-
- </varlistentry>
- <varlistentry>
- <term>Objects</term>
- <listitem>
- <para>
- A list of icons which represent the objects stored in the selected location.
- </para>
- </listitem>
-
- </varlistentry>
- <varlistentry>
- <term>Object Details</term>
- <listitem>
- <para>
- Information about the currently selected object, if the object’s type is known to the state viewer
- repository. See <xref linkend="writing-an-osv" /> for more details.
- </para>
- </listitem>
-
- </varlistentry>
-
- </variablelist>
- <section id="writing-an-osv">
- <title>Object state viewers (OSV)</title>
- <para>
- When an object is selected in the <guilabel>Objects</guilabel> pane of the main window, the registered Object
- State Viewer (OSV) for that object type is invoked. An OSV makes information about the selected object
- available via the user interface. An OSV for Atomic Actions is distributed with the standard tools. It displays
- information on the Abstract Records in its various lists, such as heuristic, failed, and read-only. You can
- write your own OSVs to display information about object types you have defined.
- </para>
-
- <section>
- <title>Writing an OSV</title>
- <para>
- Writing an OSV plug-in allows you to extend the capabilities of the Object Store browser to show the state of
- user-defined abstract records. An OSV plug-in is a class which implements the interface
- <interfacename>com.arjuna.ats.tools.objectstorebrowser.stateviewers.StateViewerInterface </interfacename>.
- Package it in a JAR within the <filename>plugins</filename> directory. This example shows how to create an OSV
- plug-in for an abstract record subclass which looks as follows:
- </para>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/abstract_record_subclass.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- <para>
- When this abstract record is viewed in the object store browser, showing the current value is simple. You can
- read the state into an instance of the abstract record and call <methodname>getValue()</methodname>. The
- following is the object store browser plug-in source code:
- </para>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/osv_plugin.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- <para>
- The method <methodname>uidNodeExpanded</methodname> is invoked when a Uid representing the given type is
- expanded in the object store hierarchy tree. This is not required by this plug-in as this abstract record is
- not visible in the object store directly, but only via one of the lists in an atomic action. The method
- <methodname>entrySelected</methodname> is invoked when an entry is selected from the object view which
- represents an object with the given type. In both methods the State Panel is used to display information
- regarding the state of the object. The State Panel has the following methods that assist in display this
- information:
- </para>
- <variablelist>
- <title>Methods of <classname>StatePanel</classname></title>
- <varlistentry>
- <term><methodname>setInfo</methodname>(<type>String</type> <varname>info</varname>)</term>
- <listitem>
- <para>
- Shows general information.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>setData</methodname>(<type>String</type> <varname>name</varname>, <type>String</type> <varname>value</varname>)</term>
- <listitem>
- <para>
- Puts information into the table which is displayed by the object store browser tool.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>enableDetailsButton</methodname>(<type>DetailsButtonListener</type> <varname>listener</varname>)</term>
- <listitem>
- <para>
- Enables the <guibutton>Details</guibutton> button. The listener interface allows a plug-in to be
- informed when the button is pressed. It is up to the plug-in developer to decide how to display this
- further information.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>
- This example reads the state from the object store and uses the value returned by
- <methodname>getValue()</methodname> to put an entry into the state panel table. The
- <methodname>getType()</methodname> method returns the type this plug-in is to be registered against.
- </para>
- <para>
- To add this plug-in to the object store browser, package it into a JAR file with a name that is prefixed with
- <filename>osv-</filename>. The JAR file must contain certain information within the manifest file so that the
- object store browser knows which classes are plug-ins. See <xref linkend="osv-plugin-ant" /> for how to do
- this using Apache Ant.
- </para>
-
- <example id="osv-plugin-ant">
- <title>Packaging an OSV using Apache Ant</title>
- <programlisting language="XML" role="XML"><xi:include href="extras/osv-plugin-ant.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
- <para>
- After creating the JAR with the correct information in the manifest file, place it in the
- <filename>bin/tools/plugins</filename> directory.
- </para>
- </section>
- </section>
-
-
- <section>
- <title>ObjectStore command-line editors</title>
- <para>
- There are currently two command-line editors for manipulating the ObjectStore. These tools are used to
- manipulate the lists of heuristic participants maintained by a transaction log. They allow a heuristic
- participant to be moved from that list back to the list of prepared participants so that transaction recovery
- may attempt to resolve them automatically.
- </para>
-
-
- <section>
- <title>LogEditor</title>
- <para>
- Started by executing <methodname>com.arjuna.ats.arjuna.tools.log.LogBrowser</methodname>, this tool supports
- the following options that can be provided on the command-line.
- </para>
- <table>
- <title>LogEditor Options</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Option</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>-tx <replaceable>id</replaceable></entry>
- <entry><para>Specifies the transaction log to work on.</para></entry>
- </row>
- <row>
- <entry>-type <replaceable>name</replaceable></entry>
- <entry><para>The transaction type to work on.</para></entry>
- </row>
- <row>
- <entry>-dump</entry>
- <entry><para>Print out the contents of the log identified by the other options.</para></entry>
- </row>
- <row>
- <entry>-forget <replaceable>index</replaceable></entry>
- <entry><para>Move the specified target from the heuristic list to the prepared list.</para></entry>
- </row>
- <row>
- <entry>-help</entry>
- <entry><para>Print out the list of commands and options.</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section>
- <title>LogBrowser</title>
- <para>
- The LogBrowser, invoked by calling <methodname>com.arjuna.ats.arjuna.tools.log.LogBrowser</methodname>, is
- similar to the LogEditor, but allows multiple log instances to be manipulated. It presents a shell-like
- interface, with the following options:
- </para>
-
- <table>
- <title>LogBrowserOptions</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Option</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>ls [<replaceable>type</replaceable>]</entry>
- <entry><para>List the logs for the specified type. If no type is specified, the editor must already be
- attached to the transaction type.</para></entry>
- </row>
- <row>
- <entry>select [<replaceable>type</replaceable>]</entry>
- <entry><para>Browse a specific transaction type. If already attached to a transaction type, you are
- detached from that type first.</para></entry>
- </row>
- <row>
- <entry>attach <replaceable>log</replaceable></entry>
- <entry><para>Attach the console to the specified transaction log. If you are attached to another log,
- the command will fail.</para></entry>
- </row>
- <row>
- <entry>detach</entry>
- <entry><para>Detach the console from the current log.</para></entry>
- </row>
- <row>
- <entry>forget <replaceable>pid</replaceable></entry>
- <entry><para>Move the specified heuristic participant back to the <systemitem>prepared</systemitem>
- list. The console must be attached.</para></entry>
- </row>
- <row>
- <entry>delete <replaceable>pid</replaceable></entry>
- <entry><para>Delete the specified heuristic participant. The console must be attached.</para></entry>
- </row>
- <row>
- <entry>types</entry>
- <entry><para>List the supported transaction types.</para></entry>
- </row>
- <row>
- <entry>quit</entry>
- <entry><para>Exit the console tool.</para></entry>
- </row>
- <row>
- <entry>help</entry> <entry><para>Print out the supported commands.</para></entry> </row> </tbody>
- </tgroup> </table> </section> </section> </section> </chapter>
Modified: labs/jbosstm/trunk/ArjunaCore/docs/failure_recovery_guide/en-US/ArjunaCore_Failure_Recovery_Guide.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaCore/docs/failure_recovery_guide/en-US/ArjunaCore_Failure_Recovery_Guide.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaCore/docs/failure_recovery_guide/en-US/ArjunaCore_Failure_Recovery_Guide.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,17 +1,11 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "ArjunaCore_Failure_Recover_Guide.ent">
-<!ENTITY PRODUCT "JBoss Transactions">
-<!ENTITY BOOKID "ArjunaCore_Failure_Recover_Guide">
-<!ENTITY VERSION "4.15">
-<!ENTITY YEAR "2011">
-<!ENTITY HOLDER "JBoss.org">
-<!ENTITY APPSERVER "JBoss Application Server">
-<!-- <!ENTITY APPSERVER "Enterprise Application Platform Server"> -->]>
+]>
<book>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Book_Info.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Preface.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Further_failure_recovery.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Revision_History.xml"/>
- <index/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Book_Info.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Preface.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Further_failure_recovery.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Revision_History.xml" />
+ <!-- <index /> -->
</book>
Modified: labs/jbosstm/trunk/ArjunaJTA/docs/administration_guide/en-US/JBossJTA_Administration_Guide.ent
===================================================================
--- labs/jbosstm/trunk/ArjunaJTA/docs/administration_guide/en-US/JBossJTA_Administration_Guide.ent 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaJTA/docs/administration_guide/en-US/JBossJTA_Administration_Guide.ent 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,4 +1,4 @@
<!ENTITY PRODUCT "JBossJTA">
<!ENTITY BOOKID "JBossJTA_Administration_Guide">
-<!ENTITY YEAR "2010">
+<!ENTITY YEAR "2011">
<!ENTITY HOLDER "JBoss.org">
Modified: labs/jbosstm/trunk/ArjunaJTA/docs/administration_guide/en-US/JBossJTA_Administration_Guide.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTA/docs/administration_guide/en-US/JBossJTA_Administration_Guide.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaJTA/docs/administration_guide/en-US/JBossJTA_Administration_Guide.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -6,7 +6,6 @@
<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="Introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Starting_And_Stopping_Transaction_Manager.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="ObjectStore_Management.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
@@ -15,5 +14,5 @@
<xi:include href="Errors_And_Exceptions.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="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <index />
+ <!-- <index /> -->
</book>
Added: labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/About_This_Guide.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/About_This_Guide.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/About_This_Guide.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -0,0 +1,39 @@
+<?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" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "JBossJTA_Development_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>About This Guide</title>
+ <para>
+ The Stand-alone JTA Programmers Guide contains information on how to use &PRODUCT;
+ outside of an application server.
+ </para>
+ <section>
+ <title>Audience</title>
+ <para>
+ This guide is most relevant to engineers who want to use &PRODUCT;
+ in
+ installations that are not covered elsewhere. It is assumed that the reader is already
+ familiar with the core &PRODUCT;
+ documentation set.
+ </para>
+ </section>
+ <section>
+ <title>Prerequisites</title>
+ <para>
+ This guide assumes a basic familiarity with Java service development and object-oriented
+ programming. A fundamental level of understanding in the following areas will also be useful:
+ <itemizedlist>
+ <listitem>
+ <para>General understanding of the APIs, components, and objects that are present in Java
+ applications.</para>
+ </listitem>
+ <listitem>
+ <para>A general understanding of the Windows and UNIX operating systems.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+</chapter>
+
Modified: labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/JBossJTA_Development_Guide.ent
===================================================================
--- labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/JBossJTA_Development_Guide.ent 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/JBossJTA_Development_Guide.ent 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,4 +1,4 @@
<!ENTITY PRODUCT "Documentation">
<!ENTITY BOOKID "JBossJTA_Development_Guide">
-<!ENTITY YEAR "2010">
+<!ENTITY YEAR "2011">
<!ENTITY HOLDER "JBoss, Inc.">
Modified: labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/JBossJTA_Development_Guide.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/JBossJTA_Development_Guide.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/JBossJTA_Development_Guide.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -4,18 +4,14 @@
%BOOK_ENTITIES;
]>
<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="Java_Transaction_API.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Transactions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="The_Resource_Manager.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Transaction_Recovery.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="JDBC.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Examples.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Configuring_JBossTA.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Using_JBossTA_In_Application_Servers.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <index />
+ <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Preface.xml" />
+ <xi:include href="About_This_Guide.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JDBC.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Examples.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Using_JBossTA_In_Application_Servers.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Configuring_JBossTA.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <!-- <index /> -->
</book>
Deleted: labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/Java_Transaction_API.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/Java_Transaction_API.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/Java_Transaction_API.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,84 +0,0 @@
-<?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" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "JBossJTA_Development_Guide.ent">
-%BOOK_ENTITIES;
-]>
-<chapter>
- <title>The Java Transaction API (JTA)</title>
- <para>
- The interfaces specified by the many transaction standards tend to be too low-level for most application
- programmers. Therefore, Sun Microsystems created the Java Transaction API (JTA), which specifies higher-level
- interfaces to assist in the development of distributed transactional applications.
- </para>
- <para>
- Note, these interfaces are still low-level. You still need to implement state management and concurrency for
- transactional applications. The interfaces are also optimized for applications which require XA resource integration
- capabilities, rather than the more general resources which other transactional APIs allow.
- </para>
- <para>
- With reference to JTA 1.1 (<ulink url="http://www.oracle.com/technetwork/java/javaee/tech/jta-138684.html" />),
- distributed transaction services typically involve a number of participants:
- </para>
- <informaltable>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>application server</entry>
- <entry>
- <para>
- provides the infrastructure required to support the application run-time environment which includes
- transaction state management, such as an EJB server.
- </para>
- </entry>
- </row>
- <row>
- <entry>transaction manager</entry>
- <entry>
- <para>
- provides the services and management functions required to support transaction demarcation, transactional
- resource management, synchronization, and transaction context propagation.
- </para>
- </entry>
- </row>
- <row>
- <entry>resource manager</entry>
- <entry>
- <para>
- Using a <firstterm>resource adapter</firstterm>, provides the application with access to resources. The
- resource manager participates in distributed transactions by implementing a transaction resource interface
- used by the transaction manager to communicate transaction association, transaction completion and
- recovery.
- </para>
- <para>
- A resource adapter is used by an application server or client to connect to a Resource Manager. JDBC
- drivers which are used to connect to relational databases are examples of Resource Adapters.
- </para>
- </entry>
- </row>
- <row>
- <entry>communication resource manager</entry>
- <entry>
- <para>
- supports transaction context propagation and access to the transaction service for incoming and outgoing
- requests.
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <para>
- From the point of view of the transaction manager, the actual implementation of the transaction services does not
- need to be exposed. You only need to define high-level interfaces to allow transaction demarcation, resource
- enlistment, synchronization and recovery process to be driven from the users of the transaction services. The JTA is
- a high-level application interface that allows a transactional application to demarcate transaction boundaries, and
- also contains a mapping of the X/Open XA protocol.
- </para>
- <important>
- <title>Compatibility</title>
- <para>
- the JTA support provided by JBossJTA is compliant with the 1.1 specification.
- </para>
- </important>
-</chapter>
-
Modified: labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/Revision_History.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/Revision_History.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/Revision_History.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -21,6 +21,20 @@
</simplelist>
</revdescription>
</revision>
+ <revision>
+ <revnumber>0-0</revnumber>
+ <date>Thu Apr 14 2011</date>
+ <author>
+ <firstname>Tom</firstname>
+ <surname>Jenkinson</surname>
+ <email>tom.jenkinson at redhat.com</email>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Moved some content to the main development guide</member>
+ </simplelist>
+ </revdescription>
+ </revision>
</revhistory>
</simpara>
</appendix>
Deleted: labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/The_Resource_Manager.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/The_Resource_Manager.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/The_Resource_Manager.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,394 +0,0 @@
-<?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" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "JBossJTA_Development_Guide.ent">
-%BOOK_ENTITIES;
-]>
-<chapter>
- <title>The Resource Manager</title>
-
-
- <section>
- <title>The <interfacename>XAResource</interfacename> interface</title>
- <para>
- Some transaction specifications and systems define a generic resource which can be used to register arbitrary
- resources with a transaction, the JTA is much more XA-specific. Interface
- <interfacename>javax.transaction.xa.XAResource</interfacename> is a Java mapping of the XA interface. The
- <interfacename>XAResource</interfacename> interface defines the contract between a
- <interfacename>ResourceManager</interfacename> and a <interfacename>TransactionManager</interfacename> in a
- distributed transaction processing environment. A resource adapter for a
- <interfacename>ResourceManager</interfacename> implements the <interfacename>XAResource</interfacename> interface
- to support association of a top-level transaction to a resource such as a relational database.
- </para>
- <para>
- The <interfacename>XAResource</interfacename> interface can be supported by any transactional resource adapter
- designed to be used in an environment where transactions are controlled by an external transaction manager, such a
- database management system. An application may access data through multiple database connections. Each database
- connection is associated with an <interfacename>XAResource</interfacename> object that serves as a proxy object to
- the underlying <interfacename>ResourceManager</interfacename> instance. The transaction manager obtains an
- <interfacename>XAResource</interfacename> for each <interfacename>ResourceManager</interfacename> participating in
- a top-level transaction. The <methodname>start</methodname> method associates the transaction with the resource,
- and the <methodname>end</methodname> method disassociates the transaction from the resource.
- </para>
- <para>
- The <interfacename>ResourceManager</interfacename> associates the transaction with all work performed on its data
- between invocation of <methodname>start</methodname> and <methodname>end</methodname> methods. At transaction
- commit time, these transactional <interfacename>ResourceManager</interfacename>s are informed by the transaction
- manager to prepare, commit, or roll back the transaction according to the two-phase commit protocol.
- </para>
- <para>
- For better Java integration, the <interfacename>XAResource</interfacename> differs from the standard
- <interfacename>XA</interfacename> interface in the following ways:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- The resource adapter implicitly initializes the <interfacename>ResourceManager</interfacename> when the
- resource (the connection) is acquired. There is no equivalent to the <methodname>xa_open</methodname> method
- of the interface <interfacename>XA</interfacename>.
- </para>
- </listitem>
- <listitem>
- <para>
- <varname>Rmid</varname> is not passed as an argument. Each <varname>Rmid</varname> is represented by a
- separate <interfacename>XAResource</interfacename> object.
- </para>
- </listitem>
- <listitem>
- <para>
- Asynchronous operations are not supported, because Java supports multi-threaded processing and most databases
- do not support asynchronous operations.
- </para>
- </listitem>
- <listitem>
- <para>
- Error return values caused by the transaction manager’s improper handling of the
- <interfacename>XAResource</interfacename> object are mapped to Java exceptions via the
- <classname>XAException</classname> class.
- </para>
- </listitem>
- <listitem>
- <para>
- The DTP concept of <phrase>Thread of Control</phrase> maps to all Java threads that are given access to the
- <interfacename>XAResource</interfacename> and <interfacename>Connection</interfacename> objects. For example,
- it is legal for two different threads to perform the <methodname>start</methodname> and
- <methodname>end</methodname> operations on the same <interfacename>XAResource</interfacename> object.
- </para>
- </listitem>
- </itemizedlist>
-
- <section>
- <title>Extended <interfacename>XAResource</interfacename> control</title>
- <para>
- By default, whenever an <interfacename>XAResource</interfacename> object is registered with a JTA-compliant
- transaction service, there is no way to manipulate the order in which it is invoked during the two-phase commit
- protocol, with respect to other <interfacename>XAResource</interfacename> objects. JBossTS, however, provides
- support for controlling the order via the two interfaces
- <interfacename>com.arjuna.ats.jta.resources.StartXAResource</interfacename> and
- <interfacename>com.arjuna.ats.jta.resources.EndXAResource</interfacename>. By inheriting your
- <interfacename>XAResource</interfacename> instance from either of these interfaces, you control whether an
- instance of your class is invoked first or last, respectively.
- </para>
- <note>
- <para>
- Only one instance of each interface type may be registered with a specific transaction.
- </para>
- </note>
- <para>
- The <citetitle>ArjunaCore Development Guide</citetitle> discusses the <firstterm>Last Resource Commit
- optimization (LRCO)</firstterm>, whereby a single resource that is only one-phase aware, and does not support
- the <methodname>prepare</methodname> phase, can be enlisted with a transaction that is manipulating two-phase
- aware participants. This optimization is also supported within the JBossTA.
- </para>
- <para>
- In order to use the LRCO, your <interfacename>XAResource</interfacename> implementation must extend the
- <interfacename>com.arjuna.ats.jta.resources.LastResourceCommitOptimisation</interfacename> marker interface. A
- marker interface is an interface which provides no methods. When
- enlisting the resource via method <methodname>Transaction.enlistResource</methodname>, JBossTS ensures that only a single instance of this
- type of participant is used within each transaction. Your resource is driven last in the commit protocol,
- and no invocation of method <methodname>prepare</methodname> occurs.
- </para>
- <para>
- By default an attempt to enlist more than one instance of a LastResourceCommitOptimisation class will fail and
- false will be returned from Transaction.enlistResource. This behavior can be overridden by setting the
- com.arjuna.ats.jta.allowMultipleLastResources to true. However, before doing so you should read the section on
- enlisting multiple one-phase aware resources.
- </para>
- <important>
- <para>
- You need to disable interposition support to use the LCRO in a distributed environment. You can still use
- implicit context propagation.
- </para>
- </important>
- <section>
- <title>Enlisting multiple one-phase-aware resources</title>
- <para>
- One-phase commit is used to process a single one-phase aware resource, which does not conform to the
- two-phase commit protocol. You can still achieve an atomic outcome across resources, by using the LRCO, as
- explained earlier.
- </para>
- <para>
- Multiple one-phase-aware resources may be enlisted in the same transaction. One example is when a legacy
- database runs within the same transaction as a legacy JMS implementation. In such a situation, you cannot
- achieve atomicity of transaction outcome across multiple resources, because none of them enter the
- <methodname>prepare</methodname> state. They commit or roll back immediately when instructed by the
- transaction coordinator, without knowledge of other resource states and without a way to undo if subsequent
- resources make a different choice. This can result in data corruption or heuristic outcomes.
- </para>
- <para>
- You can approach these situations in two different ways:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Wrap the resources in compensating transactions. See the <citetitle>XTS Transactions Development
- Guide</citetitle> for details.
- </para>
- </listitem>
- <listitem>
- <para>
- Migrate the legacy implementations to two-phase aware equivalents.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- If neither of these options is viable, JBossTS support enlisting multiple
- one-phase aware resources within the same transaction, using LRCO, which is discussed in the
- <citetitle>ArjunaCore Development Guide</citetitle> in detail.
- </para>
- <warning>
- <para>
- Even when this support is enabled, JBossTS issues a warning when it detects that the option has been
- enabled: <literal>You have chosen to enable multiple last resources in the transaction manager. This is
- transactionally unsafe and should not be relied upon.</literal> Another warning is issued when multiple
- one-phase aware resources are enlisted within a transaction: <literal>This is transactionally unsafe and
- should not be relied on.</literal>
- </para>
- <para>
- To override the above-mentioned warning at runtime, set the
- <varname>CoreEnvironmentBean.disableMultipleLastResourcesWarning</varname> property to
- <literal>true</literal>. You will see a warning that you have done this when JBossTS starts up and see the
- warning about enlisting multiple one-phase resources only the first time it happens, but after that no
- further warnings will be output. You should obviously only consider changing the default value of this
- property (false) with caution.
- </para>
- </warning>
- </section>
- </section>
- </section>
-
- <section>
- <title>Opening a resource manager</title>
- <para>
- The X/Open <interfacename>XA</interfacename> interface requires the transaction manager to initialize a resource
- manager, using method <methodname>xa_open</methodname>, before invoking any other of the interface's methods. JTA
- requires initialization of a resource manager to be embedded within the resource adapter that represents the
- resource manager. The transaction manager does not need to know how to initialize a resource manager. It only
- informs the resource manager about when to start and end work associated with a transaction and when to complete
- the transaction. The resource adapter opens the resource manager when the connection to the resource manager is
- established.
- </para>
- </section>
-
- <section>
- <title>Closing a resource manager</title>
- <para>
- The resource adapter closes a resource manager as a result of destroying the transactional resource. A
- transaction resource at the resource adapter level is comprised of two separate objects:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- An <interfacename>XAResource</interfacename> object that allows the transaction manager to start and end the
- transaction association with the resource in use and to coordinate transaction completion process.
- </para>
- </listitem>
- <listitem>
- <para>
- A connection object that allows the application to perform operations on the underlying resource, such as JDBC
- operations on an RDBMS.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- Once opened, the resource manager is kept open until the resource is released explicitly. When the application
- invokes the connection’s <methodname>close</methodname> method, the resource adapter invalidates the connection
- object reference that was held by the application and notifies the application server about the close. The
- transaction manager invokes the <methodname>XAResource.end</methodname> method to disassociate the transaction
- from that connection.
- </para>
- <para>
- The close notification triggers the application server to perform any necessary cleanup work and to mark the
- physical XA connection as free for reuse, if connection pooling is in place.
- </para>
- </section>
-
- <section>
- <title>Thread of control</title>
- <para>
- The X/Open <interfacename>XA</interfacename> interface specifies that the transaction-association-related
- <systemitem>xa</systemitem> calls must be invoked from the same thread context. This
- <firstterm>thread-of-control</firstterm> requirement does not apply to the object-oriented component-based
- application run-time environment, in which application threads are dispatched dynamically as methods are
- invoked.. Different threads may use the same connection resource to access the resource manager if the connection
- spans multiple method invocation. Depending on the implementation of the application server, different threads may
- be involved with the same <interfacename>XAResource</interfacename> object. The resource context and the
- transaction context operate independent of thread context. This creates the possibility of different threads
- invoking the <methodname>start</methodname> and <methodname>end</methodname> methods.
- </para>
- <para>
- If the application server allows multiple threads to use a single <interfacename>XAResource</interfacename> object
- and the associated connection to the resource manager, the application server must ensure that only one
- transaction context is associated with the resource at any point of time. Thus the
- <interfacename>XAResource</interfacename> interface requires the resource managers to support the two-phase commit
- protocol from any thread context.
- </para>
- </section>
-
- <section>
- <title>Transaction association</title>
- <para>
- A transaction is associated with a transactional resource via the <methodname>start</methodname> method and disassociated from the
- resource via the <methodname>end</methodname> method. The resource adapter internally maintains an association between
- the resource connection object and the <interfacename>XAResource</interfacename> object. At any given time, a
- connection is associated with zero or one transaction. JTA does not support nestedtransactions, so attempting to
- invoke the <methodname>start</methodname> method on a thread that is already associated with a transaction is an error.
- </para>
- <para>
- The transaction manager can Interleave multiple transaction contexts using the same resource, as long as methods
- <methodname>start</methodname> and <methodname>end</methodname> are invoked properly for each transaction context
- switch. Each time the resource is used with a different transaction, the method <methodname>end</methodname> must
- be invoked for the previous transaction that was associated with the resource, and method
- <methodname>start</methodname> must be invoked for the current transaction context.
- </para>
- </section>
-
- <section>
- <title>Externally controlled connections</title>
- <para>
- For a transactional application whose transaction states are managed by an application server, its resources must
- also be managed by the application server so that transaction association is performed properly. If an application
- is associated with a transaction, the application must not perform transactional work through the
- connection without having the connection’s resource object already associated with the global transaction. The
- application server must ensure that the <interfacename>XAResource</interfacename> object in use is associated with
- the transaction, by invoking the <methodname>Transaction.enlistResource</methodname> method.
- </para>
- <para>
- If a server-side transactional application retains its database connection across multiple client requests, the
- application server must ensure that before dispatching a client request to the application thread, the resource is
- enlisted with the application’s current transaction context. This implies that the application server manages the
- connection resource usage status across multiple method invocations.
- </para>
- </section>
-
- <section>
- <title>Resource sharing</title>
- <para>
- When the same transactional resource is used to interleave multiple transactions, the application server must
- ensure that only one transaction is enlisted with the resource at any given time. To initiate the transaction
- commit process, the transaction manager is allowed to use any of the resource objects connected to the same
- resource manager instance. The resource object used for the two-phase commit protocol does not need to have been
- involved with the transaction being completed.
- </para>
- <para>
- The resource adapter must be able to handle multiple threads invoking the
- <interfacename>XAResource</interfacename> methods concurrently for transaction commit processing. This is
- illustrated in <xref linkend="resource_sharing_example" />.
- </para>
- <example id="resource_sharing_example">
- <title>Resource sharing example</title>
- <programlisting language="Java" role="JAVA">
- <xi:include href="extras/resource_sharing_example.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" />
- </programlisting>
- <para>
- A transactional resource <systemitem>r1</systemitem>. Global transaction <systemitem>xid1</systemitem> is
- started and ended with r1. Then a different global transaction <systemitem>xid2</systemitem> is associated with
- <systemitem>r1</systemitem>. Meanwhile, the transaction manager may start the two phase commit process for
- <systemitem>xid1</systemitem> using <systemitem>r1</systemitem> or any other transactional resource connected to
- the same resource manager. The resource adapter needs to allow the commit process to be executed while the
- resource is currently associated with a different global transaction.
- </para>
- </example>
- </section>
-
- <section>
- <title>Local and global transactions</title>
- <para>
- The resource adapter must support the usage of both local and global transactions within the same transactional
- connection. Local transactions are started and coordinated by the resource manager internally. The
- <interfacename>XAResource</interfacename> interface is not used for local transactions. When using the same
- connection to perform both local and global transactions, the following rules apply:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- The local transaction must be committed or rolled back before a global transaction is started in the
- connection.
- </para>
- </listitem>
- <listitem>
- <para>
- The global transaction must be disassociated from the connection before any local transaction is started.
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
-
- <section>
- <title>Transaction timeouts</title>
- <para>
- You can associate timeout values with transactions in order to control their lifetimes. If the timeout value
- elapses before a transaction terminates, by committing or rolling back, the transaction system rolls it back. The
- <interfacename>XAResource</interfacename> interface supports a <methodname>setTransactionTimeout</methodname>
- operation, which allows the timeout associated with the current transaction to be propagated to the resource
- manager and if supported, overrides any default timeout associated with the resource manager. Overriding the
- timeout can be useful when long-running transactions may have lifetimes that would exceed the default, and using
- the default timeout would cause the resource manager to roll back before the transaction terminates, and cause the
- transaction to roll back as well.
- </para>
- <para>
- If You do not explicitly set a timeout value for a transaction, or you use a value of <literal>0</literal>, an
- implementation-specific default value may be used. In JBossTS, property value
- <varname>CoordinatorEnvironmentBean.defaultTimeout</varname> represents this implementation-specific default, in
- seconds. The default value is 60 seconds. A value of <literal>0</literal> disables default transaction timeouts.
- </para>
- <para>
- Unfortunately, imposing the same timeout as the transaction on a resource manager is not always appropriate. One
- example is that your business rules may require you to have control over the lifetimes on resource managers
- without allowing that control to be passed to some external entity. JBossTS supports an all-or-nothing approach to
- whether or not method <methodname>setTransactionTimeout</methodname> is called on
- <interfacename>XAResource</interfacename> instances.
- </para>
- <para>
- If the <varname>JTAEnvironmentBean.xaTransactionTimeoutEnabled</varname> property is set to
- <literal>true</literal>, which is the default, it is called on all instances. Otherwise, use the
- <methodname>setXATransactionTimeoutEnabled</methodname> method of
- <interfacename>com.arjuna.ats.jta.common.Configuration</interfacename>.
- </para>
-
- </section>
-
- <section>
- <title>Dynamic registration</title>
- <para>
- Dynamic registration is not supported in <interfacename>XAResource</interfacename>. There are two reasons this
- makes sense.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- In the Java component-based application server environment, connections to the resource manager are acquired
- dynamically when the application explicitly requests a connection. These resources are enlisted with the
- transaction manager on an as-needed basis.
- </para>
- </listitem>
- <listitem>
- <para>
- If a resource manager needs to dynamically register its work to the global transaction, you can implement this
- at the resource adapter level via a private interface between the resource adapter and the underlying resource
- manager.
- </para>
- </listitem>
- </itemizedlist>
- </section>
-</chapter>
Deleted: labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/Transaction_Recovery.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/Transaction_Recovery.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/Transaction_Recovery.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,254 +0,0 @@
-<?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" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "JBossJTA_Development_Guide.ent">
-%BOOK_ENTITIES;
-]>
-<chapter>
- <title>Transaction Recovery</title>
-
- <section>
- <title>Failure recovery</title>
- <para>
- During recovery, the Transaction Manager must communicate with all resource managers being used by the
- applications in the system. For each resource manager, the Transaction Manager uses the
- <methodname>XAResource.recover</methodname> method to retrieve the list of transactions that are currently in a
- <systemitem>prepared</systemitem> or <systemitem>heuristically completed</systemitem> state. Typically, a system
- administrator, rather than a developer, configures all transactional resource factories that are used by the
- applications deployed on the system. The JDBC <interfacename>XADataSource</interfacename> object, which is a
- factory for JDBC <interfacename>XAConnection</interfacename> objects, is such an example..
- </para>
- <para>
- <interfacename>XAResource</interfacename> objects are not persistent across system failures, so the Transaction
- Manager needs a way to acquire the <interfacename>XAResource</interfacename> objects representing the resource
- managers which might have participated in the transactions before a system failure. For example, a Transaction
- Manager might use the JNDI look-up mechanism to acquire a connection from each of the transactional resource
- factories, before obtaining the corresponding <interfacename>XAResource</interfacename> object for each
- connection. The Transaction Manager then invokes the <methodname>XAResource.recover</methodname> method, which
- requests each resource manager to return the transactions that are currently in a
- <systemitem>prepared</systemitem> or <systemitem>heuristically completed</systemitem> state.
- </para>
- <para>
- XA recovery necessitates informing JBossTS which types of Xid to recover. Each Xid that JBossTS
- creates has a unique node identifier encoded within it, and JBossTS only recovers transactions and states that
- match a specified node identifier. Provide the node identifier to JBossTS with the property
- <varname>JTAEnvironmentBean.xaRecoveryNodes</varname>. You can pass multiple values in a list.
- </para>
- <warning>
- <para>
- Setting <varname>JTAEnvironmentBean.xaRecoveryNodes</varname> to <literal>*</literal> forces JBossTS to recover,
- and possibly roll back, all transactions, regardless of their node identifiers. Use this value only with extreme
- caution.
- </para>
- </warning>
- <para>
- If you use the JBossJTA JDBC driver, JBossJTA manages all XAResource crash recovery
- automatically. Otherwise one of the following recovery mechanisms is used.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- If the <interfacename>XAResource</interfacename> is serializable, the serialized form is saved during
- transaction commitment, and used during recovery. The recreated <interfacename>XAResource</interfacename> is
- assumed to be valid, and you can use it to drive recovery on the associated database.
- </para>
- </listitem>
- <listitem>
- <para>
- Otherwise, interfaces <interfacename>com.arjuna.ats.jta.recovery.XAResourceRecovery</interfacename>,
- <interfacename>com.arjuna.ats.jta.recovery.XARecoveryResourceManager</interfacename>, and
- <methodname>com.arjuna.ats.jta.recovery.XARecoveryResource</methodname> are used. Each is documented in the
- JDBC chapters on failure recovery.<!-- Where is this? -->
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>Recovering XA connections</title>
- <para>
- During failure recovery, JBossJTA needs the ability to reconnect to databases that were in use prior to the
- failures, to resolve any outstanding transactions. Most connection information is saved by the transaction service
- during its normal execution, and can be used during recovery to recreate the connection. However, sometimes a
- failure occurs before all of the information can be saved, but after the database connection is used. For JBossTS
- to recreate connections in this type of scenario, you need to provide implementations of JBossJTA interface
- <interfacename>com.arjuna.ats.jta.recovery.XAResourceRecovery</interfacename> for each database in use by your
- applications.
- </para>
- <note>
- <para>
- The transactional JDBC driver provided with JBossJTA does all of this work for you.
- </para>
- </note>
- <para>
- To inform the recovery system about each of the <interfacename>XAResourceRecovery</interfacename> instances,
- specify their class names through the <varname>JTAEnvironmentBean.xaResourceRecoveryInstances</varname> property
- variable, as a list of space-separated strings. Each string is a classname followed by optional configuration
- information.
- </para>
- <example>
- <title>Example <varname>JTAEnvironmentBean.xaResourceRecoveryInstances</varname> value</title>
- <para>
- Without configuration information:
- </para>
- <screen>JTAEnvironmentBean.xaResourceRecoveryInstances=com.foo.barRecovery</screen>
- <para>
- With configuration information:
- </para>
- <screen>JTAEnvironmentBean.xaResourceRecoveryInstances=com.foo.barRecovery;myData=hello</screen>
- </example>
- <para>
- These properties need to go into the JTA section of the property file. Any errors will be reported during
- recovery.
- </para>
-
- <example>
- <title>Example <interfacename>XAResourceRecovery</interfacename> implementation</title>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/XAResourceRecovery_implementation.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
-
- <table>
- <title>Return values for <interfacename>XAResourceRecovery</interfacename> methods</title>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>initialise</entry>
- <entry>
- <para>
- After the instance is created, any additional information found after the first semi-colon is passed to
- the object. The object can then use this information in an implementation-specific manner to initialise
- itself, or for another purpose.
- </para>
- </entry>
- </row>
- <row>
- <entry>hasMoreResources</entry>
- <entry>
- <para>
- Each <interfacename>XAResourceRecovery</interfacename> implementation may provide multiple
- <interfacename>XAResource</interfacename> instances. Before any call to method
- <methodname>getXAResource</methodname> is made, method <methodname>hasMoreResources</methodname> is
- called to determine whether there are any further connections to be obtained. If this returns
- <literal>false</literal>, <methodname>getXAResource</methodname> is not called again during this
- recovery sweep, and the instance is not used again until the next recovery scan. The implementation must
- maintain the internal state backing this method and reset the iteration as required. Otherwise, the
- second and subsequent recovery sweeps in the lifetime of the JVM do not attempt recovery.
- </para>
- </entry>
- </row>
- <row>
- <entry>getXAResource</entry>
- <entry>
- <para>
- Returns an instance of the XAResource object. The <interfacename>XAResourceRecovery</interfacename>
- implementation determines how the instance is created, and how the parameters to its constructors are
- obtained. The parameters to the constructors of this class are similar to the ones used when creating
- the initial driver or data source, and must be sufficient to create new
- <interfacename>XAResource</interfacename>s to drive recovery.
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <note>
- <title>Calling <interfacename>XAResourRecovery</interfacename> during each sweep</title>
- <para>
- To ensure that your <interfacename>XAResourceRecovery</interfacename> instance is called during each sweep of the
- recovery manager, make sure that once method <methodname>hasMoreResources</methodname> returns
- <literal>false</literal> to indicate the end of work for the current scan, it returns <literal>true</literal> for
- the next recovery scan.
- </para>
- </note>
- </section>
-
- <section>
- <title>Alternative to XAResourceRecovery</title>
- <para>
- The iterator-based approach used by <interfacename>XAResourceRecovery</interfacename> requires implementations to
- manage state, which adds complexity. Starting with JBossTS 4.4, you can provide an implementation of public
- interface <interfacename>XAResourceRecoveryHelper</interfacename>:
- </para>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/XAResourceRecoveryHelper.java"
- xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
-
- <para>
- During each recovery sweep, method <methodname>getXAResources</methodname> is called and recovery is attempted on
- each element of the array. For the majority of resource managers, only one
- <interfacename>XAResource</interfacename> is needed in the array, because the <methodname>recover()</methodname>
- call on it can return multiple Xids.
- </para>
- <para>
- Unlike <interfacename>XAResourceRecovery</interfacename> instances, which are configured via the XML properties
- file and instantiated by JBossTS, instances of <interfacename>XAResourceRecoveryHelper</interfacename> are
- constructed by the application code and registered with JBossTS by calling
- <methodname>XARecoveryModule.addXAResourceRecoveryHelper</methodname>.
- </para>
- <para>
- Method <methodname>initialize</methodname> is not called by JBossTS in the current implementation. It is provided
- to allow for the addition of further configuration options in later releases.
- </para>
- <para>
- You can register <interfacename>XAResourceRecoveryHelper</interfacename> instances with the
- <methodname>XARecoverModule.removeXAResourceRecoveryHelper</methodname> method. After registration, they are no
- longer called by the recovery manager. Deregistration may block for a time if a recovery scan is in progress.
- </para>
- <para>
- The ability to dynamically add and remove instances of <interfacename>XAResourceRecoveryHelper</interfacename>
- while the system is running is an attractive option for environments where datasources may be deployed or
- undeployed, such as application servers. Take care with classloading behavior in such cases.
- </para>
- </section>
-
- <section>
- <title>Shipped XAResourceRecovery implementations</title>
- <para>
- Recovery of XA datasources can sometimes be implementation-dependent, requiring you to provide your own
- <interfacename>XAResourceRecovery</interfacename> instances. However, JBossTS ships with several useful
- implementations.
- </para>
- <para>
- These <interfacename>XAResourceRecovery</interfacename> instances are primarily intended for when running JBossTS
- outside of a container such as JBoss Application Server or another application server. This is because they rely upon
- <interfacename>XADataSources</interfacename> as the primary handle to drive recovery. If you are running JBossTS
- inside an application server or other container, consult the relevant integration documentation, to be sure to use
- the right recovery modules.
- </para>
-
- <section>
- <title>com.arjuna.ats.internal.jdbc.recovery.BasicXARecovery</title>
- <para>
- <interfacename>com.arjuna.ats.internal.jdbc.recovery.BasicXARecovery</interfacename> expects you to specify an
- XML property file upon creation. It uses this file to read the configuration properties for the datasource.
- </para>
- <example>
- <title>Example</title>
- <programlisting language="XML" role="XML"><xi:include href="extras/BasicXARecovery_Config_Example.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
- </section>
-
- <section>
- <title>com.arjuna.ats.internal.jdbc.recovery.JDBCXARecovery</title>
- <para>
- <interfacename>com.arjuna.ats.internal.jdbc.recovery.JDBCXARecovery</interfacename> should work on any
- datasource that is exposed via JNDI. It expects an XML property file to be specified upon creation, and uses the
- file to read the database JNDI name, user-name and password.
- </para>
- <example>
- <title>Example</title>
- <programlisting language="XML" role="XML"><xi:include href="extras/JDBCXARecovery_Config_Example.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
- </section>
- <section>
- <title>Initializing the Implementations</title>
- <para>
- Because these classes are <interfacename>XAResourceRecovery</interfacename> instances, they receive any
- necessary initialization information from the <methodname>initialise</methodname> operation. In the case of
- <interfacename>BasicXARecovery</interfacename> and <methodname>JDBCXARecovery</methodname>, the information is
- the location of a property file, and is specified in the JBossTS configuration file. For example:
- </para>
- <screen>
-com.arjuna.ats.jta.recovery.XAResourceRecoveryJDBC=com.arjuna.ats.internal.jdbc.recovery.JDBCXAResourceRecovery;thePropertyFile
- </screen>
- </section>
- </section>
-</chapter>
Deleted: labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/Transactions.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/Transactions.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaJTA/docs/development_guide/en-US/Transactions.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,381 +0,0 @@
-<?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" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "JBossJTA_Development_Guide.ent">
-%BOOK_ENTITIES;
-]>
-<chapter>
- <title>Transactions</title>
- <para>
- A transaction is a unit of work that encapsulates multiple database actions such that that either all the
- encapsulated actions fail or all succeed.
- </para>
- <para>
- Transactions ensure data integrity when an application interacts with multiple datasources.
- </para>
- <section>
- <title>Introducing the API</title>
- <para>
- The Java Transaction API consists of three elements:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- a high-level application transaction demarcation interface
- </para>
- </listitem>
- <listitem>
- <para>
- a high-level transaction manager interface intended for application server
- </para>
- </listitem>
- <listitem>
- <para>
- a standard Java mapping of the X/Open XA protocol intended for a transactional resource manager.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- All of the JTA classes and interfaces exist within the <package>javax.transaction</package> package, and the
- corresponding JBossJTA implementations within the <package>com.arjuna.ats.jta</package> package.
- </para>
- <para>
- Each Xid created by JBossTS needs a unique node identifier encoded within it, because JBossTS can only recover
- transactions and states that match a specified node identifier. The node identifier to use should be provided to
- JBossTS via the <varname>CoreEnvironmentBean.nodeIdentifier</varname> property. This value must be unique across
- your JBossTS instances. The identifier is alphanumeric and limited to 10 bytes in length. If you do not provide a
- value, then JBossTS generates one and reports the value via the logging infrastructure.
- </para>
-
- </section>
-
- <section id="UserTransaction_Definition">
- <title>UserTransaction</title>
- <para>
- The <interfacename>UserTransaction</interfacename> interface provides applications with the ability to control
- transaction boundaries. It provides methods <methodname>begin</methodname>, <methodname>commit</methodname>, and
- <methodname>rollback</methodname> to operate on top-level transactions.
- </para>
- <para>
- Nested transactions are not supported, and method <methodname>begin</methodname> throws the exception
- <systemitem>NotSupportedException</systemitem> if the calling thread is already associated with a
- transaction. <interfacename>UserTransaction</interfacename> automatically associates newly created transactions
- with the invoking thread.
- </para>
- <para>
- To obtain a <interfacename>UserTransaction</interfacename>, call the static method
- <methodname>com.arjuna.ats.jta.UserTransaction.userTransaction()</methodname>.
- </para>
- <procedure>
- <title>Selecting the local JTA Implementation</title>
- <step>
- <para>
- Set property <varname>JTAEnvironmentBean.jtaTMImplementation</varname> to
- <literal>com.arjuna.ats.internal.jta.transaction.arjunacore.TransactionManagerImple</literal>.
- </para>
- </step>
- <step>
- <para>
- Set property <varname>JTAEnvironmentBean.jtaUTImplementation</varname> to
- <literal>com.arjuna.ats.internal.jta.transaction.arjunacore.UserTransactionImple</literal>.
- </para>
- </step>
- </procedure>
- </section>
-
- <section>
- <title>TransactionManager</title>
- <para>
- The <interfacename>TransactionManager</interfacename> interface allows the application server to control
- transaction boundaries on behalf of the application being managed.
- </para>
- <para>
- To obtain a <interfacename>TransactionManager</interfacename>, invoke the static method
- <methodname>com.arjuna.ats.jta.TransactionManager.transactionManager</methodname>.
- </para>
- <para>
- The <interfacename>TransactionManager</interfacename> maintains the transaction context association with threads
- as part of its internal data structure. A thread’s transaction context may be <literal>null</literal> or it may
- refer to a specific global transaction. Multiple threads may be associated with the same global transaction. As
- noted in <xref linkend="UserTransaction_Definition" />, nested transactions are not supported.
- </para>
- <para>
- Each transaction context is encapsulated by a Transaction object, which can be used to perform operations which
- are specific to the target transaction, regardless of the calling thread’s transaction context.
- </para>
- <table>
- <title><interfacename>TransactionManager</interfacename> Methods</title>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry><para><methodname>begin</methodname></para></entry>
- <entry>
- <para>
- Starts a new top-level transaction and associates the transaction context with the calling thread. If
- the calling thread is already associated with a transaction, exception
- <systemitem>NotSupportedException</systemitem> is thrown.
- </para>
- </entry>
- </row>
- <row>
- <entry><para><methodname>getTransaction</methodname></para></entry>
- <entry>
- <para>
- Returns the Transaction object representing the transaction context which is currently associated with
- the calling thread. You can use this object to perform various operations on the target transaction.
- </para>
- </entry>
- </row>
- <row>
- <entry><para><methodname>commit</methodname></para></entry>
- <entry>
- <para>
- Completes the transaction currently associated with the calling thread. After it returns, the calling
- thread is associated with no transaction. If <methodname>commit</methodname> is called when the thread
- is not associated with any transaction context, an exception is thrown. In some implementations, the
- <methodname>commit</methodname> operation is restricted to the transaction originator only. If the
- calling thread is not allowed to commit the transaction, an exception is thrown. JBossTA does not
- currently impose any restriction on the ability of threads to terminate transactions.
- </para>
- </entry>
- </row>
- <row>
- <entry><para><methodname>rollback</methodname></para></entry>
- <entry>
- <para>
- Rolls back the transaction associated with the current thread. After the
- <methodname>rollback</methodname> method completes, the thread is associated with no transaction.
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>
- In a multi-threaded environment, multiple threads may be active within the same transaction. If checked
- transaction semantics have been disabled, or the transaction times out, a transaction may terminated by a thread
- other than the one that created it. In this case, the creator usually needs to be notified. JBossTS notifies the
- creator during operations <methodname>commit</methodname> or <methodname>rollback</methodname> by throwing
- exception <systemitem>IllegalStateException</systemitem>.
- </para>
- </section>
-
- <section>
- <title>Suspend and resuming a transaction</title>
- <para>
- The JTA supports the concept of a thread temporarily suspending and resuming transactions in order to perform
- non-transactional work. Call the <methodname>suspend</methodname> method to temporarily suspend the current
- transaction that is associated with the calling thread. The thread then operates outside of the scope of the
- transaction. If the thread is not associated with any transaction, a <type>null</type> object reference is
- returned. Otherwise, a valid <type>Transaction</type> object is returned. Pass the <type>Transaction</type> object
- to the <methodname>resume</methodname> method to reinstate the transaction context.
- </para>
- <para>
- The <methodname>resume</methodname> method associates the specified transaction context with the calling
- thread. If the transaction specified is not a valid transaction, , the thread is associated with no transaction.
- if <methodname>resume</methodname> is invoked when the calling thread is already associated with another
- transaction, the <systemitem>IllegalStateException</systemitem> exception is thrown.
- </para>
- <example>
- <title>Using the <methodname>suspend</methodname> method</title>
- <programlisting language="Java" role="JAVA"> <xi:include href="extras/using_suspend_method.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /> </programlisting>
- </example>
- <note>
- <para>
- JBossJTA allows a suspended transaction to be resumed by a different thread. This feature is not required by
- JTA, but is an important feature.
- </para>
- </note>
- <para>
- When a transaction is suspended, the application server must ensure that the resources in use by the application
- are no longer registered with the suspended transaction. When a resource is de-listed this triggers the
- Transaction Manager to inform the resource manager to disassociate the transaction from the specified resource
- object. When the application’s transaction context is resumed, the application server must ensure that the
- resources in use by the application are again enlisted with the transaction. Enlisting a resource as a result of
- resuming a transaction triggers the Transaction Manager to inform the resource manager to re-associate the
- resource object with the resumed transaction.
- </para>
- </section>
-
- <section>
- <title>The Transaction interface</title>
- <para>
- The <interfacename>Transaction</interfacename> interface allows you to perform operations on the transaction
- associated with the target object. Every top-level transaction is associated with one <type>Transaction</type>
- object when the transaction is created.
- </para>
- <itemizedlist>
- <title>Uses of the <type>Transaction</type> object</title>
- <listitem>
- <para>
- enlist the transactional resources in use by the application.
- </para>
- </listitem>
- <listitem>
- <para>
- register for transaction synchronization call backs.
- </para>
- </listitem>
- <listitem>
- <para>
- commit or rollback the transaction.
- </para>
- </listitem>
- <listitem>
- <para>
- obtain the status of the transaction.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- The <methodname>commit</methodname> and <methodname>rollback</methodname> methods allow the target object to be
- committed or rolled back. The calling thread does not need to have the same transaction associated with the
- thread. If the calling thread is not allowed to commit the transaction, the transaction manager throws an
- exception. At present JBossJTA does not impose restrictions on threads terminating transactions.
- </para>
- <para>
- The JTA standard does not provide a means to obtain the transaction identifier. However, JBossJTA provides several
- ways to view the transaction identifier. Call method <methodname>toString</methodname> to print full information
- about the transaction, including the identifier. Alternatively you can cast the
- <type>javax.transaction.Transaction</type> instance to a <type>com.arjuna.ats.jta.transaction.Transaction</type>,
- then call either method <methodname>get_uid</methodname>, which returns an ArjunaCore <type>Uid</type>
- representation, or <methodname>getTxId</methodname>, which returns an <type>Xid</type> for the global identifier,
- i.e., no branch qualifier.
- </para>
- </section>
-
-
- <section>
- <title>Resource enlistment</title>
- <para>
- Typically, an application server manages transactional resources, such as database connections, in conjunction
- with some resource adapter and optionally with connection pooling optimization. For an external transaction
- manager to coordinate transactional work performed by the resource managers, the application server must enlist
- and de-list the resources used in the transaction. These resources, called <firstterm>participants</firstterm>,
- are enlisted with the transaction so that they can be informed when the transaction terminates, by being driven
- through the two-phase commit protocol.
- </para>
- <para>
- As stated previously, the JTA is much more closely integrated with the XA concept of resources than the arbitrary
- objects. For each resource the application is using, the application server invokes the
- <methodname>enlistResource</methodname> method with an <type>XAResource</type> object which identifies the
- resource in use.<!-- See for details on how the implementation of the XAResource can affect recovery in the event
- of a failure.-->
- </para>
- <para>
- The enlistment request causes the transaction manager to inform the resource manager to start associating the
- transaction with the work performed through the corresponding resource. The transaction manager passes the
- appropriate flag in its <methodname>XAResource.start</methodname> method call to the resource manager.
- </para>
- <para>
- The <methodname>delistResource</methodname> method disassociates the specified resource from the transaction
- context in the target object. The application server invokes the method with the two parameters: the
- <type>XAResource</type> object that represents the resource, and a flag to indicate whether the operation is due
- to the transaction being suspended (<literal>TMSUSPEND</literal>), a portion of the work has failed
- (<literal>TMFAIL</literal>), or a normal resource release by the application (<literal>TMSUCCESS</literal>).
- </para>
- <para>
- The de-list request causes the transaction manager to inform the resource manager to end the association of the
- transaction with the target <type>XAResource</type>. The flag value allows the application server to indicate
- whether it intends to come back to the same resource whereby the resource states must be kept intact. The
- transaction manager passes the appropriate flag value in its <methodname>XAResource.end</methodname> method call
- to the underlying resource manager.
- </para>
- </section>
-
-
- <section>
- <title>Transaction synchronization</title>
- <para>
- Transaction synchronization allows the application server to be notified before and after the transaction
- completes. For each transaction started, the application server may optionally register a
- <type>Synchronization</type> call-back object to be invoked by the transaction manager, which will be one of the
- following:
- </para>
- <informaltable>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>
- <para><methodname>beforeCompletion</methodname></para>
- </entry>
- <entry>
- <para>
- Called before the start of the two-phase transaction complete process. This call is executed in the same
- transaction context of the caller who initiates the <methodname>TransactionManager.commit</methodname>
- or the call is executed with no transaction context if <methodname>Transaction.commit</methodname> is
- used.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para><methodname>afterCompletion</methodname></para>
- </entry>
- <entry>
- <para>
- Called after the transaction completes. The status of the transaction is supplied in the parameter. This
- method is executed without a transaction context.
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </section>
-
- <section>
- <title>Transaction equality</title>
- <para>
- The transaction manager implements the <type>Transaction</type> object’s <methodname>equals</methodname> method to
- allow comparison between the target object and another <type>Transaction</type> object. The
- <methodname>equals</methodname> method returns <literal>true</literal> if the target object and the parameter
- object both refer to the same global transaction.
- </para>
- <example>
- <title>Method <methodname>equals</methodname></title>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/Transaction_Equality.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
- </section>
-
-
- <section>
- <title>TransactionSynchronizationRegistry</title>
- <para>
- The <interfacename>javax.transaction.TransactionSynchronizationRegistry</interfacename> interface, added to the
- JTA API in version 1.1, provides for registering Synchronizations with special ordering behavior, and for storing
- key-value pairs in a per-transaction Map. Full details are available from the JTA 1.1 API specification and
- javadoc. Here we focus on implementation specific behavior.
- </para>
- <example>
- <title>Accessing the TransactionSynchronizationRegistry in standalone environments</title>
- <programlisting language="Java" role="JAVA"><xi:include
- href="extras/TransactionSynchronizationRegistry_standalone.java" xmlns:xi="http://www.w3.org/2001/XInclude"
- parse="text" /></programlisting>
- <para>
- This is a stateless object and hence is cheap to instantiate.
- </para>
- </example>
- <formalpara>
- <title>Accessing the TransactionSynchronizationRegistry via JNDI</title>
- <para>
- In application server environments, the standard JNDI name binding is
- <literal>java:comp/TransactionSynchronizationRegistry</literal>.
- </para>
- </formalpara>
- <para>
- Ordering of interposed Synchronizations is relative to other local Synchronizations only. In cases where the
- transaction is distributed over multiple JVMs, global ordering is not guaranteed.
- </para>
- <para>
- The per-transaction data storage provided by the <interfacename>TransactionSynchronizationRegistry</interfacename>
- methods <methodname>getResource</methodname> and <methodname>putResource</methodname> are non-persistent and thus
- not available in <interfacename>Transactions</interfacename> during crash recovery. When running integrated with
- an application server or other container, this storage may be used for system purposes. To avoid collisions, use
- an application-specific prefix on map keys, such as <command>put(“myapp_”+key, value)</command>. The behavior of
- the <type>Map</type> on <type>Thread</type>s that have status <literal>NO_TRANSACTION</literal> or where the
- transaction they are associated with has been rolled back by another <type>Thread</type>, such as in the case of a
- timeout, is undefined. A <type>Transaction</type> can be associated with multiple <type>Thread</type>s. For such
- cases the <type>Map</type> is synchronized to provide thread safety.
- </para>
- </section>
-</chapter>
Modified: labs/jbosstm/trunk/ArjunaJTA/docs/installation_guide/en-US/JBossJTA_Installation_Guide.ent
===================================================================
--- labs/jbosstm/trunk/ArjunaJTA/docs/installation_guide/en-US/JBossJTA_Installation_Guide.ent 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaJTA/docs/installation_guide/en-US/JBossJTA_Installation_Guide.ent 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,4 +1,4 @@
<!ENTITY PRODUCT "JBossJTA">
<!ENTITY BOOKID "JBossJTA_Installation_Guide">
-<!ENTITY YEAR "2010">
+<!ENTITY YEAR "2011">
<!ENTITY HOLDER "JBoss.org">
Modified: labs/jbosstm/trunk/ArjunaJTA/docs/installation_guide/en-US/JBossJTA_Installation_Guide.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTA/docs/installation_guide/en-US/JBossJTA_Installation_Guide.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaJTA/docs/installation_guide/en-US/JBossJTA_Installation_Guide.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -12,5 +12,5 @@
<xi:include href="Additional_JAR_Requirements.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Setting_Properties.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <index />
+ <!-- <index /> -->
</book>
Modified: labs/jbosstm/trunk/ArjunaJTA/docs/quick_start/en-US/JBossJTA_Quick_Start_Guide.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTA/docs/quick_start/en-US/JBossJTA_Quick_Start_Guide.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaJTA/docs/quick_start/en-US/JBossJTA_Quick_Start_Guide.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -9,5 +9,5 @@
<xi:include href="About_This_Guide.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Quick_Start_to_JTA.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <index />
+ <!-- <index /> -->
</book>
Modified: labs/jbosstm/trunk/ArjunaJTS/docs/administration_guide/en-US/JBossJTS_Administration_Guide.ent
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/administration_guide/en-US/JBossJTS_Administration_Guide.ent 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/administration_guide/en-US/JBossJTS_Administration_Guide.ent 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,4 +1,4 @@
<!ENTITY PRODUCT "JBossJTS">
<!ENTITY BOOKID "JBossJTS_Administration_Guide">
-<!ENTITY YEAR "2010">
+<!ENTITY YEAR "2011">
<!ENTITY HOLDER "JBoss.org">
Modified: labs/jbosstm/trunk/ArjunaJTS/docs/administration_guide/en-US/JBossJTS_Administration_Guide.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/administration_guide/en-US/JBossJTS_Administration_Guide.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/administration_guide/en-US/JBossJTS_Administration_Guide.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -13,5 +13,5 @@
<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="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <index />
+ <!-- <index /> -->
</book>
Modified: labs/jbosstm/trunk/ArjunaJTS/docs/development_guide/en-US/Failure_Recovery.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/development_guide/en-US/Failure_Recovery.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/development_guide/en-US/Failure_Recovery.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -6,483 +6,510 @@
<chapter>
<title>Failure Recovery</title>
<para>
- The failure recovery subsystem of JBossTS 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 hardware hosting them crash
- or lose network connectivity. In the case of hardware crashes or network failures, the recovery does not take place
- until the system or network are restored, but the original application does not need to be restarted. Recovery is
- handled by the Recovery Manager process. For recover to take place, information about the transaction and the
- resources involved needs to survive the failure and be accessible afterward. This information is held in the
- <classname>ActionStore</classname>, which is part of the <classname>ObjectStore</classname>. If the
- <classname>ObjectStore</classname> is destroyed or modified, recovery may not be possible.
+ The failure recovery subsystem of JBossTS 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 hardware hosting them crash
+ or lose network connectivity. In the case of
+ hardware crashes or network failures, the recovery does not take place
+ until the system or
+ network are restored, but the original application does not need to be restarted. Recovery is
+ handled by the Recovery Manager process. For recover to take place, information about the
+ transaction and the
+ resources involved needs to survive the failure and be accessible afterward.
+ This information is held in the
+ <classname>ActionStore</classname>
+ , which is part of the
+ <classname>ObjectStore</classname>
+ . If the
+ <classname>ObjectStore</classname>
+ is destroyed or modified, recovery may not be possible.
</para>
<para>
- Until the recovery procedures are complete, resources affected by a transaction which was in progress at the time of
- the failure may be inaccessible. Database resources may report this as as tables or rows held by <phrase>in-doubt
- transactions</phrase>. For TXOJ resources, an attempt to activate the Transactional Object, such as when trying to
+ Until the recovery procedures are complete, resources affected by a transaction which was in
+ progress at the time of
+ the failure may be inaccessible. Database resources may report this as as
+ tables or rows held by
+ <phrase>in-doubt
+ transactions</phrase>
+ . For TXOJ resources, an attempt to activate the Transactional Object, such as when trying to
get a lock, fails.
</para>
- <!-- Surely JDK 1.3 is no longer supported
- <note>
- <para>
- Because of limitations in the ORB which ships with the JDK 1.3, it is not possible to provide crash recovery. We
- therefore do not recommend using this ORB for mission critical applications.
- </para>
- </note>
- -->
-
+ <!-- Surely JDK 1.3 is no longer supported <note> <para> Because of limitations in the ORB which ships
+ with the JDK 1.3, it is not possible to provide crash recovery. We therefore do not recommend using this
+ ORB for mission critical applications. </para> </note> -->
+
<section>
<title>Configuring the failure recovery subsystem for your ORB</title>
<para>
- Although some ORB-specific configuration is necessary to configure the ORB sub-system, the basic settings are ORB-independent.
- The configuration which applies to JBossTS is in the <filename>RecoveryManager-properties.xml</filename> file and
- the <filename>orportability-properties.xml</filename> file. Contents of each file are below.
+ Although some ORB-specific configuration is necessary to configure the ORB sub-system, the
+ basic settings are ORB-independent.
+ The configuration which applies to JBossTS is in the
+ <filename>RecoveryManager-properties.xml</filename>
+ file and
+ the
+ <filename>orportability-properties.xml</filename>
+ file. Contents of each file are below.
</para>
<example>
<title>RecoverManager-properties.xml</title>
- <programlisting language="XML" role="XML"><xi:include href="extras/RecoveryManager-properties.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ <programlisting language="XML" role="XML"><xi:include
+ href="extras/RecoveryManager-properties.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
+ parse="text" /></programlisting>
</example>
<example>
<title>orportability-properties.xml</title>
- <programlisting language="XML" role="XML"><xi:include href="extras/orportability-properties.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ <programlisting language="XML" role="XML"><xi:include
+ href="extras/orportability-properties.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
</example>
<para>
- These entries cause instances of the named classes to be loaded. The named classes then load the ORB-specific
- classes needed and perform other initialization. This enables failure recovery for transactions initiated by or
- involving applications using this property file. The default <filename>RecoveryManager-properties.xml</filename>
- file and <filename>orportability-properties.xml</filename> with the distribution include these entries.
+ These entries cause instances of the named classes to be loaded. The named classes then load
+ the ORB-specific
+ classes needed and perform other initialization. This enables failure recovery
+ for transactions initiated by or
+ involving applications using this property file. The default
+ <filename>RecoveryManager-properties.xml</filename>
+ file and
+ <filename>orportability-properties.xml</filename>
+ with the distribution include these entries.
</para>
<important>
<para>
- Failure recovery is NOT supported with the JavaIDL ORB that is part of JDK. Failure recovery is supported for
+ Failure recovery is NOT supported with the JavaIDL ORB that is part of JDK. Failure
+ recovery is supported for
JacOrb only.
</para>
</important>
<para>
- To disable recovery, remove or comment out the <literal>RecoveryEnablement</literal> line in the property file.
+ To disable recovery, remove or comment out the
+ <literal>RecoveryEnablement</literal>
+ line in the property file.
</para>
</section>
-
+
<section>
- <title>The recovery manager</title>
- <para>
- The failure recovery subsystem of JBossTS requires the stand-alone Recovery Manager process to be running for
- each <systemitem>ObjectStore</systemitem>. Typically, there is one <systemitem>ObjectStore</systemitem> for each
- node on the network that is running JBossTS applications. The
- RecoveryManager file is located in the <filename>arjuna.jar</filename> file within the package
- <package>com.arjuna.ats.arjuna.recovery.RecoveryManager</package>. To start the Recovery Manager issue the following
- command:
- </para>
- <example>
- <title>Starting the recovery manager</title>
- <screen>
- java com.arjuna.ats.arjuna.recovery.RecoveryManager
- </screen>
- </example>
- <para>
- If the <option>-test</option> flag is used with the Recovery Manager, it displays a “Ready” message when you
- start it.
- </para>
- <important>
- <para>
- If you are using JacORB, the Recovery Manager is started to allow successful registration of
- <classname>Resource</classname> objects.
- </para>
- </important>
-
- <section>
- <title>Configuring the RecoveryManager</title>
- <para>
- The <classname>RecoveryManager</classname> reads the properties defined in the
- <filename>jbossts-properties.xml</filename> file and then the property file
- <filename>RecoveryManager-properties.xml</filename>, from the same directory as it found the <filename>arjuna
- properties</filename> file. An entry for a property in the <filename>RecoveryManager-properties.xml</filename>
- file overrides an entry for the same property in the main <filename>TransactionService-properties.xml</filename>
- file. Most of the entries are specific to the <classname>RecoveryManager</classname>.
- </para>
- <para>
- A default version of <filename>RecoveryManager-properties.xml</filename> is supplied with the distribution. You
- can use this file without modification, unless you want to modify the debug tracing fields as outlined in <xref
- linkend="recovery-manager-output" />.
- </para>
-
- <section id="recovery-manager-output">
- <title>Output</title>
- <para>
- You will likely need output from the <classname>RecoveryManager</classname>, to provide a record of what
- recovery activity has taken place. <classname>RecoveryManager</classname> uses the logging tracing mechanism
- provided by the <firstterm>Arjuna Common Logging Framework (CLF)</firstterm>, which provides a high level
- interface that hides differences that exist between existing logging APIs such as Jakarta log4j or the JDK
- logging API.
- </para>
- <para>
- With the CLF, applications make logging calls on <classname>commonLogger</classname> objects. These
- <classname>commonLogger</classname> objects pass log messages to <classname>Handler</classname> for
- publication. Both <classname>commonLoggers</classname> and <classname>Handlers</classname> filter log messages
- by level. Each log message has an associated log Level that gives the importance and urgency of a log message.
- </para>
- <orderedlist>
- <title>Logging levels, from most to least verbose</title>
- <listitem>
- <para>
- DEBUG
- </para>
- </listitem>
- <listitem>
- <para>
- INFO
- </para>
- </listitem>
- <listitem>
- <para>
- WARN
- </para>
- </listitem>
- <listitem>
- <para>
- ERROR
- </para>
- </listitem>
- <listitem>
- <para>
- FATAL
- </para>
- </listitem>
- </orderedlist>
- <para>
- The choice of the underlying logging infrastructure is defined by the property
- <varname>LoggingEnvironmentBean.loggingFactory</varname>, which is set by default to
- <literal>log4j</literal>. Possible values are described in the <classname>LoggingEnvironmentBean</classname>
- javadoc.
- </para>
- <para>
- The properties of the underlying log system are configured in a manner specific to that log system. For log4j,
- a <filename>log4j.properties</filename> file is used.
- </para>
- <example>
- <title>Default log4j configuration file used by JBossTS</title>
- <screen>
-# Default LOG4J Configuration
-# Arjuna Technologies Ltd.
-# $Id: log4j.properties,v 1.1 2003/09/28 11:38:24 rbegg Exp $
-log4j.rootLogger=WARN, stdout
-log4j.appender.stdout=org.apache.log4j.ConsoleAppender
-log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
-log4j.appender.stdout.layout.ConversionPattern=%d [%t] %-5p %c - %m%n
- </screen>
- </example>
- <para>
- To set the logging level to <literal>DEBUG</literal>, set the <varname>log4j.rootLogger</varname> to
- <literal>DEBUG</literal>.
- </para>
- <para>
- Messages describing the start and the periodical behavior of the <classname>RecoveryManager</classname> are
- set the <literal>INFO</literal> level. To see them, set the logging level to <literal>INFO</literal>. Setting
- the normal recovery messages to the <literal>INFO</literal> level produces a moderate level of reporting from
- the <classname>RecoveryManager</classname>. If no recovery needs to take place, the only thing reported is the
- entry into each module for each periodic pass. To disable the <literal>INFO</literal> messages produced by the
- <classname>RecoveryManager</classname>, set the logging level to <literal>ERROR</literal>.
- </para>
- <note>
- <para>
- Set the Logging level at least to the <literal>WARN</literal> value to enable the report of warning
- messages.
- </para>
- </note>
- </section>
+ <title>JTS specific recovery</title>
- </section>
-
<section>
- <title>Periodic recovery</title>
- <para>
- The <classname>RecoveryManager</classname> scans the <classname>ObjectStore</classname> and other locations of
- information, looking for transactions and resources that may require recovery. The scans and recovery processing
- are performed by recovery modules, which are instances of classes that implement the
- <interfacename>com.arjuna.ats.arjuna.recovery.RecoveryModule</interfacename> interface. Each module is
- responsible for a particular category of transaction or resource.The set of recovery modules is dynamically
- loaded, using properties found in the <filename>RecoveryManager-properties.xml</filename> file.
- </para>
- <para>
- The interface has two methods: <methodname>periodicWorkFirstPass</methodname> and
- <methodname>periodicWorkSecondPass</methodname>. At an interval defined by property
- <varname>PERIODIC_RECOVERY_PERIOD</varname>, the <classname>RecoveryManager</classname> calls the
- <methodname>periodicWorkFirstPass</methodname> method on each property. It then waits for a brief period,
- defined by <varname>RECOVERY_BACKOFF_PERIOD</varname>, before calling the
- <methodname>periodicWorkSecondPass</methodname> method. Typically, in the first pass, the module scans the
- relevant part of the ObjectStore to find transactions or resources that are in-doubt, or part of the way through
- the commitment process. On the second pass, if any of the same items are still in-doubt, the original
- application process may have crashed and the item may need recovery.
- </para>
- <para>
- If the <classname>RecoveryManager</classname> attempts to recover a transaction that is still progressing in the
- original process, it is likely to break the consistency. Accordingly, the recovery modules use a mechanism,
- implemented in the <package>com.arjuna.ats.internal.jts.recovery.contact</package> package, to check whether the
- original process is still alive, and whether the transaction is still in progress. The
- <classname>RecoveryManager</classname> only proceeds with recovery if the original process has disappeared or
- the transaction is completed. If a server process or machine crashes, but the transaction-initiating process
- survives, the transaction complete, usually generating a warning. Recovery of such a transaction is the
- responsibility of the <classname>RecoveryManager</classname>.
- </para>
- <para>
- It is important to set the interval periods appropriately. The total iteration time is the sum of
- <varname>PERIODIC_RECOVERY_PERIOD</varname>, <varname>RECOVERY_BACKOFF_PERIOD</varname>, and the length of time it takes to scan the stores and to
- attempt recovery of any in-doubt transactions, for all the recovery modules. The recovery attempt time may
- include connection timeouts while trying to use the ORB to communicate with processes or machines that have
- crashed or are inaccessible. This is why the recovery system includes mechanisms to avoid trying to recover
- the same transaction infinitely. The total iteration time affects how long a resource remains
- inaccessible after a failure.
- </para>
- <para>
- Set <varname>PERIODIC_RECOVERY_PERIOD</varname> accordingly. It defaults to 120 seconds. The
- <varname>RECOVERY_BACKOFF_PERIOD</varname> can be comparatively short, and defaults to 10 seconds. Its purpose
- is to reduce the number of transactions that are candidates for recovery, and which require a contact call to
- the original process to check whether they are still in progress.
- </para>
- <!-- Taking this out because it is ancient history
- <note>
- <para>
- In JBossTS 2.0, there was no contact mechanism, and the backoff period had to be long enough to avoid catching
- transactions in flight at all. From 2.1, there is no such risk.
- </para>
- </note>
- -->
- <para>
- JBossTS includes several recovery modules, supporting various aspects of transaction recovery including JDBC
- recovery. You can create your own recovery modules and register them with the
- <classname>RecoveryManager</classname> using the
- <classname>RecoveryEnvironmentBean.recoveryModuleClassNames</classname> property. These recovery modules are invoked
- on each pass of the periodic recovery in the order they appear. You can predict the order in which they run, but
- a failure in an application process might occur while a periodic recovery pass is in progress. The default
- <classname>RecoveryExtension</classname> settings are below.
- </para>
- <example>
- <title>Default RecoveryExtension settings</title>
- <programlisting language="XML" role="XML"><xi:include href="extras/default-RecoveryExtension-settings.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
- </section>
-
- <section>
<title>XA resource recovery</title>
<para>
- Recovery of XA resources accessed via JDBC is handled by the <classname>XARecoveryModule</classname>. This
- module includes both <phrase>transaction-initiated</phrase> and <phrase>resource-initiated</phrase> recovery.
+ Recovery of XA resources accessed via JDBC is handled by the
+ <classname>XARecoveryModule</classname>
+ . This
+ module includes both
+ <phrase>transaction-initiated</phrase>
+ and
+ <phrase>resource-initiated</phrase>
+ recovery.
</para>
<itemizedlist>
<listitem>
<para>
- Transaction-initiated recovery is possible where the particular transaction branch progressed far enough for
- a <systemitem>JTA_ResourceRecord</systemitem> to be written in the ObjectStore. The record contains the
- information needed to link the transaction to information known by the rest of JBossTS in the database.
+ Transaction-initiated recovery is possible where the particular transaction branch
+ progressed far enough for
+ a
+ <systemitem>JTA_ResourceRecord</systemitem>
+ to be written in the ObjectStore. The record contains the
+ information needed to link the
+ transaction to information known by the rest of JBossTS in the database.
</para>
</listitem>
<listitem>
<para>
- Resource-initiated recovery is necessary for branches where a failure occurred after the database made a
- persistent record of the transaction, but before the <systemitem>JTA_ResourceRecord</systemitem> was
- written. Resource-initiated recovery is also necessary for datasources for which it is impossible to hold
- information in the <systemitem>JTA_ResourceRecord</systemitem> that allows the recreation in the
- RecoveryManager of the <classname>XAConnection</classname> or <classname>XAResource</classname> used in the
+ Resource-initiated recovery is necessary for branches where a failure occurred after the
+ database made a
+ persistent record of the transaction, but before the
+ <systemitem>JTA_ResourceRecord</systemitem>
+ was
+ written. Resource-initiated recovery is also necessary for datasources for which it
+ is impossible to hold
+ information in the
+ <systemitem>JTA_ResourceRecord</systemitem>
+ that allows the recreation in the
+ RecoveryManager of the
+ <classname>XAConnection</classname>
+ or
+ <classname>XAResource</classname>
+ used in the
original application.
</para>
</listitem>
</itemizedlist>
<para>
- Transaction-initiated recovery is automatic. The <classname>XARecoveryModule</classname> finds the
- <systemitem>JTA_ResourceRecord</systemitem> which needs recovery, using the two-pass mechanism described
- above. It then uses the normal recovery mechanisms to find the status of the transaction the resource was
- involved in, by running <methodname>replay_completion</methodname> on the
- <classname>RecoveryCoordinator</classname> for the transaction branch. Next, it creates or recreates the
- appropriate <classname>XAResource</classname> and issues <methodname>commit</methodname> or
- <methodname>rollback</methodname> on it as appropriate. The <classname>XAResource</classname> creation uses the
- same database name, username, password, and other information as the application.
+ Transaction-initiated recovery is automatic. The
+ <classname>XARecoveryModule</classname>
+ finds the
+ <systemitem>JTA_ResourceRecord</systemitem>
+ which needs recovery, using the two-pass mechanism described
+ above. It then uses the normal
+ recovery mechanisms to find the status of the transaction the resource was
+ involved in, by
+ running
+ <methodname>replay_completion</methodname>
+ on the
+ <classname>RecoveryCoordinator</classname>
+ for the transaction branch. Next, it creates or recreates the
+ appropriate
+ <classname>XAResource</classname>
+ and issues
+ <methodname>commit</methodname>
+ or
+ <methodname>rollback</methodname>
+ on it as appropriate. The
+ <classname>XAResource</classname>
+ creation uses the
+ same database name, username, password, and other information as the
+ application.
</para>
<para>
Resource-initiated recovery must be specifically configured, by supplying the
- <classname>RecoveryManager</classname> with the appropriate information for it to interrogate all the
- <classname>XADataSources</classname> accessed by any JBossTS application. The access to each
- <classname>XADataSource</classname> is handled by a class that implements the
- <interfacename>com.arjuna.ats.jta.recovery.XAResourceRecovery</interfacename> interface. Instances of this class
+ <classname>RecoveryManager</classname>
+ with the appropriate information for it to interrogate all the
+ <classname>XADataSources</classname>
+ accessed by any JBossTS application. The access to each
+ <classname>XADataSource</classname>
+ is handled by a class that implements the
+ <interfacename>com.arjuna.ats.jta.recovery.XAResourceRecovery</interfacename>
+ interface. Instances of this class
are dynamically loaded, as controlled by property
- <varname>JTAEnvironmentBean.xaResourceRecoveryInstances</varname>.
+ <varname>JTAEnvironmentBean.xaResourceRecoveryInstances</varname>
+ .
</para>
<para>
- The <classname>XARecoveryModule</classname> uses the <classname>XAResourceRecovery</classname> implementation to
- get an <classname>XAResource</classname> to the target datasource. On each invocation of
- <methodname>periodicWorkSecondPass</methodname>, the recovery module issues an
- <methodname>XAResource.recover</methodname> request. This request returns a list of the transaction identifiers
- that are known to the datasource and are in an in-doubt state. The list of these in-doubt Xids is compared
- across multiple passes, using <methodname>periodicWorkSecondPass-es</methodname>. Any Xid that appears in both
- lists, and for which no <systemitem>JTA_ResourceRecord</systemitem> is found by the intervening
- transaction-initiated recovery, is assumed to belong to a transaction involved in a crash before any
- <systemitem>JTA_Resource_Record</systemitem> was written, and a <methodname>rollback</methodname> is issued for
- that transaction on the <classname>XAResource</classname>.
+ The
+ <classname>XARecoveryModule</classname>
+ uses the
+ <classname>XAResourceRecovery</classname>
+ implementation to
+ get an
+ <classname>XAResource</classname>
+ to the target datasource. On each invocation of
+ <methodname>periodicWorkSecondPass</methodname>
+ , the recovery module issues an
+ <methodname>XAResource.recover</methodname>
+ request. This request returns a list of the transaction identifiers
+ that are known to the
+ datasource and are in an in-doubt state. The list of these in-doubt Xids is compared
+ across
+ multiple passes, using
+ <methodname>periodicWorkSecondPass-es</methodname>
+ . Any Xid that appears in both
+ lists, and for which no
+ <systemitem>JTA_ResourceRecord</systemitem>
+ is found by the intervening
+ transaction-initiated recovery, is assumed to belong to a
+ transaction involved in a crash before any
+ <systemitem>JTA_Resource_Record</systemitem>
+ was written, and a
+ <methodname>rollback</methodname>
+ is issued for
+ that transaction on the
+ <classname>XAResource</classname>
+ .
</para>
<para>
- This double-scan mechanism is used because it is possible the Xid was obtained from the datasource just as the
- original application process was about to create the corresponding JTA_ResourceRecord. The interval between the
- scans should allow time for the record to be written unless the application crashes (and if it does, rollback is
+ This double-scan mechanism is used because it is possible the Xid was obtained from the
+ datasource just as the
+ original application process was about to create the corresponding
+ JTA_ResourceRecord. The interval between the
+ scans should allow time for the record to be
+ written unless the application crashes (and if it does, rollback is
the right answer).
</para>
<para>
- An <classname>XAResourceRecovery</classname> implementation class can contain all the information needed to
- perform recovery to a specific datasource. Alternatively, a single class can handle multiple datasources which
- have some similar features. The constructor of the implementation class must have an empty parameter list,
- because it is loaded dynamically. The interface includes an <methodname>initialise</methodname> method, which
- passes in further information as a <type>string</type>. The content of the string is taken from the property
- value that provides the class name. Everything after the first semi-colon is passed as the value of the
- string. The <classname>XAResourceRecovery</classname> implementation class determines how to use the string.
+ An
+ <classname>XAResourceRecovery</classname>
+ implementation class can contain all the information needed to
+ perform recovery to a specific
+ datasource. Alternatively, a single class can handle multiple datasources which
+ have some
+ similar features. The constructor of the implementation class must have an empty parameter
+ list,
+ because it is loaded dynamically. The interface includes an
+ <methodname>initialise</methodname>
+ method, which
+ passes in further information as a
+ <type>string</type>
+ . The content of the string is taken from the property
+ value that provides the class name.
+ Everything after the first semi-colon is passed as the value of the
+ string. The
+ <classname>XAResourceRecovery</classname>
+ implementation class determines how to use the string.
</para>
<para>
- An <classname>XAResourceRecovery</classname> implementation class, <classname>com.arjuna.ats.internal.jdbc.recovery.BasicXARecovery</classname>, supports resource-initiated recovery for any XADataSource. For this class, the string
- received in method <methodname>initialise</methodname> is assumed to contain the number of connections to recover, and the name of the
- properties file containing the dynamic class name, the database username, the database password and the database
- connection URL. The following example is for an Oracle 8.1.6 database accessed via the Sequelink 5.1 driver:
+ An
+ <classname>XAResourceRecovery</classname>
+ implementation class,
+ <classname>com.arjuna.ats.internal.jdbc.recovery.BasicXARecovery</classname>
+ , supports resource-initiated recovery for any XADataSource. For this class, the string
+ received in method
+ <methodname>initialise</methodname>
+ is assumed to contain the number of connections to recover, and the name of the
+ properties
+ file containing the dynamic class name, the database username, the database password and the
+ database
+ connection URL. The following example is for an Oracle 8.1.6 database accessed via
+ the Sequelink 5.1 driver:
</para>
<screen>
XAConnectionRecoveryEmpay=com.arjuna.ats.internal.jdbc.recovery.BasicXARecovery;2;OraRecoveryInfo
</screen>
<para>
- This implementation is only meant as an example, because it relies upon usernames and passwords appearing in
- plain text properties files. You can create your own implementations of
- <classname>XAConnectionRecovery</classname>. See the javadocs and the example
- <package>com.arjuna.ats.internal.jdbc.recovery.BasicXARecovery</package>.
+ This implementation is only meant as an example, because it relies upon usernames and
+ passwords appearing in
+ plain text properties files. You can create your own implementations
+ of
+ <classname>XAConnectionRecovery</classname>
+ . See the javadocs and the example
+ <package>com.arjuna.ats.internal.jdbc.recovery.BasicXARecovery</package>
+ .
</para>
-
+
<example>
<title>XAConnectionRecovery implementation</title>
- <programlisting role="JAVA" language="Java"><xi:include href="extras/XAConnectionRecovery.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ <programlisting role="JAVA" language="Java"><xi:include
+ href="extras/XAConnectionRecovery.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
</example>
- <!-- Removed as ancient
+ <!-- Removed as ancient <note> <title>Oracle usernames for Oracle 8.0 to 8.1.4</title> <para> it
+ is necessary for any database user that will use distributed transactions (e.g., JBossTS and JDBC) to
+ have select privilege on the SYS via DBA_PENDING_TRANSACTIONS. For 8.1.5 and higher, this is not (apparently)
+ necessary for normal transaction access. However, this privilege is needed for the database user given
+ when creating an XAConnection that provides an XAResource that is then used for XAResource.recover. (XAResource.commit,
+ rollback etc. do not require the privilege). Accordingly, administrators may wish to create a special
+ database username for the JBossTS RecoveryManager, which has this privilege, which need not be granted
+ to users in general. An implication of this is that access to the RecoveryManager_2_2.properties file
+ needs to be appropriately controlled, if the password for the RecoveryManager user is contained in it.
+ </para> </note> -->
<note>
- <title>Oracle usernames for Oracle 8.0 to 8.1.4</title>
- <para>
- it is necessary for any database user that will use distributed transactions (e.g., JBossTS and JDBC) to have
- select privilege on the SYS via DBA_PENDING_TRANSACTIONS. For 8.1.5 and higher, this is not (apparently)
- necessary for normal transaction access. However, this privilege is needed for the database user given when
- creating an XAConnection that provides an XAResource that is then used for
- XAResource.recover. (XAResource.commit, rollback etc. do not require the privilege). Accordingly,
- administrators may wish to create a special database username for the JBossTS RecoveryManager, which has this
- privilege, which need not be granted to users in general. An implication of this is that access to the
- RecoveryManager_2_2.properties file needs to be appropriately controlled, if the password for the
- RecoveryManager user is contained in it.
- </para>
- </note>
- -->
- <note>
<title>Multiple recovery domains and resource-initiated recovery</title>
<para>
- <methodname>XAResource.recover</methodname> returns the list of all transactions that are in-doubt with in the
- datasource. If multiple recovery domains are used with a single datasource, resource-initiated recovery sees
- transactions from other domains. Since it does not have a <systemitem>JTA_ResourceRecord</systemitem>
- available, it rolls back the transaction in the database, if the Xid appears in successive recover calls. To
- suppress resource-initiated recovery, do not supply an <varname>XAConnectionRecovery</varname> property, or
+ <methodname>XAResource.recover</methodname>
+ returns the list of all transactions that are in-doubt with in the
+ datasource. If multiple
+ recovery domains are used with a single datasource, resource-initiated recovery sees
+ transactions from other domains. Since it does not have a
+ <systemitem>JTA_ResourceRecord</systemitem>
+ available, it rolls back the transaction in the database, if the Xid appears in successive
+ recover calls. To
+ suppress resource-initiated recovery, do not supply an
+ <varname>XAConnectionRecovery</varname>
+ property, or
confine it to one recovery domain.
</para>
</note>
</section>
-
+
<section>
<title>Recovery behavior</title>
<para>
- Property <varname>OTS_ISSUE_RECOVERY_ROLLBACK</varname> controls whether the
- <classname>RecoveryManager</classname> explicitly issues a rollback request when
- <methodname>replay_completion</methodname> asks for the status of a transaction that is unknown. According to
- the <systemitem>presume-abort</systemitem> mechanism used by OTS and JTS, the transaction can be assumed to have
- rolled back, and this is the response that is returned to the <classname>Resource</classname>, including a
- subordinate coordinator, in this case. The <classname>Resource</classname> should then apply that result to the
- underlying resources. However, it is also legitimate for the superior to issue a rollback, if
- <varname>OTS_ISSUE_RECOVERY_ROLLBACK</varname> is set to <literal>YES</literal>.
+ Property
+ <varname>OTS_ISSUE_RECOVERY_ROLLBACK</varname>
+ controls whether the
+ <classname>RecoveryManager</classname>
+ explicitly issues a rollback request when
+ <methodname>replay_completion</methodname>
+ asks for the status of a transaction that is unknown. According to
+ the
+ <systemitem>presume-abort</systemitem>
+ mechanism used by OTS and JTS, the transaction can be assumed to have
+ rolled back, and this
+ is the response that is returned to the
+ <classname>Resource</classname>
+ , including a
+ subordinate coordinator, in this case. The
+ <classname>Resource</classname>
+ should then apply that result to the
+ underlying resources. However, it is also legitimate for
+ the superior to issue a rollback, if
+ <varname>OTS_ISSUE_RECOVERY_ROLLBACK</varname>
+ is set to
+ <literal>YES</literal>
+ .
</para>
<para>
- The OTS transaction identification mechanism makes it possible for a transaction coordinator to hold a
- <classname>Resource</classname> reference that will never be usable. This can occur in two cases:
+ The OTS transaction identification mechanism makes it possible for a transaction coordinator
+ to hold a
+ <classname>Resource</classname>
+ reference that will never be usable. This can occur in two cases:
</para>
<itemizedlist>
<listitem>
<para>
- The process holding the <classname>Resource</classname> crashes before receiving the commit or rollback
+ The process holding the
+ <classname>Resource</classname>
+ crashes before receiving the commit or rollback
request from the coordinator.
</para>
</listitem>
<listitem>
<para>
- The <classname>Resource</classname> receives the commit or rollback, and responds. However, the message is
- lost or the coordinator process has crashed.
+ The
+ <classname>Resource</classname>
+ receives the commit or rollback, and responds. However, the message is
+ lost or the
+ coordinator process has crashed.
</para>
</listitem>
</itemizedlist>
<para>
- In the first case, the <classname>RecoveryManager</classname> for the <classname>Resource</classname>
- <classname>ObjectStore</classname> eventually reconstructs a new <classname>Resource</classname> (with a
- different CORBA object reference (IOR), and issues a <methodname>replay_completion</methodname> request
- containing the new <classname>Resource</classname> IOR. The <classname>RecoveryManager</classname> for the
- coordinator substitutes this in place of the original, useless one, and issues <methodname>commit</methodname>
- to the new reconstructed <classname>Resource</classname>. The <classname>Resource</classname> has to have been
- in a commit state, or there would be no transaction intention list. Until the
- <methodname>replay_completion</methodname> is received, the <classname>RecoveryManager</classname> tries to send
- <methodname>commit</methodname> to its <classname>Resource</classname> reference.–This will fail with a CORBA
- System Exception. Which exception depends on the ORB and other details.
+ In the first case, the
+ <classname>RecoveryManager</classname>
+ for the
+ <classname>Resource</classname>
+ <classname>ObjectStore</classname>
+ eventually reconstructs a new
+ <classname>Resource</classname>
+ (with a
+ different CORBA object reference (IOR), and issues a
+ <methodname>replay_completion</methodname>
+ request
+ containing the new
+ <classname>Resource</classname>
+ IOR. The
+ <classname>RecoveryManager</classname>
+ for the
+ coordinator substitutes this in place of the original, useless one, and issues
+ <methodname>commit</methodname>
+ to the new reconstructed
+ <classname>Resource</classname>
+ . The
+ <classname>Resource</classname>
+ has to have been
+ in a commit state, or there would be no transaction intention list. Until
+ the
+ <methodname>replay_completion</methodname>
+ is received, the
+ <classname>RecoveryManager</classname>
+ tries to send
+ <methodname>commit</methodname>
+ to its
+ <classname>Resource</classname>
+ reference.–This will fail with a CORBA
+ System Exception. Which exception depends on the ORB
+ and other details.
</para>
<para>
- In the second case, the <classname>Resource</classname> no longer exists. The
- <classname>RecoveryManager</classname> at the coordinator will never get through, and will receive System
+ In the second case, the
+ <classname>Resource</classname>
+ no longer exists. The
+ <classname>RecoveryManager</classname>
+ at the coordinator will never get through, and will receive System
Exceptions forever.
</para>
<para>
- The <classname>RecoveryManager</classname> cannot distinguish these two cases by any protocol mechanism. There
- is a perceptible cost in repeatedly attempting to send the commit to an inaccessible
- <classname>Resource</classname>. In particular, the timeouts involved will extend the recovery iteration time,
- and thus potentially leave resources inaccessible for longer.
+ The
+ <classname>RecoveryManager</classname>
+ cannot distinguish these two cases by any protocol mechanism. There
+ is a perceptible cost in
+ repeatedly attempting to send the commit to an inaccessible
+ <classname>Resource</classname>
+ . In particular, the timeouts involved will extend the recovery iteration time,
+ and thus
+ potentially leave resources inaccessible for longer.
</para>
<para>
- To avoid this, the <classname>RecoveryManager</classname> only attempts to send <methodname>commit</methodname>
- to a <classname>Resource</classname> a limited number of times. After that, it considers the transaction
- <phrase>assumed complete</phrase>. It retains the information about the transaction, by changing the object type
- in the <classname>ActionStore</classname>, and if the <classname>Resource</classname> eventually does wake up
- and a <methodname>replay_completion</methodname> request is received, the <classname>RecoveryManager</classname>
- activates the transaction and issues the commit request to the new Resource IOR. The number of times the
- <classname>RecoveryManager</classname> attempts to issue <methodname>commit</methodname> as part of the periodic
- recovery is controlled by the property variable <varname>COMMITTED_TRANSACTION_RETRY_LIMIT</varname>, and
- defaults to <literal>3</literal>.
+ To avoid this, the
+ <classname>RecoveryManager</classname>
+ only attempts to send
+ <methodname>commit</methodname>
+ to a
+ <classname>Resource</classname>
+ a limited number of times. After that, it considers the transaction
+ <phrase>assumed complete</phrase>
+ . It retains the information about the transaction, by changing the object type
+ in the
+ <classname>ActionStore</classname>
+ , and if the
+ <classname>Resource</classname>
+ eventually does wake up
+ and a
+ <methodname>replay_completion</methodname>
+ request is received, the
+ <classname>RecoveryManager</classname>
+ activates the transaction and issues the commit request to the new Resource IOR. The number
+ of times the
+ <classname>RecoveryManager</classname>
+ attempts to issue
+ <methodname>commit</methodname>
+ as part of the periodic
+ recovery is controlled by the property variable
+ <varname>COMMITTED_TRANSACTION_RETRY_LIMIT</varname>
+ , and
+ defaults to
+ <literal>3</literal>
+ .
</para>
</section>
-
+
<section>
<title>Expired entry removal</title>
<para>
- The operation of the recovery subsystem causes some entries to be made in the <classname>ObjectStore</classname>
- that are not removed in normal progress. The <classname>RecoveryManager</classname> has a facility for scanning
- for these and removing items that are very old. Scans and removals are performed by implementations of the
- <interfacename>>com.arjuna.ats.arjuna.recovery.ExpiryScanner</interfacename>. Implementations of this interface
- are loaded by giving the class names as the value of the property
- <varname>RecoveryEnvironmentBean.expiryScannerClassNames</varname>. The <classname>RecoveryManager</classname> calls the
- <methodname>scan</methodname> method on each loaded <classname>ExpiryScanner</classname> implementation at an
- interval determined by the property <varname>RecoveryEnvironmentBean.expiryScanInterval</varname>. This value is
- given in hours, and defaults to <literal>12</literal>. A property value of <literal>0</literal> disables any
- expiry scanning. If the value as supplied is positive, the first scan is performed when
- <classname>RecoveryManager</classname> starts. If the value is negative, the first scan is delayed until after
- the first interval, using the absolute value.
+ The operation of the recovery subsystem causes some entries to be made in the
+ <classname>ObjectStore</classname>
+ that are not removed in normal progress. The
+ <classname>RecoveryManager</classname>
+ has a facility for scanning
+ for these and removing items that are very old. Scans and
+ removals are performed by implementations of the
+ <interfacename>>com.arjuna.ats.arjuna.recovery.ExpiryScanner</interfacename>
+ . Implementations of this interface
+ are loaded by giving the class names as the value of the
+ property
+ <varname>RecoveryEnvironmentBean.expiryScannerClassNames</varname>
+ . The
+ <classname>RecoveryManager</classname>
+ calls the
+ <methodname>scan</methodname>
+ method on each loaded
+ <classname>ExpiryScanner</classname>
+ implementation at an
+ interval determined by the property
+ <varname>RecoveryEnvironmentBean.expiryScanInterval</varname>
+ . This value is
+ given in hours, and defaults to
+ <literal>12</literal>
+ . A property value of
+ <literal>0</literal>
+ disables any
+ expiry scanning. If the value as supplied is positive, the first scan is
+ performed when
+ <classname>RecoveryManager</classname>
+ starts. If the value is negative, the first scan is delayed until after
+ the first interval,
+ using the absolute value.
</para>
<para>
There are two kinds of item that are scanned for expiry:
</para>
<informaltable>
<tgroup cols="2">
- <colspec colwidth="100px"/>
- <colspec colwidth="350px"/>
+ <colspec colwidth="100px" />
+ <colspec colwidth="350px" />
<tbody>
<row>
<entry>Contact items</entry>
<entry>
<para>
- One contact item is created by every application process that uses JBossTS. They contain the
- information that the <classname>RecoveryManager</classname> uses to determine if the process that
- initiated the transaction is still alive, and what the transaction status is. The expiry time for
+ One contact item is created by every application process that uses JBossTS. They
+ contain the
+ information that the
+ <classname>RecoveryManager</classname>
+ uses 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
- <varname>RecoveryEnvironmentBean.transactionStatusManagerExpiryTime</varname>, which is expressed in
- hours. The default is <literal>12</literal>, and <literal>0</literal> suppresses the expiration. This
- is the interval after which a process that cannot be contacted is considered to be dead. It should be
- long enough to avoid accidentally removing valid entries due to short-lived transient errors such as
+ <varname>RecoveryEnvironmentBean.transactionStatusManagerExpiryTime</varname>
+ , which is expressed in
+ hours. The default is
+ <literal>12</literal>
+ , and
+ <literal>0</literal>
+ suppresses the expiration. This
+ is the interval after which a process that cannot
+ be contacted is considered to be dead. It should be
+ long enough to avoid
+ accidentally removing valid entries due to short-lived transient errors such as
network downtime.
</para>
</entry>
@@ -491,16 +518,33 @@
<entry>Assumed complete transactions</entry>
<entry>
<para>
- The expiry time is counted from when the transactions were assumed to be complete. A
- <methodname>replay_completion</methodname> request resets the clock. The risk with removing assumed
- complete transactions it that a prolonged communication outage means that a remote
- <classname>Resource</classname> cannot connect to the <classname>RecoveryManager</classname> for the
- parent transaction. If the assumed complete transaction entry is expired before the communications are
- recovered, the eventual <methodname>replay_completion</methodname> will find no information and the
- <classname>Resource</classname> will be rolled back, although the transaction committed. Consequently,
- the expiry time for assumed complete transactions should be set to a value that exceeds any
- anticipated network outage. The parameter is <varname>ASSUMED_COMPLETE_EXPIRY_TIME</varname>. It is
- expressed in hours, with <literal>240</literal> being the default, and <literal>0</literal> meaning
+ The expiry time is counted from when the transactions were assumed to be complete.
+ A
+ <methodname>replay_completion</methodname>
+ request resets the clock. The risk with removing assumed
+ complete transactions it
+ that a prolonged communication outage means that a remote
+ <classname>Resource</classname>
+ cannot connect to the
+ <classname>RecoveryManager</classname>
+ for the
+ parent transaction. If the assumed complete transaction entry is expired
+ before the communications are
+ recovered, the eventual
+ <methodname>replay_completion</methodname>
+ will find no information and the
+ <classname>Resource</classname>
+ will be rolled back, although the transaction committed. Consequently,
+ the expiry
+ time for assumed complete transactions should be set to a value that exceeds any
+ anticipated network outage. The parameter is
+ <varname>ASSUMED_COMPLETE_EXPIRY_TIME</varname>
+ . It is
+ expressed in hours, with
+ <literal>240</literal>
+ being the default, and
+ <literal>0</literal>
+ meaning
never to expire.
</para>
</entry>
@@ -510,61 +554,103 @@
</informaltable>
<example>
<title>ExpiryScanner properties</title>
- <programlisting language="XML" role="XML"><xi:include href="extras/ExpiryScanner-properties.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ <programlisting language="XML" role="XML"><xi:include
+ href="extras/ExpiryScanner-properties.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
+ parse="text" /></programlisting>
</example>
<para>
- There are two <classname>ExpiryScannner</classname>s for the assumed complete transactions, because there are
- different types in the ActionStore.
+ There are two
+ <classname>ExpiryScannner</classname>
+ s for the assumed complete transactions, because there are
+ different types in the
+ ActionStore.
</para>
</section>
-
+
<section>
<title>Recovery domains</title>
<para>
- A key part of the recovery subsystem is that the <classname>RecoveryManager</classname> hosts the OTS
- <classname>RecoveryCoordinator</classname> objects that handle recovery for transactions initiated in
- application processes. Information passes between the application process and the
- <classname>RecoveryManager</classname> in one of three ways:
+ A key part of the recovery subsystem is that the
+ <classname>RecoveryManager</classname>
+ hosts the OTS
+ <classname>RecoveryCoordinator</classname>
+ objects that handle recovery for transactions initiated in
+ application processes. Information
+ passes between the application process and the
+ <classname>RecoveryManager</classname>
+ in one of three ways:
</para>
<itemizedlist>
<listitem>
<para>
- <classname>RecoveryCoordinator</classname> object references (IORs) are created in the application
- process. They contain information identifying the transaction in the object key. They pass the object key to
- the <classname>Resource</classname> objects, and the <classname>RecoveryManager</classname> receives it.
+ <classname>RecoveryCoordinator</classname>
+ object references (IORs) are created in the application
+ process. They contain information
+ identifying the transaction in the object key. They pass the object key to
+ the
+ <classname>Resource</classname>
+ objects, and the
+ <classname>RecoveryManager</classname>
+ receives it.
</para>
</listitem>
<listitem>
<para>
- The application process and the <classname>RecoveryManager</classname> access the same
- <filename>jbossts-properties.xml</filename>, and therefore use the same <classname>ObjectStore</classname>.
+ The application process and the
+ <classname>RecoveryManager</classname>
+ access the same
+ <filename>jbossts-properties.xml</filename>
+ , and therefore use the same
+ <classname>ObjectStore</classname>
+ .
</para>
</listitem>
<listitem>
<para>
- The <classname>RecoveryCoordinator</classname> invokes CORBA directly in the application, using information
- in the contact items. Contact items are kept in the <classname>ObjectStore</classname>.
+ The
+ <classname>RecoveryCoordinator</classname>
+ invokes CORBA directly in the application, using information
+ in the contact items.
+ Contact items are kept in the
+ <classname>ObjectStore</classname>
+ .
</para>
</listitem>
</itemizedlist>
<para>
Multiple recovery domains may useful if you are doing a migration, and separate
- <classname>ObjectStores</classname> are useful. However, multiple RecoveryManagers can cause problems with XA
- datasources if resource-initiated recovery is active on any of them.
+ <classname>ObjectStores</classname>
+ are useful. However, multiple RecoveryManagers can cause problems with XA
+ datasources if
+ resource-initiated recovery is active on any of them.
</para>
</section>
</section>
-
+
<section>
- <title>Transaction status and <methodname>replay_comparison</methodname></title>
+ <title>
+ Transaction status and
+ <methodname>replay_comparison</methodname>
+ </title>
<para>
- When a transaction successfully commits, the transaction log is removed from the system. The log is no longer
- required, since all registered Resources have responded successfully to the two-phase commit sequence. However, if
- a <classname>Resource</classname> calls <methodname>replay_completion</methodname> on the
- <classname>RecoveryCoordinator</classname> after the transaction it represents commits, the status returned is
- <classname>StatusRolledback</classname>. The transaction system does not keep a record of committed transactions,
- and assumes that in the absence of a transaction log, the transaction must have rolled back. This is in line with
- the <systemitem>presumed abort protocol</systemitem> used by the OTS.
+ When a transaction successfully commits, the transaction log is removed from the system. The
+ log is no longer
+ required, since all registered Resources have responded successfully to the
+ two-phase commit sequence. However, if
+ a
+ <classname>Resource</classname>
+ calls
+ <methodname>replay_completion</methodname>
+ on the
+ <classname>RecoveryCoordinator</classname>
+ after the transaction it represents commits, the status returned is
+ <classname>StatusRolledback</classname>
+ . The transaction system does not keep a record of committed transactions,
+ and assumes that in
+ the absence of a transaction log, the transaction must have rolled back. This is in line with
+ the
+ <systemitem>presumed abort protocol</systemitem>
+ used by the OTS.
</para>
</section>
</chapter>
Modified: labs/jbosstm/trunk/ArjunaJTS/docs/development_guide/en-US/JBossJTS_Development_Guide.ent
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/development_guide/en-US/JBossJTS_Development_Guide.ent 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/development_guide/en-US/JBossJTS_Development_Guide.ent 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,4 +1,4 @@
<!ENTITY PRODUCT "JBossJTS">
<!ENTITY BOOKID "JBossJTS_Development_Guide">
-<!ENTITY YEAR "2010">
+<!ENTITY YEAR "2011">
<!ENTITY HOLDER "JBoss, Inc.">
Modified: labs/jbosstm/trunk/ArjunaJTS/docs/development_guide/en-US/JBossJTS_Development_Guide.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/development_guide/en-US/JBossJTS_Development_Guide.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/development_guide/en-US/JBossJTS_Development_Guide.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -4,24 +4,22 @@
%BOOK_ENTITIES;
]>
<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="Overview.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="JBossTS_Basics.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="OTS.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Constructing_An_OTS_Application.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="JBossTS_Interface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Example.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="JTA_And_JTS.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Tools.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="Configuring_JBossTS.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="IDL_Definitions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="References.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <index />
+ <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="Overview.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossTS_Basics.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="OTS.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Constructing_An_OTS_Application.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossTS_Interface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Example.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="JTA_And_JTS.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Tools.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="Configuring_JBossTS.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="IDL_Definitions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="References.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <!-- <index /> -->
</book>
Modified: labs/jbosstm/trunk/ArjunaJTS/docs/development_guide/en-US/Revision_History.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/development_guide/en-US/Revision_History.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/development_guide/en-US/Revision_History.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -4,24 +4,38 @@
%BOOK_ENTITIES;
]>
<appendix>
- <title>Revision History</title>
- <simpara>
- <revhistory>
- <revision>
- <revnumber>0-0</revnumber>
- <date>Wed Nov 17 2010</date>
- <author>
- <firstname>Misty</firstname>
- <surname>Stanley-Jones</surname>
- <email>misty at redhat.com</email>
- </author>
- <revdescription>
- <simplelist>
- <member>Initial conversion to Docbook</member>
- </simplelist>
- </revdescription>
- </revision>
- </revhistory>
- </simpara>
+ <title>Revision History</title>
+ <simpara>
+ <revhistory>
+ <revision>
+ <revnumber>1</revnumber>
+ <date>Wed Nov 17 2010</date>
+ <author>
+ <firstname>Misty</firstname>
+ <surname>Stanley-Jones</surname>
+ <email>misty at redhat.com</email>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Initial conversion to Docbook</member>
+ </simplelist>
+ </revdescription>
+ </revision>
+ <revision>
+ <revnumber>2</revnumber>
+ <date>Thu Apr 14 2011</date>
+ <author>
+ <firstname>Tom</firstname>
+ <surname>Jenkinson</surname>
+ <email>tom.jenkinson at redhat.com</email>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Moved some content to main developers guide and added tools information</member>
+ </simplelist>
+ </revdescription>
+ </revision>
+ </revhistory>
+ </simpara>
</appendix>
Modified: labs/jbosstm/trunk/ArjunaJTS/docs/development_guide/en-US/Tools.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/development_guide/en-US/Tools.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/development_guide/en-US/Tools.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,495 +1,52 @@
<?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" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "ArjunaCore_Development_Guide.ent">
+<!ENTITY % BOOK_ENTITIES SYSTEM "JBossJTS_Development_Guide.ent">
%BOOK_ENTITIES;
]>
<chapter>
<title>Tools</title>
- <para>
- This chapter explains how to start and use the tools framework and what tools are available.
- </para>
+
<section>
- <title>Starting the Transaction Service tools</title>
+ <title>Introduction</title>
<para>
- The transaction service tools are started differently, depending on your operating system.
+ This chapter includes descriptions of JTS specific tools.
</para>
-
- <procedure id="starting-tools">
- <title>Starting the Transaction Service Tools</title>
- <step>
- <title>Microsoft Windows</title>
- <substeps>
- <step>
- <para>
- Double click on the <guilabel>Start Tools</guilabel> link in the <guilabel>JBoss Transaction
- Service</guilabel> program group in the <guilabel>Start</guilabel> menu.
- </para>
- </step>
- </substeps>
- </step>
- <step>
- <title>Linux / UNIX</title>
- <substeps>
- <step>
- <para>
- In a graphical environment, Start a command prompt and change to the directory where JBoss Transaction
- Service is installed, henceforth referred to as <replaceable>JBOSSTS_INSTALL_DIRECTORY</replaceable>.
- </para>
- </step>
- <step>
- <para>
- Run the <command>run-tools.sh</command> command.
- </para>
- <screen>[user at localhost bin]$ ./run-tools.sh</screen>
- </step>
- </substeps>
- </step>
- <step>
- <title>Result</title>
- <para>
- The <guilabel>Tools</guilabel> window appears. This is the launch area for all of the tools shipped
- with the JBoss Transaction Service. At the top of the window you will notice a menu bar (see Figure 7).
- </para>
- </step>
- </procedure>
-
</section>
-
<section>
- <title>The Tools Window</title>
- <itemizedlist>
- <listitem><para>File</para>
- <variablelist>
- <varlistentry>
- <term>Open JMX Browser</term>
- <listitem>
- <para>
- Displays the <xref linkend="jmx-browser-window" />
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Open Object Store Browser</term>
- <listitem>
- <para>
- Displays the <xref linkend="object-store-browser" />.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Settings</term>
- <listitem>
- <para>
- Allows you to configure application settings.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Exit</term>
- <listitem>
- <para>
- Exits the application.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- <listitem><para>Performance</para>
- <variablelist>
- <varlistentry>
- <term>Open</term>
- <listitem>
- <para>
- Opens a <xref linkend="performance-tool" /> window.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Close All</term>
- <listitem>
- <para>
- Closes all open Performance windows.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- <listitem><para>Window</para>
- <variablelist>
- <varlistentry>
- <term>Cascade Windows</term>
- <listitem>
- <para>
- Arranges windows diagonally so that you can find a specific one.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Numbered list of open windows</term>
- <listitem>
- <para>
- Allows you to focus a window from the list of all open windows.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- <listitem><para>Help</para>
- <variablelist>
- <varlistentry>
- <term>About</term>
- <listitem>
- <para>
- Information about the Tools, including version, licensing, and credits.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </itemizedlist>
- </section>
-
- <section id="performance-tool">
- <title>Using the performance tool</title>
- <para>
- The performance tool can be used to display performance information about the transaction service. This
- information is gathered using the <systemitem>Performance</systemitem> JMX bean, so the transaction service needs
- to be integrated into an application server, such as JBoss Application Server, to give any performance
- information.
+ <title>RMIC Extensions</title>
+ <para>The RMIC extensions allow stubs and tie classes to be generated for transactional RMI-IIOP
+ objects. A transactional object is one which wishes to receive transactional context when one
+ of its methods is invoked. Without transactional object support an RMI-IIOP object won't have
+ transactional context propagated to it when its methods are invoked.</para>
+ <para>The tool works in two ways: i) via the command line, ii) via ANTs RMIC compiler task.
+ Examples of how to use the tool via these methods are covered in the following sections.
</para>
- <para>
- The performance information is displayed via a multi-series graph. To view this graph, open a performance window
- by selecting <menuchoice><guimenu>Performance</guimenu><guimenu>Open</guimenu></menuchoice>.
- </para>
- <para>
- The multi-series graph displays a number of items. The items can be turned on or off from the
- <guimenu>Series</guimenu> menu. When series are enabled, they appear in the legend at the bottom of the graph.
- </para>
- <itemizedlist>
- <listitem><para>Number of transactions.</para></listitem>
- <listitem><para>Number of committed transactions.</para></listitem>
- <listitem><para>Number of aborted transactions.</para></listitem>
- <listitem><para>Number of nested transactions.</para></listitem>
- <listitem><para>Number of heuristics raised.</para></listitem>
- </itemizedlist>
- <para>
- The data shown is graphed against time. The <guilabel>Y-axis</guilabel> represents the number of transactions and
- the <guilabel>X-axis</guilabel> represents time.
- </para>
- <para>
- You can stop and restart the sampling of data at any time using the <guimenu>Sampling</guimenu> menu. You can save
- the data currently visible in the graph to a Comma Separate Values (CSV) file from the
- <menuchoice><guimenu>Data</guimenu><guimenu>Save to .csv</guimenu></menuchoice> option.
- </para>
- </section>
-
- <section id="jmx-browser-window">
- <title>Using the JMX Browser</title>
- <para>
- To open the JMX browser window, choose <menuchoice><guimenu>File</guimenu><guimenu>Open JMX
- Browser</guimenu></menuchoice>. The JMX browser window opens.
- </para>
-
- <para>
- The window has two main sections: the <guilabel>Details</guilabel> panel and the <guilabel>MBean</guilabel> panel.
- The <guilabel>MBean</guilabel> panel displays the MBeans exposed by the MBean server, grouped by domain name. The
- <guilabel>Details</guilabel> panel displays information about the currently selected MBean. To select an MBean,
- select its name with the mouse. Information about the MBean appears in the panel.
- </para>
- <itemizedlist>
- <title>MBean Details</title>
- <listitem><para>The total number of MBeans registered on this server.</para></listitem>
- <listitem><para>The number of constructors exposed by this MBean.</para></listitem>
- <listitem><para>The number of attributes exposed by this MBean.</para></listitem>
- <listitem><para>The number of operations exposed by this MBean.</para></listitem>
- <listitem><para>The number of notifications exposed by this MBean.</para></listitem>
- <listitem><para>A brief description of the MBean.</para></listitem>
- </itemizedlist>
- <para>
- Click the <guilabel>View</guilabel> link to display and operate on the attributes and operations exposed by this
- MBean. You can view readable attributes, alter writable attributes, and invoke operations.
- </para>
-
<section>
- <title>Attributes and Operations</title>
+ <title>Command Line Usage</title>
+ <para>As this tool delegates compilation to the Sun RMIC tool it accepts the same command line
+ parameters. So for more details please see it's documentation for details
+ (http://java.sun.com/j2se/1.4.2/docs/tooldocs/tools.html#rmi). The following is an example
+ of how this can be used:</para>
<para>
- When you click the <guilabel>View</guilabel> link, the <guilabel>View JMX Attributes and Operations</guilabel>
- window appears. You can view all readable attributes exposed by the selected MBean. You can also alter
- writable attributes. If an attribute is read-only then you cannot alter an attribute's value. To alter an
- attribute's value, just double-click the current value and enter the new value. If the
- <guibutton>Edit</guibutton> button is enabled, then you can click it to open an advanced editor. If the
- attribute type is a <systemitem>JMX object name</systemitem>, clicking this button displays the JMX attributes
- and operations for the object.
+ <programlisting role="JAVA" language="Java">java com.arjuna.common.tools.rmictool.RMICTool <parameters></programlisting>
</para>
- <para>
- Click the <guibutton>Refresh</guibutton> button to refresh the attribute values. If an exception occurs while
- retrieving the value of an attribute, the exception is displayed in place of the attribute's value.
- </para>
- <para>
- You can also invoke operations upon an MBean. A list of operations exposed by an MBean is displayed below the
- attributes list. To invoke an operation, select it from the list and click the <guibutton>Invoke</guibutton>
- button. If the operation requires parameters, a window will be displayed, prompting you for the values. You
- specify parameter values in the same way as you specify JMX attribute values. After you have specified a value
- for each of the parameters, click the <guibutton>Invoke</guibutton> button to perform the invocation.
- </para>
- <para>
- After the method invocation is complete, its return value is displayed.
- </para>
</section>
-
-
+ <section>
+ <title>ANT Usage</title>
+ <para>The RMICTool also acts as a plug-in for the ANT RMIC task. To use the RMICTool simply
+ specify the fully qualified classname as the compiler attribute, e.g.</para>
+ <example>
+ <title>
+ Example ANT
+ <classname>rmic</classname>
+ declaration
+ </title>
+ <programlisting language="XML" role="XML"><xi:include
+ href="extras/exampleRMICDeclaration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ <para>The RMICTool JAR file must either be specified in your system classpath or it should be
+ copied into the lib directory of your ANT distribution for it to be found.</para>
+ </section>
</section>
+</chapter>
- <section id="object-store-browser">
- <title>Using the object store browser</title>
- <para>
- To open the Object Store browser, select <menuchoice><guimenu>File</guimenu><guimenu>Open Object State
- Browser</guimenu></menuchoice>.
- </para>
- <para>
- The Object Store Browser window is divided into four sections:
- </para>
- <variablelist>
- <varlistentry>
- <term>Object Store Roots</term>
- <listitem>
- <para>
- The currently available object store roots. Selecting an option from the list repopulate the Object Store
- Hierarchy with the contents of the selected root.
- </para>
- </listitem>
-
- </varlistentry>
- <varlistentry>
- <term>Object Store Hierarchy</term>
- <listitem>
- <para>
- A tree which shows the current object store hierarchy. Selecting a node from this tree displays the objects
- stored in that location.
- </para>
- </listitem>
-
- </varlistentry>
- <varlistentry>
- <term>Objects</term>
- <listitem>
- <para>
- A list of icons which represent the objects stored in the selected location.
- </para>
- </listitem>
-
- </varlistentry>
- <varlistentry>
- <term>Object Details</term>
- <listitem>
- <para>
- Information about the currently selected object, if the object’s type is known to the state viewer
- repository. See <xref linkend="writing-an-osv" /> for more details.
- </para>
- </listitem>
-
- </varlistentry>
-
- </variablelist>
- <section id="writing-an-osv">
- <title>Object state viewers (OSV)</title>
- <para>
- When an object is selected in the <guilabel>Objects</guilabel> pane of the main window, the registered Object
- State Viewer (OSV) for that object type is invoked. An OSV makes information about the selected object
- available via the user interface. An OSV for Atomic Actions is distributed with the standard tools. It displays
- information on the Abstract Records in its various lists, such as heuristic, failed, and read-only. You can
- write your own OSVs to display information about object types you have defined.
- </para>
-
- <section>
- <title>Writing an OSV</title>
- <para>
- Writing an OSV plug-in allows you to extend the capabilities of the Object Store browser to show the state of
- user-defined abstract records. An OSV plug-in is a class which implements the interface
- <interfacename>com.arjuna.ats.tools.objectstorebrowser.stateviewers.StateViewerInterface </interfacename>.
- Package it in a JAR within the <filename>plugins</filename> directory. This example shows how to create an OSV
- plug-in for an abstract record subclass which looks as follows:
- </para>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/abstract_record_subclass.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- <para>
- When this abstract record is viewed in the object store browser, showing the current value is simple. You can
- read the state into an instance of the abstract record and call <methodname>getValue()</methodname>. The
- following is the object store browser plug-in source code:
- </para>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/osv_plugin.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- <para>
- The method <methodname>uidNodeExpanded</methodname> is invoked when a Uid representing the given type is
- expanded in the object store hierarchy tree. This is not required by this plug-in as this abstract record is
- not visible in the object store directly, but only via one of the lists in an atomic action. The method
- <methodname>entrySelected</methodname> is invoked when an entry is selected from the object view which
- represents an object with the given type. In both methods the State Panel is used to display information
- regarding the state of the object. The State Panel has the following methods that assist in display this
- information:
- </para>
- <variablelist>
- <title>Methods of <classname>StatePanel</classname></title>
- <varlistentry>
- <term><methodname>setInfo</methodname>(<type>String</type> <varname>info</varname>)</term>
- <listitem>
- <para>
- Shows general information.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>setData</methodname>(<type>String</type> <varname>name</varname>, <type>String</type> <varname>value</varname>)</term>
- <listitem>
- <para>
- Puts information into the table which is displayed by the object store browser tool.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>enableDetailsButton</methodname>(<type>DetailsButtonListener</type> <varname>listener</varname>)</term>
- <listitem>
- <para>
- Enables the <guibutton>Details</guibutton> button. The listener interface allows a plug-in to be
- informed when the button is pressed. It is up to the plug-in developer to decide how to display this
- further information.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>
- This example reads the state from the object store and uses the value returned by
- <methodname>getValue()</methodname> to put an entry into the state panel table. The
- <methodname>getType()</methodname> method returns the type this plug-in is to be registered against.
- </para>
- <para>
- To add this plug-in to the object store browser, package it into a JAR file with a name that is prefixed with
- <filename>osv-</filename>. The JAR file must contain certain information within the manifest file so that the
- object store browser knows which classes are plug-ins. See <xref linkend="osv-plugin-ant" /> for how to do
- this using Apache Ant.
- </para>
-
- <example id="osv-plugin-ant">
- <title>Packaging an OSV using Apache Ant</title>
- <programlisting language="XML" role="XML"><xi:include href="extras/osv-plugin-ant.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
- <para>
- After creating the JAR with the correct information in the manifest file, place it in the
- <filename>bin/tools/plugins</filename> directory.
- </para>
- </section>
- </section>
-
-
- <section>
- <title>ObjectStore command-line editors</title>
- <para>
- There are currently two command-line editors for manipulating the ObjectStore. These tools are used to
- manipulate the lists of heuristic participants maintained by a transaction log. They allow a heuristic
- participant to be moved from that list back to the list of prepared participants so that transaction recovery
- may attempt to resolve them automatically.
- </para>
-
-
- <section>
- <title>LogEditor</title>
- <para>
- Started by executing <methodname>com.arjuna.ats.arjuna.tools.log.LogBrowser</methodname>, this tool supports
- the following options that can be provided on the command-line.
- </para>
- <table>
- <title>LogEditor Options</title>
- <tgroup cols="2">
- <colspec colwidth="150px"/>
- <colspec colwidth="290px"/>
-
- <thead>
- <row>
- <entry>Option</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>-tx <replaceable>id</replaceable></entry>
- <entry><para>Specifies the transaction log to work on.</para></entry>
- </row>
- <row>
- <entry>-type <replaceable>name</replaceable></entry>
- <entry><para>The transaction type to work on.</para></entry>
- </row>
- <row>
- <entry>-dump</entry>
- <entry><para>Print out the contents of the log identified by the other options.</para></entry>
- </row>
- <row>
- <entry>-forget <replaceable>index</replaceable></entry>
- <entry><para>Move the specified target from the heuristic list to the prepared list.</para></entry>
- </row>
- <row>
- <entry>-help</entry>
- <entry><para>Print out the list of commands and options.</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section>
- <title>LogBrowser</title>
- <para>
- The LogBrowser, invoked by calling <methodname>com.arjuna.ats.arjuna.tools.log.LogBrowser</methodname>, is
- similar to the LogEditor, but allows multiple log instances to be manipulated. It presents a shell-like
- interface, with the following options:
- </para>
-
- <table>
- <title>LogBrowserOptions</title>
- <tgroup cols="2">
- <colspec colwidth="150px"/>
- <colspec colwidth="290px"/>
-
- <thead>
- <row>
- <entry>Option</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>ls [<replaceable>type</replaceable>]</entry>
- <entry><para>List the logs for the specified type. If no type is specified, the editor must already be
- attached to the transaction type.</para></entry>
- </row>
- <row>
- <entry>select [<replaceable>type</replaceable>]</entry>
- <entry><para>Browse a specific transaction type. If already attached to a transaction type, you are
- detached from that type first.</para></entry>
- </row>
- <row>
- <entry>attach <replaceable>log</replaceable></entry>
- <entry><para>Attach the console to the specified transaction log. If you are attached to another log,
- the command will fail.</para></entry>
- </row>
- <row>
- <entry>detach</entry>
- <entry><para>Detach the console from the current log.</para></entry>
- </row>
- <row>
- <entry>forget <replaceable>pid</replaceable></entry>
- <entry><para>Move the specified heuristic participant back to the <systemitem>prepared</systemitem>
- list. The console must be attached.</para></entry>
- </row>
- <row>
- <entry>delete <replaceable>pid</replaceable></entry>
- <entry><para>Delete the specified heuristic participant. The console must be attached.</para></entry>
- </row>
- <row>
- <entry>types</entry>
- <entry><para>List the supported transaction types.</para></entry>
- </row>
- <row>
- <entry>quit</entry>
- <entry><para>Exit the console tool.</para></entry>
- </row>
- <row>
- <entry>help</entry> <entry><para>Print out the supported commands.</para></entry> </row> </tbody>
- </tgroup> </table> </section> </section> </section> </chapter>
Added: labs/jbosstm/trunk/ArjunaJTS/docs/development_guide/en-US/extras/exampleRMICDeclaration.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/development_guide/en-US/extras/exampleRMICDeclaration.xml (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/development_guide/en-US/extras/exampleRMICDeclaration.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -0,0 +1,2 @@
+<rmic compiler="com.arjuna.common.tools.rmictool.RMICTool" classname="RMIObjectImpl" base="build-dir"
+ verify="true" iiop="true" iiopopts="-poa" classpathref="build.classpath" />
\ No newline at end of file
Modified: labs/jbosstm/trunk/ArjunaJTS/docs/orbportability/en-US/JBossJTS_ORB_Portability_Guide.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/orbportability/en-US/JBossJTS_ORB_Portability_Guide.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/orbportability/en-US/JBossJTS_ORB_Portability_Guide.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -9,5 +9,5 @@
<xi:include href="About_This_Guide.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="ORB_Portability_API.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <index />
+ <!-- <index /> -->
</book>
Modified: labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/JBossJTS_Quick_Start_Guide.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/JBossJTS_Quick_Start_Guide.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/quick_start/en-US/JBossJTS_Quick_Start_Guide.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -9,5 +9,5 @@
<xi:include href="About_This_Guide.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Quick_Start_to_JTS_OTS.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <index />
+ <!-- <index /> -->
</book>
Modified: labs/jbosstm/trunk/XTS/docs/Transactions_XTS_Administration_And_Development_Guide/en-US/Transactions_XTS_Administration_And_Development_Guide.ent
===================================================================
--- labs/jbosstm/trunk/XTS/docs/Transactions_XTS_Administration_And_Development_Guide/en-US/Transactions_XTS_Administration_And_Development_Guide.ent 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/XTS/docs/Transactions_XTS_Administration_And_Development_Guide/en-US/Transactions_XTS_Administration_And_Development_Guide.ent 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,7 +1,7 @@
<!ENTITY PRODUCT "JBoss Transactions">
<!ENTITY BOOKID "XTS_Development_Guide">
<!ENTITY VERSION "4.13">
-<!ENTITY YEAR "2010">
+<!ENTITY YEAR "2011">
<!ENTITY HOLDER "JBoss.org">
<!ENTITY APPSERVER "JBoss Application Server">
<!-- <!ENTITY APPSERVER "Enterprise Application Platform Server"> -->
Modified: labs/jbosstm/trunk/XTS/docs/Transactions_XTS_Administration_And_Development_Guide/en-US/Transactions_XTS_Administration_And_Development_Guide.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/Transactions_XTS_Administration_And_Development_Guide/en-US/Transactions_XTS_Administration_And_Development_Guide.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/XTS/docs/Transactions_XTS_Administration_And_Development_Guide/en-US/Transactions_XTS_Administration_And_Development_Guide.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -20,6 +20,6 @@
<xi:include href="Web_Service_Transaction_Management.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <index />
+ <!-- <index /> -->
</book>
Added: labs/jbosstm/trunk/docs/development_guide/en-US/About_This_Guide.xml
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/About_This_Guide.xml (rev 0)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/About_This_Guide.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -0,0 +1,42 @@
+<?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" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "Development_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>About This Guide</title>
+ <para>
+ The Programmers Guide contains information on how to use &PRODUCT;.
+ This
+ document provides a detailed look at the design and operation of &PRODUCT;.
+ It describes the
+ architecture and the interaction of components within this architecture.
+ </para>
+ <section>
+ <title>Audience</title>
+ <para>
+ This guide is most relevant to engineers who are responsible for developing using &PRODUCT;.
+ Although this guide is specifically intended for service
+ developers, it will be
+ useful to anyone
+ who would like to gain an understanding of
+ transactions and how they function.
+ </para>
+ </section>
+ <section>
+ <title>Prerequisites</title>
+ <para>
+ This guide assumes a basic familiarity with Java service development and object-oriented
+ programming. A fundamental level of understanding in the following areas will also be useful:
+ <itemizedlist>
+ <listitem>
+ <para>General understanding of the APIs, components, and objects that are present in Java
+ applications.</para>
+ </listitem>
+ <listitem>
+ <para>A general understanding of the Windows and UNIX operating systems.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+</chapter>
Property changes on: labs/jbosstm/trunk/docs/development_guide/en-US/About_This_Guide.xml
___________________________________________________________________
Added: svn:mime-type
+ text/plain
Modified: labs/jbosstm/trunk/docs/development_guide/en-US/Author_Group.xml
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/Author_Group.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/Author_Group.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,6 +1,6 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "JBossJTA_Development_Guide.ent">
+<!ENTITY % BOOK_ENTITIES SYSTEM "Development_Guide.ent">
%BOOK_ENTITIES;
]>
<authorgroup>
Modified: labs/jbosstm/trunk/docs/development_guide/en-US/Book_Info.xml
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/Book_Info.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/Book_Info.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,18 +1,18 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "JBossJTA_Development_Guide.ent">
+<!ENTITY % BOOK_ENTITIES SYSTEM "Development_Guide.ent">
%BOOK_ENTITIES;
]>
-<bookinfo id="book-JBossJTA_Development_Guide-JBossJTA_Development_Guide">
- <title>JBossJTA Development Guide</title>
- <subtitle>Development reference guide for the JBossJTA implementation of the JTA API</subtitle>
- <productname>JBossJTA</productname>
+<bookinfo id="book-Development_Guide-Development_Guide">
+ <title>Development Guide</title>
+ <subtitle> Development reference guide for the JBoss Transactions Suite of software</subtitle>
+ <productname>JBoss Transactions</productname>
<productnumber>4.15.0</productnumber>
<edition>0</edition>
<pubsnumber>0</pubsnumber>
<abstract>
<para>
- Development reference guide for the ArjunaTA implementation of the JTA API
+ Development reference guide for the JBoss Transactions Suite of software
</para>
</abstract>
<corpauthor>
Modified: labs/jbosstm/trunk/docs/development_guide/en-US/Chapter.xml
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/Chapter.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/Chapter.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,6 +1,6 @@
<?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" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "JBossJTA_Development_Guide.ent">
+<!ENTITY % BOOK_ENTITIES SYSTEM "Development_Guide.ent">
%BOOK_ENTITIES;
]>
<chapter>
Copied: labs/jbosstm/trunk/docs/development_guide/en-US/Configuration_Options.xml (from rev 36927, labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/Configuration_Options.xml)
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/Configuration_Options.xml (rev 0)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/Configuration_Options.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -0,0 +1,226 @@
+<?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" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "Development_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter id="chap-configuration-options">
+ <title>Configuration options</title>
+
+ <section>
+ <title>Loading a configuration</title>
+ <para>
+ Each module of the system contains a <classname><replaceable>module</replaceable>propertyManager</classname>
+ class., which provides static getter methods for one or more
+ <classname><replaceable>name</replaceable>EnvironmentBean</classname> classes. An example is
+ <classname>com.arjuna.ats.arjuna.commmon.arjPropertyManager</classname>. These environment beans are standard
+ JavaBean containing properties for each configuration option in the system. Typical usage is of the form:
+ </para>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/defaultTimeout.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ <para>
+ These beans are singletons, instantiated upon first access, using the following algorithm.
+ </para>
+ <procedure>
+ <title>Algorithm for environment bean instantiation</title>
+ <step>
+ <para>
+ The properties are loaded and populated from a properties file named and located as follows:
+ </para>
+ <substeps>
+ <step>
+ <para>
+ If the properties file name property is set, its value is used as the file name.
+ </para>
+ </step>
+ <step>
+ <para>
+ If not, the default file name is used.
+ </para>
+ </step>
+ </substeps>
+ </step>
+ <step>
+ <para>
+ The file thus named is searched for by, in order
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ absolute path
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ user.dir
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ user.home
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ java.home
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ directories contained on the classpath
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ a default file embedded in the product .jar file.
+ </para>
+ </listitem>
+ </orderedlist>
+ </step>
+ <step>
+ <para>
+ The file is treated as being of standard java.util.Properties xml format and loaded accordingly. The entry
+ names are of the form EnvironmentBeanClass.propertyName:<code><entry
+ key="CoordinatorEnvironmentBean.commitOnePhase">YES</entry></code>. Valid values for Boolean
+ properties are case-insensitive, and may be one of:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ NO
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ YES
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ FALSE
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ TRUE
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ OFF
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ ON
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ In the case of properties that take multiple values, they are white-space-delimited.
+ </para>
+ <example>
+ <title>Example Environment Bean</title>
+ <programlisting language="XML" role="XML"> <xi:include href="extras/EnvironmentBeans.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ </step>
+ <step>
+ <para>
+ After the file is loaded, it is cached and is not re-read until the JVM is restarted. Changes to the
+ properties file require a restart in order to take effect.
+ </para>
+ </step>
+ <step>
+ <para>
+ After the properties are loaded, the EnvironmentBean is then inspected and, for each field, if the properties
+ contains a matching key in the search order as follows, the <methodname>setter</methodname> method for that field is invoked with the
+ value from the properties, or the system properties if different.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Fully.Qualified.NameEnvironmentBean.propertyName
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ NameEnvironmentBean.propertyName (this is the preferred form used in the properties file)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the old com.arjuna... properties key (deprecated, for backwards compatibility only).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </step>
+ <step>
+ <para>
+ The bean is then returned to the caller, which may further override values by calling setter methods.
+ </para>
+ </step>
+ </procedure>
+ <para>
+ The implementation reads most bean properties only once, as the consuming component or class is instantiated. This
+ usually happens the first time a transaction is run. As a result, calling <methodname>setter</methodname> methods
+ to change the value of bean properties while the system is running typically has no effect, unless it is done
+ prior to any use of the transaction system. Altered bean properties are not persisted back to the properties file.
+ </para>
+ <para>
+ You can configure the system using a bean wiring system such as JBoss Microcontainer or Spring. Take care when
+ instantiating beans, to obtain the singleton via the static getter (factory) method on the module property
+ manager. Using a new bean instantiated with the default constructor is ineffective, since it is not possible to
+ pass this configured bean back to the property management system.
+ </para>
+ </section>
+
+
+ <section>
+ <title>Options</title>
+ <para>
+ The canonical reference for configuration options is the Javadoc of the various
+ <classname>EnvironmentBean</classname> classes, For ArjunaCore these are:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <classname>com.arjuna.common.internal.util.logging.LoggingEnvironmentBean.java </classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <classname>com.arjuna.common.internal.util.logging.basic.BasicLogEnvironmentBean.java </classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <classname>com.arjuna.ats.txoj.common.TxojEnvironmentBean.java </classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <classname>com.arjuna.ats.arjuna.common.CoordinatorEnvironmentBean.java </classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <classname>com.arjuna.ats.arjuna.common.ObjectStoreEnvironmentBean.java </classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <classname>com.arjuna.ats.arjuna.common.RecoveryEnvironmentBean.java </classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <classname>com.arjuna.ats.arjuna.common.CoreEnvironmentBean.java </classname>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Additional modules built on ArjunaCore may include further beans containing module-specific configuration
+ options. Refer to the documentation for the specific modules for more information.
+ </para>
+ </section>
+
+</chapter>
+
Copied: labs/jbosstm/trunk/docs/development_guide/en-US/Development_Guide.ent (from rev 36931, labs/jbosstm/trunk/docs/development_guide/en-US/JBossJTA_Development_Guide.ent)
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/Development_Guide.ent (rev 0)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/Development_Guide.ent 2011-04-14 13:12:59 UTC (rev 36934)
@@ -0,0 +1,4 @@
+<!ENTITY PRODUCT "Documentation">
+<!ENTITY BOOKID "Development_Guide">
+<!ENTITY YEAR "2011">
+<!ENTITY HOLDER "JBoss, Inc.">
Copied: labs/jbosstm/trunk/docs/development_guide/en-US/Development_Guide.xml (from rev 36931, labs/jbosstm/trunk/docs/development_guide/en-US/JBossJTA_Development_Guide.xml)
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/Development_Guide.xml (rev 0)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/Development_Guide.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -0,0 +1,18 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "Development_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<book>
+ <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Preface.xml" />
+ <xi:include href="About_This_Guide.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Transactions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="The_Resource_Manager.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="General_Transaction_Issues.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Tools.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Configuration_Options.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <!-- <index /> -->
+</book>
+
Deleted: labs/jbosstm/trunk/docs/development_guide/en-US/Examples.xml
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/Examples.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/Examples.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,61 +0,0 @@
-<?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" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "JBossJTA_Development_Guide.ent">
-%BOOK_ENTITIES;
-]>
-<chapter>
- <title>Examples</title>
-
- <section>
- <title>JDBC example</title>
-
- <example>
- <title>JDBC example</title>
- <para>
- This simplified example assumes that you are using the transactional JDBC driver provided with JBossTS. For
- details about how to configure and use this driver see the previous Chapter.<!-- Link? -->
- </para>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/jdbc_example.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
- </section>
-
- <section>
- <title>Failure recovery example with BasicXARecovery</title>
- <para>
- This class implements the <interfacename>XAResourceRecovery</interfacename> interface for XAResources. The parameter supplied in <varname>setParameters</varname>
- can contain arbitrary information necessary to initialize the class once created. In this example, it contains the
- name of the property file in which the database connection information is specified, as well as the number of
- connections that this file contains information on. Each item is separated by a semicolon.
- </para>
- <para>
- This is only a small example of the sorts of things an XAResourceRecovery implementer could do. This implementation
- uses a property file that is assumed to contain sufficient information to recreate connections used during the
- normal run of an application so that recovery can be performed on them. Typically, user-names and passwords should
- never be presented in raw text on a production system.
- </para>
- <example>
- <title>Database parameter format for the properties file</title>
- <screen>
- DB_x_DatabaseURL=
- DB_x_DatabaseUser=
- DB_x_DatabasePassword=
- DB_x_DatabaseDynamicClass=
- </screen>
- <para>
- <replaceable>x</replaceable> is the number of the connection information.
- </para>
- </example>
- <para>
- Some error-handling code is missing from this example, to make it more readable.
- </para>
- <example>
- <title>Failure recovery example with BasicXARecovery</title>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/failure_recovery_example.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- <para>
- You can use the class <classname>com.arjuna.ats.internal.jdbc.recovery.JDBC2RecoveryConnection</classname> to
- create a new connection to the database using the same parameters used to create the initial connection.
- </para>
- </example>
- </section>
-</chapter>
-
Copied: labs/jbosstm/trunk/docs/development_guide/en-US/General_Transaction_Issues.xml (from rev 36927, labs/jbosstm/trunk/ArjunaCore/docs/development_guide/en-US/General_Transaction_Issues.xml)
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/General_Transaction_Issues.xml (rev 0)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/General_Transaction_Issues.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -0,0 +1,293 @@
+<?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" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "Development_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>General Transaction Issues</title>
+ <section>
+ <title>Advanced transaction issues with TxCore</title>
+ <para>
+ Atomic actions (transactions) can be used by both application programmers and class
+ developers. Thus entire
+ operations (or parts of operations) can be made atomic as required by
+ the
+ semantics of a particular operation. This
+ chapter will describe some of the more subtle
+ issues
+ involved with using transactions in general and TxCore in
+ particular.
+
+ </para>
+
+ <section>
+ <title>Checking transactions</title>
+ <para>
+ In a multi-threaded application, multiple threads may be associated with a transaction
+ during its lifetime,
+ sharing the context. In addition, it is possible that if one thread
+ terminates a transaction, other threads may
+ still be active within it. In a distributed
+ environment, it can be difficult to guarantee that all threads have
+ finished with a
+ transaction
+ when it is terminated. By default, TxCore will issue a warning if a thread
+ terminates
+ a
+ transaction when other threads are still active within it. However, it will allow
+ the
+ transaction termination to
+ continue.
+ </para>
+ <para>
+ Other solutions to this problem are possible. One example would be to block the thread which
+ is terminating the
+ transaction until all other threads have disassociated themselves from the
+ transaction context. Therefore, TxCore
+ provides the
+ <classname>com.arjuna.ats.arjuna.coordinator.CheckedAction</classname>
+ class, which allows the thread
+ or transaction termination policy to be overridden. Each
+ transaction has an instance of this class associated with
+ it, and application programmers can
+ provide their own implementations on a per transaction basis.
+ </para>
+ <example>
+ <title>
+ Class
+ <classname>CheckedAction</classname>
+ </title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/CheckedAction.java"
+ xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ <para>
+ When a thread attempts to terminate the transaction and there are active threads within it,
+ the system will invoke
+ the
+ <methodname>check</methodname>
+ method on the transaction’s
+ <systemitem>CheckedAction</systemitem>
+ object. The
+ parameters to the check method are:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>isCommit</term>
+ <listitem>
+ <para>
+ Indicates whether the transaction is in the process of committing or rolling back.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>actUid</term>
+ <listitem>
+ <para>
+ The transaction identifier.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>list</term>
+ <listitem>
+ <para>
+ A list of all of the threads currently marked as active within this transaction.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ When
+ <methodname>check</methodname>
+ returns, the transaction termination will continue. Obviously the state of the
+ transaction at
+ this point may be different from that when
+ <methodname>check</methodname>
+ was called, e.g., the
+ transaction may subsequently have been committed.
+ </para>
+ <para>
+ A
+ <classname>CheckedAction</classname>
+ instance is created for each transaction. As mentioned above, the default
+ implementation
+ simply
+ issues warnings in the presence of multiple threads active on the transaction when it
+ is
+ terminated. However, a different instance can be provided to each transaction in one of
+ the
+ following ways:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Use the
+ <methodname>setCheckedAction</methodname>
+ method on the
+ <classname>BasicAction</classname>
+ instance.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Define an implementation of the
+ <interfacename>CheckedActionFactory</interfacename>
+ interface, which has a
+ single method
+ <methodname>getCheckedAction</methodname>
+ (
+ <type>final Uid</type>
+ <varname>txId</varname>
+ ,
+ <type>final String</type>
+ <varname>actionType</varname>
+ ) that returns a
+ <classname>CheckedAction</classname>
+ . The factory class name can then be provided to the Transaction Service
+ at runtime by
+ setting the
+ <varname>CoordinatorEnvironmentBean.checkedActionFactory</varname>
+ property.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Gathering statistics</title>
+ <para>
+ By default, the Transaction Service does not maintain any history information about
+ transactions. However, by
+ setting the
+ <varname>CoordinatorEnvironmentBean.enableStatistics</varname>
+ property variable to
+ <literal>YES</literal>
+ , the transaction service will maintain information about the number of transactions
+ created,
+ and their outcomes. This information can be obtained during the execution of a
+ transactional
+ application
+ via the
+ <classname>com.arjuna.ats.arjuna.coordinator.TxStats</classname>
+ class.
+ </para>
+ <example>
+ <title>
+ Class
+ <classname>TxStats</classname>
+ </title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/TxStats.java"
+ xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ <para>
+ The class
+ <classname>ActionManager</classname>
+ gives further information about specific active transactions
+ through the classes
+ <classname>getTimeAdded</classname>
+ , which returns the time (in milliseconds) when the
+ transaction was created, and
+ <classname>inflightTransactions</classname>
+ , which returns the list of currently
+ active transactions.
+ </para>
+ </section>
+
+ <section>
+ <title>Asynchronously committing a transaction</title>
+ <para>
+ By default, the Transaction Service executes the
+ <methodname>commit</methodname>
+ protocol of a top-level
+ transaction in a synchronous manner. All registered resources will be
+ told to prepare in order by a single thread,
+ and then they will be told to commit or
+ rollback.
+ This has several possible disadvantages:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ In the case of many registered resources, the
+ <methodname>prepare</methodname>
+ operating can logically be
+ invoked in parallel on each resource. The disadvantage is that
+ if an “early” resource in the list of
+ registered resource forces a rollback during
+ <methodname>prepare</methodname>
+ , possibly many prepare
+ operations will have been made needlessly.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ In the case where heuristic reporting is not required by the application, the second
+ phase of the commit
+ protocol can be done asynchronously, since its success or failure is
+ not important.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Therefore, JBoss Transaction Service provides runtime options to enable possible threading
+ optimizations. By
+ setting the
+ <varname>CoordinatorEnvironmentBean.asyncPrepare</varname>
+ environment variable to
+ <literal>YES</literal>
+ , during the
+ <methodname>prepare</methodname>
+ phase a separate thread will be created for
+ each registered participant within the
+ transaction.
+ By setting
+ <varname>CoordinatorEnvironmentBean.asyncCommit</varname>
+ to
+ <literal>YES</literal>
+ , a separate thread will be
+ created to complete the second phase of the transaction if
+ knowledge about heuristics outcomes is not required.
+ </para>
+ </section>
+ <section>
+ <title>Transaction Logs</title>
+ <para>JBossTS supports a number of different transaction log implementations. They are
+ outlined
+ below.</para>
+ <section>
+ <title>The ActionStore</title>
+ <para>This is the original version of the transaction log as provided in prior releases. It
+ is
+ simple but slow. Each transaction has an instance of its own log and they are all
+ written to
+ the same location in the file system</para>
+ </section>
+ <section>
+ <title>The HashedActionStore</title>
+ <para>This implementation is based on the ActionStore but the individual logs are striped
+ across a number of sub-directories to improve performance. Check the Configuration Options
+ table for how to configure the HashedActionStore.</para>
+ </section>
+ <section>
+ <title>LogStore</title>
+ <para>This implementation is based on a traditional transaction log. All transaction states
+ within the same process (VM instance) are written to the same log (file), which is an
+ append-only entity. When transaction data would normally be deleted, e.g., at the end of
+ the
+ transaction, a delete record is added to the log instead. Therefore, the log just keeps
+ growing. Periodically a thread runs to prune the log of entries that have been deleted.
+ </para>
+ <para>A log is initially given a maximum capacity beyond which it cannot grow. Once this is
+ reached the system will create a new log for transactions that could not be accommodated
+ in
+ the original log. The new log and the old log are pruned as usual. During the normal
+ execution of the transaction system there may be an arbitrary number of log instances.
+ These
+ should be garbage collected by the system (or the recovery sub-system) eventually.
+ </para>
+ <para>Check the Configuration Options table for how to configure the LogStore.</para>
+ </section>
+ </section>
+ </section>
+</chapter>
+
Deleted: labs/jbosstm/trunk/docs/development_guide/en-US/JBossJTA_Development_Guide.ent
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/JBossJTA_Development_Guide.ent 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/JBossJTA_Development_Guide.ent 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,4 +0,0 @@
-<!ENTITY PRODUCT "Documentation">
-<!ENTITY BOOKID "JBossJTA_Development_Guide">
-<!ENTITY YEAR "2010">
-<!ENTITY HOLDER "JBoss, Inc.">
Deleted: labs/jbosstm/trunk/docs/development_guide/en-US/JBossJTA_Development_Guide.xml
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/JBossJTA_Development_Guide.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/JBossJTA_Development_Guide.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,21 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "JBossJTA_Development_Guide.ent">
-%BOOK_ENTITIES;
-]>
-<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="Java_Transaction_API.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Transactions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="The_Resource_Manager.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Transaction_Recovery.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="JDBC.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Examples.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Configuring_JBossTA.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Using_JBossTA_In_Application_Servers.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <index />
-</book>
-
Deleted: labs/jbosstm/trunk/docs/development_guide/en-US/JDBC.xml
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/JDBC.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/JDBC.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,310 +0,0 @@
-<?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" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "JBossJTA_Development_Guide.ent">
-%BOOK_ENTITIES;
-]>
-<chapter>
- <title>JDBC and Transactions</title>
-
- <section>
- <title>Using the transactional JDBC driver</title>
- <para>
- JBossJTA supports construction of both local and distributed transactional applications which access databases
- using the JDBC APIs. JDBC supports two-phase commit of transactions, and is similar to the XA X/Open
- standard. JBossTS provides JDBC support in package <package>com.arjuna.ats.jdbc</package>. A list of the tested
- drivers is available from the JBossTS website.<!-- Put this in an appendix? Link directly to it? -->
- </para>
- <para>
- Only use the transactional JDBC support provided in package <package>com.arjuna.ats.jdbc</package> when you are
- using JBossTS outside of an application server, such as JBoss Application Server, or another container. Otherwise,
- use the JDBC support provided by your application server or container.
- </para>
- <section>
- <title>Managing transactions</title>
- <para>
- JBossJTA needs the ability to associate work performed on a JDBC connection with a specific
- transaction. Therefore, applications need to use a combination of implicit transaction propagation and indirect
- transaction management. For each JDBC connection, JBossJTA must be able to determine the invoking thread's
- current transaction context.
- </para>
- </section>
- <section>
- <title>Restrictions</title>
- <para>
- Nested transactions are not supported by JDBC. If you try to use a JDBC connection within a subtransaction,
- JBossJTA throws a suitable exception and no work is allowed on that connection. However, if you need nested
- transactions, and are comfortable with straying from the JDBC standard, you can set property
- <varname>com.arjuna.ats.jta.supportSubtransactions</varname> property to <literal>YES</literal>.
- </para>
- </section>
- </section>
-
- <section>
- <title>Transactional drivers</title>
- <para>
- The approach JBossJTA takes for incorporating JDBC connections within transactions is to provide transactional
- JDBC drivers as conduits for all interactions. These drivers intercept all invocations and ensure that they are
- registered with, and driven by, appropriate transactions. The driver
- <classname>com.arjuna.ats.jdbc.TransactionalDriver</classname> handles all JDBC drivers, implementing the
- <interfacename>java.sql.Driver</interfacename> interface. If the database is not transactional, ACID properties
- cannot be guaranteed.
- </para>
- <section>
- <title>Loading drivers</title>
- <example>
- <title>Instantiating and using the driver within an application</title>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/instantiating_transactionaldriver.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
-
- <example>
- <title>Registering the drivers with the JDBC driver manager using the Java system properties</title>
- <programlisting language="Java" role="JAVA">
- <xi:include href="extras/registering_transactionaldriver_using_jdbc_driver_manager.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- <para>
- The jdbc.drivers property contains a colon-separated list of driver class names, which the JDBC driver manager
- loads when it is initialized. After the driver is loaded, you can use it to make a connection with a
- database.
- </para>
- </example>
- <example>
- <title>Using the <methodname>Class.forName</methodname> method</title>
- <para>
- Calling <methodname>Class.forName()</methodname> automatically registers the driver with the JDBC driver
- manager. It is also possible to explicitly create an instance of the JDBC driver.
- </para>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/class.forName.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
- </section>
- </section>
-
-
- <section>
- <title>Connections</title>
- <para>
- Because JBossJTA provides JDBC connectivity via its own JDBC driver, application code can support transactions
- with relatively small code changes. Typically, the application programmer only needs to start and terminate
- transactions.
- </para>
- <section>
- <title>JDBC</title>
- <para>
- The JBossJTA driver accepts the following properties, all located in class
- <classname>com.arjuna.ats.jdbc.TransactionalDriver</classname>.
- </para>
- <informaltable>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>username</entry>
- <entry>
- <para>
- the database username
- </para>
- </entry>
- </row>
- <row>
- <entry>password</entry>
- <entry>
- <para>
- the database password
- </para>
- </entry>
- </row>
- <row>
- <entry>createDb</entry>
- <entry>
- <para>
- creates the database automatically if set to <literal>true</literal>. Not all JDBC implementations
- support this.
- </para>
- </entry>
- </row>
- <row>
- <entry>dynamicClass</entry>
- <entry>
- <para>
- specifies a class to instantiate to connect to the database, instead of using JNDI.
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </section>
- <section>
- <title>XADataSources</title>
- <para>
- JDBC connections are created from appropriate DataSources. Connections which participate in distributed
- transactions are obtained from XADataSources. When using a JDBC driver, JBossJTA uses the appropriate DataSource
- whenever a connection to the database is made. It then obtains XAResources and registers them with the
- transaction via the JTA interfaces. The transaction service uses these XAResources when the transaction
- terminates in order to drive the database to either commit or roll back the changes made via the JDBC
- connection.
- </para>
- <para>
- JBossJTA JDBC support can obtain XADataSources through the Java Naming and Directory Interface (JNDI) or dynamic
- class instantiation.
- </para>
- <section>
- <title>Java naming and directory interface (JNDI)</title>
- <para>
- A JDBC driver can use arbitrary DataSources without having to know specific details about their
- implementations, by using JNDI. A specific DataSource or XADataSource can be created and registered with an
- appropriate JNDI implementation, and the application, or JDBC driver, can later bind to and use it. Since JNDI
- only allows the application to see the DataSource or XADataSource as an instance of the interface (e.g.,
- javax.sql.XADataSource) rather than as an instance of the implementation class (e.g.,
- com.mydb.myXADataSource), the application is not tied at build-time to only use a specific implementation.
- </para>
- <para>
- For the TransactionalDriver class to use a JNDI-registered XADataSource, you need to create the
- XADataSource instance and store it in an appropriate JNDI implementation. Details of how to do this can be
- found in the JDBC tutorial available at the Java web site.<!--Link?-->
- </para>
- <example>
- <title>Storing a datasource in a JNDI implementation</title>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/storing_datasource_in_jndi.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /> </programlisting>
- <para>
- The Context.INITIAL_CONTEXT_FACTORY property is the JNDI way of specifying the type of JNDI
- implementation to use.
- </para>
- <para>
- The application must pass an appropriate connection URL to the JDBC driver:
- </para>
- <programlisting language="Java" role="JAVA">
- <xi:include href="extras/passing_connection_url_to_jdbc.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- <para>
- The JNDI URL must be pre-pended with <literal>jdbc:arjuna:</literal> in order for the TransactionalDriver to
- recognize that the DataSource must participate within transactions and be driven accordingly.
- </para>
- </example>
- </section>
- <section>
- <title>Dynamic class instantiation</title>
- <para>
- If a JNDI implementation is not available. you can specify an implementation of the
- <interfacename>DynamicClass</interfacename> interface, which is used to get the XADataSource object. This is
- not recommended, but provides a fallback for environments where use of JNDI is not feasible.
- </para>
- <para>
- Use the property <varname>TransactionalDriver.dynamicClass</varname> to specify the implementation to use. An
- example is <literal>PropertyFileDynamicClass</literal>, a DynamicClass implementation that reads the
- XADataSource implementation class name and configuration properties from a file, then instantiates and
- configures it.
- </para>
- <note>
- <title>Deprecated class</title>
- <para>
- The oracle_8_1_6 dynamic class is deprecated and should not be used.
- </para>
- </note>
- <example>
- <title>Instantiating a dynamic class</title>
- <para>
- The application code must specify which dynamic class the TransactionalDriver should instantiate when
- setting up the connection:
- </para>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/instantiating_dynamic_class.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
- </section>
- </section>
- <section>
- <title>Using the connection</title>
- <para>
- Once the connection is established, all operations on the connection are monitored by JBossJTA. you do not need
- to use the transactional connection within transactions. If a transaction is not present when the connection is
- used, then operations are performed directly on the database.
- </para>
- <important>
- <para>
- JDBC does not support subtransactions.
- </para>
- </important>
- <para>
- You can use transaction timeouts to automatically terminate transactions if a connection is not terminated
- within an appropriate period.
- </para>
- <para>
- You can use JBossJTA connections within multiple transactions simultaneously. An example would be different
- threads, with different notions of the current transaction. JBossJTA does connection pooling for each
- transaction within the JDBC connection. Although multiple threads may use the same instance of the JDBC
- connection, internally there may be a separate connection for each transaction. With the exception of method
- <methodname>close</methodname>, all operations performed on the connection at the application level are only
- performed on this transaction-specific connection.
- </para>
- <para>
- JBossJTA automatically registers the JDBC driver connection with the transaction via an appropriate
- resource. When the transaction terminates, this resource either commits or rolls back any changes made to the
- underlying database via appropriate calls on the JDBC driver.
- </para>
- <para>
- Once created, the driver and any connection can be used in the same way as any other JDBC driver or connection.
- </para>
- <example>
- <title>Creating and using a connection</title>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/creating_and_using_a_connection.java"
- xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
- </section>
-
- <section>
- <title>Connection pooling</title>
- <para>
- For each user name and password, JBossJTA maintains a single instance of each connection for as long as that
- connection is in use. Subsequent requests for the same connection get a reference to the original connection,
- rather than a new instance. You can try to close the connection, but the connection will only actually be closed
- when all users (including transactions) have either finished with the connection, or issued
- <methodname>close</methodname> calls.
- </para>
- </section>
-
- <section>
- <title>Reusing connections</title>
- <para>
- Some JDBC drivers allow the reuse of a connection for multiple different transactions once a given transaction
- completes. Unfortunately this is not a common feature, and other drivers require a new connection to be
- obtained for each new transaction. By default, the JBossJTA transactional driver always obtains a new
- connection for each new transaction. However, if an existing connection is available and is currently unused,
- JBossJTA can reuse this connection. To turn on this feature, add option <varname>reuseconnection=true</varname>
- to the JDBC URL. For instance, <code>jdbc:arjuna:sequelink://host:port;databaseName=foo;reuseconnection=true</code>
- </para>
- </section>
-
- <section>
- <title>Terminating the transaction</title>
- <para>
- When a transaction with an associated JDBC connection terminates, because of the application or because a
- transaction timeout expires, JBossJTA uses the JDBC driver to drive the database to either commit or roll back
- any changes made to it. This happens transparently to the application.
- </para>
- </section>
-
- <section>
- <title>AutoCommit</title>
- <para>
- If property <varname>AutoCommit</varname> of the interface <varname>java.sql.Connection</varname> is set to
- <literal>true</literal> for JDBC, the execution of every SQL statement is a separate top-level transaction, and
- it is not possible to group multiple statements to be managed within a single OTS transaction. Therefore,
- JBossJTA disables <varname>AutoCommit</varname> on JDBC connections before they can be used. If
- <varname>AutoCommit</varname> is later set to <literal>true</literal> by the application, JBossJTA throws the
- <systemitem>java.sql.SQLException</systemitem>.
- </para>
- </section>
-
- <section>
- <title>Setting isolation levels</title>
- <para>
- When you use the JBossJTA JDBC driver, you may need to set the underlying transaction isolation level on the XA
- connection. By default, this is set to <literal>TRANSACTION_SERIALIZABLE</literal>, but another value may be
- more appropriate for your application. To change it, set the property
- <varname>com.arjuna.ats.jdbc.isolationLevel</varname> to the appropriate isolation level in string form. Example
- values are <literal>TRANSACTION_READ_COMMITTED</literal> or <literal>TRANSACTION_REPEATABLE_READ</literal>.
- </para>
- <note>
- <para>
- Currently, this property applies to all XA connections created in the JVM.
- </para>
- </note>
- </section>
- </section>
-</chapter>
-
Deleted: labs/jbosstm/trunk/docs/development_guide/en-US/Java_Transaction_API.xml
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/Java_Transaction_API.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/Java_Transaction_API.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,84 +0,0 @@
-<?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" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "JBossJTA_Development_Guide.ent">
-%BOOK_ENTITIES;
-]>
-<chapter>
- <title>The Java Transaction API (JTA)</title>
- <para>
- The interfaces specified by the many transaction standards tend to be too low-level for most application
- programmers. Therefore, Sun Microsystems created the Java Transaction API (JTA), which specifies higher-level
- interfaces to assist in the development of distributed transactional applications.
- </para>
- <para>
- Note, these interfaces are still low-level. You still need to implement state management and concurrency for
- transactional applications. The interfaces are also optimized for applications which require XA resource integration
- capabilities, rather than the more general resources which other transactional APIs allow.
- </para>
- <para>
- With reference to JTA 1.1 (<ulink url="http://www.oracle.com/technetwork/java/javaee/tech/jta-138684.html" />),
- distributed transaction services typically involve a number of participants:
- </para>
- <informaltable>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>application server</entry>
- <entry>
- <para>
- provides the infrastructure required to support the application run-time environment which includes
- transaction state management, such as an EJB server.
- </para>
- </entry>
- </row>
- <row>
- <entry>transaction manager</entry>
- <entry>
- <para>
- provides the services and management functions required to support transaction demarcation, transactional
- resource management, synchronization, and transaction context propagation.
- </para>
- </entry>
- </row>
- <row>
- <entry>resource manager</entry>
- <entry>
- <para>
- Using a <firstterm>resource adapter</firstterm>, provides the application with access to resources. The
- resource manager participates in distributed transactions by implementing a transaction resource interface
- used by the transaction manager to communicate transaction association, transaction completion and
- recovery.
- </para>
- <para>
- A resource adapter is used by an application server or client to connect to a Resource Manager. JDBC
- drivers which are used to connect to relational databases are examples of Resource Adapters.
- </para>
- </entry>
- </row>
- <row>
- <entry>communication resource manager</entry>
- <entry>
- <para>
- supports transaction context propagation and access to the transaction service for incoming and outgoing
- requests.
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <para>
- From the point of view of the transaction manager, the actual implementation of the transaction services does not
- need to be exposed. You only need to define high-level interfaces to allow transaction demarcation, resource
- enlistment, synchronization and recovery process to be driven from the users of the transaction services. The JTA is
- a high-level application interface that allows a transactional application to demarcate transaction boundaries, and
- also contains a mapping of the X/Open XA protocol.
- </para>
- <important>
- <title>Compatibility</title>
- <para>
- the JTA support provided by JBossJTA is compliant with the 1.1 specification.
- </para>
- </important>
-</chapter>
-
Modified: labs/jbosstm/trunk/docs/development_guide/en-US/Preface.xml
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/Preface.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/Preface.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,23 +1,13 @@
-<?xml version='1.0' encoding='utf-8' ?>
+<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "JBossJTA_Development_Guide.ent">
-%BOOK_ENTITIES;
+<!ENTITY % BOOK_ENTITIES SYSTEM "Failure_Recovery_Guide.ent">
]>
-<preface>
- <title>Preface</title>
-
- <section>
- <title>Prerequisites</title>
- <para>
- ArjunaTA works in conjunction with ArjunaCore. In addition to the documentation here, consult the ArjunaCore
- documentation, which ships as part of ArjunaCore and is also available on the JBoss Transaction Service website
- at <ulink url="http://www.jboss.org/jbosstm" />.
- </para>
- </section>
-
- <xi:include href="Common_Content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude"><xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude"><xi:include href="Common_Content/Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-</xi:fallback>
- </xi:include>
+<preface id="pref-Failure_Recovery_Guide-Preface">
+ <title>Preface</title>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Common_Content/Conventions.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Feedback.xml">
+ <xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude">
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Common_Content/Feedback.xml"/>
+ </xi:fallback>
+ </xi:include>
</preface>
-
Modified: labs/jbosstm/trunk/docs/development_guide/en-US/Revision_History.xml
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/Revision_History.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/Revision_History.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,14 +1,14 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "JBossJTA_Development_Guide.ent">
+<!ENTITY % BOOK_ENTITIES SYSTEM "Development_Guide.ent">
%BOOK_ENTITIES;
]>
-<appendix id="appe-JBossJTA_Development_Guide-Revision_History">
+<appendix id="appe-Development_Guide-Revision_History">
<title>Revision History</title>
<simpara>
<revhistory>
<revision>
- <revnumber>0-0</revnumber>
+ <revnumber>1</revnumber>
<date>Thu Oct 28 2010</date>
<author>
<firstname>Misty</firstname>
@@ -21,6 +21,20 @@
</simplelist>
</revdescription>
</revision>
+ <revision>
+ <revnumber>2</revnumber>
+ <date>Thu Apr 14 2011</date>
+ <author>
+ <firstname>Tom</firstname>
+ <surname>Jenkinson</surname>
+ <email>tom.jenkinson at redhat.com</email>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Taken from JBossJTA development guide and selected others</member>
+ </simplelist>
+ </revdescription>
+ </revision>
</revhistory>
</simpara>
</appendix>
Modified: labs/jbosstm/trunk/docs/development_guide/en-US/The_Resource_Manager.xml
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/The_Resource_Manager.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/The_Resource_Manager.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,6 +1,6 @@
<?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" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "JBossJTA_Development_Guide.ent">
+<!ENTITY % BOOK_ENTITIES SYSTEM "Development_Guide.ent">
%BOOK_ENTITIES;
]>
<chapter>
Copied: labs/jbosstm/trunk/docs/development_guide/en-US/Tools.xml (from rev 36927, labs/jbosstm/trunk/ArjunaJTS/docs/development_guide/en-US/Tools.xml)
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/Tools.xml (rev 0)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/Tools.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -0,0 +1,495 @@
+<?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" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "Development_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>Tools</title>
+ <para>
+ This chapter explains how to start and use the tools framework and what tools are available.
+ </para>
+ <section>
+ <title>Starting the Transaction Service tools</title>
+ <para>
+ The transaction service tools are started differently, depending on your operating system.
+ </para>
+
+ <procedure id="starting-tools">
+ <title>Starting the Transaction Service Tools</title>
+ <step>
+ <title>Microsoft Windows</title>
+ <substeps>
+ <step>
+ <para>
+ Double click on the <guilabel>Start Tools</guilabel> link in the <guilabel>JBoss Transaction
+ Service</guilabel> program group in the <guilabel>Start</guilabel> menu.
+ </para>
+ </step>
+ </substeps>
+ </step>
+ <step>
+ <title>Linux / UNIX</title>
+ <substeps>
+ <step>
+ <para>
+ In a graphical environment, Start a command prompt and change to the directory where JBoss Transaction
+ Service is installed, henceforth referred to as <replaceable>JBOSSTS_INSTALL_DIRECTORY</replaceable>.
+ </para>
+ </step>
+ <step>
+ <para>
+ Run the <command>run-tools.sh</command> command.
+ </para>
+ <screen>[user at localhost bin]$ ./run-tools.sh</screen>
+ </step>
+ </substeps>
+ </step>
+ <step>
+ <title>Result</title>
+ <para>
+ The <guilabel>Tools</guilabel> window appears. This is the launch area for all of the tools shipped
+ with the JBoss Transaction Service. At the top of the window you will notice a menu bar (see Figure 7).
+ </para>
+ </step>
+ </procedure>
+
+ </section>
+
+ <section>
+ <title>The Tools Window</title>
+ <itemizedlist>
+ <listitem><para>File</para>
+ <variablelist>
+ <varlistentry>
+ <term>Open JMX Browser</term>
+ <listitem>
+ <para>
+ Displays the <xref linkend="jmx-browser-window" />
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Open Object Store Browser</term>
+ <listitem>
+ <para>
+ Displays the <xref linkend="object-store-browser" />.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Settings</term>
+ <listitem>
+ <para>
+ Allows you to configure application settings.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Exit</term>
+ <listitem>
+ <para>
+ Exits the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ <listitem><para>Performance</para>
+ <variablelist>
+ <varlistentry>
+ <term>Open</term>
+ <listitem>
+ <para>
+ Opens a <xref linkend="performance-tool" /> window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Close All</term>
+ <listitem>
+ <para>
+ Closes all open Performance windows.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ <listitem><para>Window</para>
+ <variablelist>
+ <varlistentry>
+ <term>Cascade Windows</term>
+ <listitem>
+ <para>
+ Arranges windows diagonally so that you can find a specific one.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Numbered list of open windows</term>
+ <listitem>
+ <para>
+ Allows you to focus a window from the list of all open windows.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ <listitem><para>Help</para>
+ <variablelist>
+ <varlistentry>
+ <term>About</term>
+ <listitem>
+ <para>
+ Information about the Tools, including version, licensing, and credits.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section id="performance-tool">
+ <title>Using the performance tool</title>
+ <para>
+ The performance tool can be used to display performance information about the transaction service. This
+ information is gathered using the <systemitem>Performance</systemitem> JMX bean, so the transaction service needs
+ to be integrated into an application server, such as JBoss Application Server, to give any performance
+ information.
+ </para>
+ <para>
+ The performance information is displayed via a multi-series graph. To view this graph, open a performance window
+ by selecting <menuchoice><guimenu>Performance</guimenu><guimenu>Open</guimenu></menuchoice>.
+ </para>
+ <para>
+ The multi-series graph displays a number of items. The items can be turned on or off from the
+ <guimenu>Series</guimenu> menu. When series are enabled, they appear in the legend at the bottom of the graph.
+ </para>
+ <itemizedlist>
+ <listitem><para>Number of transactions.</para></listitem>
+ <listitem><para>Number of committed transactions.</para></listitem>
+ <listitem><para>Number of aborted transactions.</para></listitem>
+ <listitem><para>Number of nested transactions.</para></listitem>
+ <listitem><para>Number of heuristics raised.</para></listitem>
+ </itemizedlist>
+ <para>
+ The data shown is graphed against time. The <guilabel>Y-axis</guilabel> represents the number of transactions and
+ the <guilabel>X-axis</guilabel> represents time.
+ </para>
+ <para>
+ You can stop and restart the sampling of data at any time using the <guimenu>Sampling</guimenu> menu. You can save
+ the data currently visible in the graph to a Comma Separate Values (CSV) file from the
+ <menuchoice><guimenu>Data</guimenu><guimenu>Save to .csv</guimenu></menuchoice> option.
+ </para>
+ </section>
+
+ <section id="jmx-browser-window">
+ <title>Using the JMX Browser</title>
+ <para>
+ To open the JMX browser window, choose <menuchoice><guimenu>File</guimenu><guimenu>Open JMX
+ Browser</guimenu></menuchoice>. The JMX browser window opens.
+ </para>
+
+ <para>
+ The window has two main sections: the <guilabel>Details</guilabel> panel and the <guilabel>MBean</guilabel> panel.
+ The <guilabel>MBean</guilabel> panel displays the MBeans exposed by the MBean server, grouped by domain name. The
+ <guilabel>Details</guilabel> panel displays information about the currently selected MBean. To select an MBean,
+ select its name with the mouse. Information about the MBean appears in the panel.
+ </para>
+ <itemizedlist>
+ <title>MBean Details</title>
+ <listitem><para>The total number of MBeans registered on this server.</para></listitem>
+ <listitem><para>The number of constructors exposed by this MBean.</para></listitem>
+ <listitem><para>The number of attributes exposed by this MBean.</para></listitem>
+ <listitem><para>The number of operations exposed by this MBean.</para></listitem>
+ <listitem><para>The number of notifications exposed by this MBean.</para></listitem>
+ <listitem><para>A brief description of the MBean.</para></listitem>
+ </itemizedlist>
+ <para>
+ Click the <guilabel>View</guilabel> link to display and operate on the attributes and operations exposed by this
+ MBean. You can view readable attributes, alter writable attributes, and invoke operations.
+ </para>
+
+ <section>
+ <title>Attributes and Operations</title>
+ <para>
+ When you click the <guilabel>View</guilabel> link, the <guilabel>View JMX Attributes and Operations</guilabel>
+ window appears. You can view all readable attributes exposed by the selected MBean. You can also alter
+ writable attributes. If an attribute is read-only then you cannot alter an attribute's value. To alter an
+ attribute's value, just double-click the current value and enter the new value. If the
+ <guibutton>Edit</guibutton> button is enabled, then you can click it to open an advanced editor. If the
+ attribute type is a <systemitem>JMX object name</systemitem>, clicking this button displays the JMX attributes
+ and operations for the object.
+ </para>
+ <para>
+ Click the <guibutton>Refresh</guibutton> button to refresh the attribute values. If an exception occurs while
+ retrieving the value of an attribute, the exception is displayed in place of the attribute's value.
+ </para>
+ <para>
+ You can also invoke operations upon an MBean. A list of operations exposed by an MBean is displayed below the
+ attributes list. To invoke an operation, select it from the list and click the <guibutton>Invoke</guibutton>
+ button. If the operation requires parameters, a window will be displayed, prompting you for the values. You
+ specify parameter values in the same way as you specify JMX attribute values. After you have specified a value
+ for each of the parameters, click the <guibutton>Invoke</guibutton> button to perform the invocation.
+ </para>
+ <para>
+ After the method invocation is complete, its return value is displayed.
+ </para>
+ </section>
+
+
+ </section>
+
+ <section id="object-store-browser">
+ <title>Using the object store browser</title>
+ <para>
+ To open the Object Store browser, select <menuchoice><guimenu>File</guimenu><guimenu>Open Object State
+ Browser</guimenu></menuchoice>.
+ </para>
+ <para>
+ The Object Store Browser window is divided into four sections:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>Object Store Roots</term>
+ <listitem>
+ <para>
+ The currently available object store roots. Selecting an option from the list repopulate the Object Store
+ Hierarchy with the contents of the selected root.
+ </para>
+ </listitem>
+
+ </varlistentry>
+ <varlistentry>
+ <term>Object Store Hierarchy</term>
+ <listitem>
+ <para>
+ A tree which shows the current object store hierarchy. Selecting a node from this tree displays the objects
+ stored in that location.
+ </para>
+ </listitem>
+
+ </varlistentry>
+ <varlistentry>
+ <term>Objects</term>
+ <listitem>
+ <para>
+ A list of icons which represent the objects stored in the selected location.
+ </para>
+ </listitem>
+
+ </varlistentry>
+ <varlistentry>
+ <term>Object Details</term>
+ <listitem>
+ <para>
+ Information about the currently selected object, if the object’s type is known to the state viewer
+ repository. See <xref linkend="writing-an-osv" /> for more details.
+ </para>
+ </listitem>
+
+ </varlistentry>
+
+ </variablelist>
+ <section id="writing-an-osv">
+ <title>Object state viewers (OSV)</title>
+ <para>
+ When an object is selected in the <guilabel>Objects</guilabel> pane of the main window, the registered Object
+ State Viewer (OSV) for that object type is invoked. An OSV makes information about the selected object
+ available via the user interface. An OSV for Atomic Actions is distributed with the standard tools. It displays
+ information on the Abstract Records in its various lists, such as heuristic, failed, and read-only. You can
+ write your own OSVs to display information about object types you have defined.
+ </para>
+
+ <section>
+ <title>Writing an OSV</title>
+ <para>
+ Writing an OSV plug-in allows you to extend the capabilities of the Object Store browser to show the state of
+ user-defined abstract records. An OSV plug-in is a class which implements the interface
+ <interfacename>com.arjuna.ats.tools.objectstorebrowser.stateviewers.StateViewerInterface </interfacename>.
+ Package it in a JAR within the <filename>plugins</filename> directory. This example shows how to create an OSV
+ plug-in for an abstract record subclass which looks as follows:
+ </para>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/abstract_record_subclass.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ <para>
+ When this abstract record is viewed in the object store browser, showing the current value is simple. You can
+ read the state into an instance of the abstract record and call <methodname>getValue()</methodname>. The
+ following is the object store browser plug-in source code:
+ </para>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/osv_plugin.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ <para>
+ The method <methodname>uidNodeExpanded</methodname> is invoked when a Uid representing the given type is
+ expanded in the object store hierarchy tree. This is not required by this plug-in as this abstract record is
+ not visible in the object store directly, but only via one of the lists in an atomic action. The method
+ <methodname>entrySelected</methodname> is invoked when an entry is selected from the object view which
+ represents an object with the given type. In both methods the State Panel is used to display information
+ regarding the state of the object. The State Panel has the following methods that assist in display this
+ information:
+ </para>
+ <variablelist>
+ <title>Methods of <classname>StatePanel</classname></title>
+ <varlistentry>
+ <term><methodname>setInfo</methodname>(<type>String</type> <varname>info</varname>)</term>
+ <listitem>
+ <para>
+ Shows general information.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><methodname>setData</methodname>(<type>String</type> <varname>name</varname>, <type>String</type> <varname>value</varname>)</term>
+ <listitem>
+ <para>
+ Puts information into the table which is displayed by the object store browser tool.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><methodname>enableDetailsButton</methodname>(<type>DetailsButtonListener</type> <varname>listener</varname>)</term>
+ <listitem>
+ <para>
+ Enables the <guibutton>Details</guibutton> button. The listener interface allows a plug-in to be
+ informed when the button is pressed. It is up to the plug-in developer to decide how to display this
+ further information.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ This example reads the state from the object store and uses the value returned by
+ <methodname>getValue()</methodname> to put an entry into the state panel table. The
+ <methodname>getType()</methodname> method returns the type this plug-in is to be registered against.
+ </para>
+ <para>
+ To add this plug-in to the object store browser, package it into a JAR file with a name that is prefixed with
+ <filename>osv-</filename>. The JAR file must contain certain information within the manifest file so that the
+ object store browser knows which classes are plug-ins. See <xref linkend="osv-plugin-ant" /> for how to do
+ this using Apache Ant.
+ </para>
+
+ <example id="osv-plugin-ant">
+ <title>Packaging an OSV using Apache Ant</title>
+ <programlisting language="XML" role="XML"><xi:include href="extras/osv-plugin-ant.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ <para>
+ After creating the JAR with the correct information in the manifest file, place it in the
+ <filename>bin/tools/plugins</filename> directory.
+ </para>
+ </section>
+ </section>
+
+
+ <section>
+ <title>ObjectStore command-line editors</title>
+ <para>
+ There are currently two command-line editors for manipulating the ObjectStore. These tools are used to
+ manipulate the lists of heuristic participants maintained by a transaction log. They allow a heuristic
+ participant to be moved from that list back to the list of prepared participants so that transaction recovery
+ may attempt to resolve them automatically.
+ </para>
+
+
+ <section>
+ <title>LogEditor</title>
+ <para>
+ Started by executing <methodname>com.arjuna.ats.arjuna.tools.log.LogBrowser</methodname>, this tool supports
+ the following options that can be provided on the command-line.
+ </para>
+ <table>
+ <title>LogEditor Options</title>
+ <tgroup cols="2">
+ <colspec colwidth="150px"/>
+ <colspec colwidth="290px"/>
+
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>-tx <replaceable>id</replaceable></entry>
+ <entry><para>Specifies the transaction log to work on.</para></entry>
+ </row>
+ <row>
+ <entry>-type <replaceable>name</replaceable></entry>
+ <entry><para>The transaction type to work on.</para></entry>
+ </row>
+ <row>
+ <entry>-dump</entry>
+ <entry><para>Print out the contents of the log identified by the other options.</para></entry>
+ </row>
+ <row>
+ <entry>-forget <replaceable>index</replaceable></entry>
+ <entry><para>Move the specified target from the heuristic list to the prepared list.</para></entry>
+ </row>
+ <row>
+ <entry>-help</entry>
+ <entry><para>Print out the list of commands and options.</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section>
+ <title>LogBrowser</title>
+ <para>
+ The LogBrowser, invoked by calling <methodname>com.arjuna.ats.arjuna.tools.log.LogBrowser</methodname>, is
+ similar to the LogEditor, but allows multiple log instances to be manipulated. It presents a shell-like
+ interface, with the following options:
+ </para>
+
+ <table>
+ <title>LogBrowserOptions</title>
+ <tgroup cols="2">
+ <colspec colwidth="150px"/>
+ <colspec colwidth="290px"/>
+
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>ls [<replaceable>type</replaceable>]</entry>
+ <entry><para>List the logs for the specified type. If no type is specified, the editor must already be
+ attached to the transaction type.</para></entry>
+ </row>
+ <row>
+ <entry>select [<replaceable>type</replaceable>]</entry>
+ <entry><para>Browse a specific transaction type. If already attached to a transaction type, you are
+ detached from that type first.</para></entry>
+ </row>
+ <row>
+ <entry>attach <replaceable>log</replaceable></entry>
+ <entry><para>Attach the console to the specified transaction log. If you are attached to another log,
+ the command will fail.</para></entry>
+ </row>
+ <row>
+ <entry>detach</entry>
+ <entry><para>Detach the console from the current log.</para></entry>
+ </row>
+ <row>
+ <entry>forget <replaceable>pid</replaceable></entry>
+ <entry><para>Move the specified heuristic participant back to the <systemitem>prepared</systemitem>
+ list. The console must be attached.</para></entry>
+ </row>
+ <row>
+ <entry>delete <replaceable>pid</replaceable></entry>
+ <entry><para>Delete the specified heuristic participant. The console must be attached.</para></entry>
+ </row>
+ <row>
+ <entry>types</entry>
+ <entry><para>List the supported transaction types.</para></entry>
+ </row>
+ <row>
+ <entry>quit</entry>
+ <entry><para>Exit the console tool.</para></entry>
+ </row>
+ <row>
+ <entry>help</entry> <entry><para>Print out the supported commands.</para></entry> </row> </tbody>
+ </tgroup> </table> </section> </section> </section> </chapter>
Deleted: labs/jbosstm/trunk/docs/development_guide/en-US/Transaction_Recovery.xml
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/Transaction_Recovery.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/Transaction_Recovery.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,254 +0,0 @@
-<?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" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "JBossJTA_Development_Guide.ent">
-%BOOK_ENTITIES;
-]>
-<chapter>
- <title>Transaction Recovery</title>
-
- <section>
- <title>Failure recovery</title>
- <para>
- During recovery, the Transaction Manager must communicate with all resource managers being used by the
- applications in the system. For each resource manager, the Transaction Manager uses the
- <methodname>XAResource.recover</methodname> method to retrieve the list of transactions that are currently in a
- <systemitem>prepared</systemitem> or <systemitem>heuristically completed</systemitem> state. Typically, a system
- administrator, rather than a developer, configures all transactional resource factories that are used by the
- applications deployed on the system. The JDBC <interfacename>XADataSource</interfacename> object, which is a
- factory for JDBC <interfacename>XAConnection</interfacename> objects, is such an example..
- </para>
- <para>
- <interfacename>XAResource</interfacename> objects are not persistent across system failures, so the Transaction
- Manager needs a way to acquire the <interfacename>XAResource</interfacename> objects representing the resource
- managers which might have participated in the transactions before a system failure. For example, a Transaction
- Manager might use the JNDI look-up mechanism to acquire a connection from each of the transactional resource
- factories, before obtaining the corresponding <interfacename>XAResource</interfacename> object for each
- connection. The Transaction Manager then invokes the <methodname>XAResource.recover</methodname> method, which
- requests each resource manager to return the transactions that are currently in a
- <systemitem>prepared</systemitem> or <systemitem>heuristically completed</systemitem> state.
- </para>
- <para>
- XA recovery necessitates informing JBossTS which types of Xid to recover. Each Xid that JBossTS
- creates has a unique node identifier encoded within it, and JBossTS only recovers transactions and states that
- match a specified node identifier. Provide the node identifier to JBossTS with the property
- <varname>JTAEnvironmentBean.xaRecoveryNodes</varname>. You can pass multiple values in a list.
- </para>
- <warning>
- <para>
- Setting <varname>JTAEnvironmentBean.xaRecoveryNodes</varname> to <literal>*</literal> forces JBossTS to recover,
- and possibly roll back, all transactions, regardless of their node identifiers. Use this value only with extreme
- caution.
- </para>
- </warning>
- <para>
- If you use the JBossJTA JDBC driver, JBossJTA manages all XAResource crash recovery
- automatically. Otherwise one of the following recovery mechanisms is used.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- If the <interfacename>XAResource</interfacename> is serializable, the serialized form is saved during
- transaction commitment, and used during recovery. The recreated <interfacename>XAResource</interfacename> is
- assumed to be valid, and you can use it to drive recovery on the associated database.
- </para>
- </listitem>
- <listitem>
- <para>
- Otherwise, interfaces <interfacename>com.arjuna.ats.jta.recovery.XAResourceRecovery</interfacename>,
- <interfacename>com.arjuna.ats.jta.recovery.XARecoveryResourceManager</interfacename>, and
- <methodname>com.arjuna.ats.jta.recovery.XARecoveryResource</methodname> are used. Each is documented in the
- JDBC chapters on failure recovery.<!-- Where is this? -->
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>Recovering XA connections</title>
- <para>
- During failure recovery, JBossJTA needs the ability to reconnect to databases that were in use prior to the
- failures, to resolve any outstanding transactions. Most connection information is saved by the transaction service
- during its normal execution, and can be used during recovery to recreate the connection. However, sometimes a
- failure occurs before all of the information can be saved, but after the database connection is used. For JBossTS
- to recreate connections in this type of scenario, you need to provide implementations of JBossJTA interface
- <interfacename>com.arjuna.ats.jta.recovery.XAResourceRecovery</interfacename> for each database in use by your
- applications.
- </para>
- <note>
- <para>
- The transactional JDBC driver provided with JBossJTA does all of this work for you.
- </para>
- </note>
- <para>
- To inform the recovery system about each of the <interfacename>XAResourceRecovery</interfacename> instances,
- specify their class names through the <varname>JTAEnvironmentBean.xaResourceRecoveryInstances</varname> property
- variable, as a list of space-separated strings. Each string is a classname followed by optional configuration
- information.
- </para>
- <example>
- <title>Example <varname>JTAEnvironmentBean.xaResourceRecoveryInstances</varname> value</title>
- <para>
- Without configuration information:
- </para>
- <screen>JTAEnvironmentBean.xaResourceRecoveryInstances=com.foo.barRecovery</screen>
- <para>
- With configuration information:
- </para>
- <screen>JTAEnvironmentBean.xaResourceRecoveryInstances=com.foo.barRecovery;myData=hello</screen>
- </example>
- <para>
- These properties need to go into the JTA section of the property file. Any errors will be reported during
- recovery.
- </para>
-
- <example>
- <title>Example <interfacename>XAResourceRecovery</interfacename> implementation</title>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/XAResourceRecovery_implementation.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
-
- <table>
- <title>Return values for <interfacename>XAResourceRecovery</interfacename> methods</title>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>initialise</entry>
- <entry>
- <para>
- After the instance is created, any additional information found after the first semi-colon is passed to
- the object. The object can then use this information in an implementation-specific manner to initialise
- itself, or for another purpose.
- </para>
- </entry>
- </row>
- <row>
- <entry>hasMoreResources</entry>
- <entry>
- <para>
- Each <interfacename>XAResourceRecovery</interfacename> implementation may provide multiple
- <interfacename>XAResource</interfacename> instances. Before any call to method
- <methodname>getXAResource</methodname> is made, method <methodname>hasMoreResources</methodname> is
- called to determine whether there are any further connections to be obtained. If this returns
- <literal>false</literal>, <methodname>getXAResource</methodname> is not called again during this
- recovery sweep, and the instance is not used again until the next recovery scan. The implementation must
- maintain the internal state backing this method and reset the iteration as required. Otherwise, the
- second and subsequent recovery sweeps in the lifetime of the JVM do not attempt recovery.
- </para>
- </entry>
- </row>
- <row>
- <entry>getXAResource</entry>
- <entry>
- <para>
- Returns an instance of the XAResource object. The <interfacename>XAResourceRecovery</interfacename>
- implementation determines how the instance is created, and how the parameters to its constructors are
- obtained. The parameters to the constructors of this class are similar to the ones used when creating
- the initial driver or data source, and must be sufficient to create new
- <interfacename>XAResource</interfacename>s to drive recovery.
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <note>
- <title>Calling <interfacename>XAResourRecovery</interfacename> during each sweep</title>
- <para>
- To ensure that your <interfacename>XAResourceRecovery</interfacename> instance is called during each sweep of the
- recovery manager, make sure that once method <methodname>hasMoreResources</methodname> returns
- <literal>false</literal> to indicate the end of work for the current scan, it returns <literal>true</literal> for
- the next recovery scan.
- </para>
- </note>
- </section>
-
- <section>
- <title>Alternative to XAResourceRecovery</title>
- <para>
- The iterator-based approach used by <interfacename>XAResourceRecovery</interfacename> requires implementations to
- manage state, which adds complexity. Starting with JBossTS 4.4, you can provide an implementation of public
- interface <interfacename>XAResourceRecoveryHelper</interfacename>:
- </para>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/XAResourceRecoveryHelper.java"
- xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
-
- <para>
- During each recovery sweep, method <methodname>getXAResources</methodname> is called and recovery is attempted on
- each element of the array. For the majority of resource managers, only one
- <interfacename>XAResource</interfacename> is needed in the array, because the <methodname>recover()</methodname>
- call on it can return multiple Xids.
- </para>
- <para>
- Unlike <interfacename>XAResourceRecovery</interfacename> instances, which are configured via the XML properties
- file and instantiated by JBossTS, instances of <interfacename>XAResourceRecoveryHelper</interfacename> are
- constructed by the application code and registered with JBossTS by calling
- <methodname>XARecoveryModule.addXAResourceRecoveryHelper</methodname>.
- </para>
- <para>
- Method <methodname>initialize</methodname> is not called by JBossTS in the current implementation. It is provided
- to allow for the addition of further configuration options in later releases.
- </para>
- <para>
- You can register <interfacename>XAResourceRecoveryHelper</interfacename> instances with the
- <methodname>XARecoverModule.removeXAResourceRecoveryHelper</methodname> method. After registration, they are no
- longer called by the recovery manager. Deregistration may block for a time if a recovery scan is in progress.
- </para>
- <para>
- The ability to dynamically add and remove instances of <interfacename>XAResourceRecoveryHelper</interfacename>
- while the system is running is an attractive option for environments where datasources may be deployed or
- undeployed, such as application servers. Take care with classloading behavior in such cases.
- </para>
- </section>
-
- <section>
- <title>Shipped XAResourceRecovery implementations</title>
- <para>
- Recovery of XA datasources can sometimes be implementation-dependent, requiring you to provide your own
- <interfacename>XAResourceRecovery</interfacename> instances. However, JBossTS ships with several useful
- implementations.
- </para>
- <para>
- These <interfacename>XAResourceRecovery</interfacename> instances are primarily intended for when running JBossTS
- outside of a container such as JBoss Application Server or another application server. This is because they rely upon
- <interfacename>XADataSources</interfacename> as the primary handle to drive recovery. If you are running JBossTS
- inside an application server or other container, consult the relevant integration documentation, to be sure to use
- the right recovery modules.
- </para>
-
- <section>
- <title>com.arjuna.ats.internal.jdbc.recovery.BasicXARecovery</title>
- <para>
- <interfacename>com.arjuna.ats.internal.jdbc.recovery.BasicXARecovery</interfacename> expects you to specify an
- XML property file upon creation. It uses this file to read the configuration properties for the datasource.
- </para>
- <example>
- <title>Example</title>
- <programlisting language="XML" role="XML"><xi:include href="extras/BasicXARecovery_Config_Example.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
- </section>
-
- <section>
- <title>com.arjuna.ats.internal.jdbc.recovery.JDBCXARecovery</title>
- <para>
- <interfacename>com.arjuna.ats.internal.jdbc.recovery.JDBCXARecovery</interfacename> should work on any
- datasource that is exposed via JNDI. It expects an XML property file to be specified upon creation, and uses the
- file to read the database JNDI name, user-name and password.
- </para>
- <example>
- <title>Example</title>
- <programlisting language="XML" role="XML"><xi:include href="extras/JDBCXARecovery_Config_Example.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
- </section>
- <section>
- <title>Initializing the Implementations</title>
- <para>
- Because these classes are <interfacename>XAResourceRecovery</interfacename> instances, they receive any
- necessary initialization information from the <methodname>initialise</methodname> operation. In the case of
- <interfacename>BasicXARecovery</interfacename> and <methodname>JDBCXARecovery</methodname>, the information is
- the location of a property file, and is specified in the JBossTS configuration file. For example:
- </para>
- <screen>
-com.arjuna.ats.jta.recovery.XAResourceRecoveryJDBC=com.arjuna.ats.internal.jdbc.recovery.JDBCXAResourceRecovery;thePropertyFile
- </screen>
- </section>
- </section>
-</chapter>
Modified: labs/jbosstm/trunk/docs/development_guide/en-US/Transactions.xml
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/Transactions.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/Transactions.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,18 +1,121 @@
<?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" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "JBossJTA_Development_Guide.ent">
+<!ENTITY % BOOK_ENTITIES SYSTEM "Development_Guide.ent">
%BOOK_ENTITIES;
]>
<chapter>
<title>Transactions</title>
<para>
- A transaction is a unit of work that encapsulates multiple database actions such that that either all the
+ A transaction is a unit of work that encapsulates multiple database actions such that that
+ either all the
encapsulated actions fail or all succeed.
</para>
<para>
Transactions ensure data integrity when an application interacts with multiple datasources.
</para>
<section>
+ <title>The Java Transaction API (JTA)</title>
+ <para>
+ The interfaces specified by the many transaction standards tend to be too low-level for most
+ application
+ programmers. Therefore, Sun Microsystems created the Java Transaction API (JTA),
+ which specifies higher-level
+ interfaces to assist in the development of distributed transactional
+ applications.
+ </para>
+ <para>
+ Note, these interfaces are still low-level. You still need to implement state management and
+ concurrency for
+ transactional applications. The interfaces are also optimized for applications
+ which require XA resource integration
+ capabilities, rather than the more general resources which
+ other transactional APIs allow.
+ </para>
+ <para>
+ With reference to JTA 1.1 (
+ <ulink url="http://www.oracle.com/technetwork/java/javaee/tech/jta-138684.html" />
+ ),
+ distributed transaction services typically involve a number of participants:
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>application server</entry>
+ <entry>
+ <para>
+ provides the infrastructure required to support the application run-time
+ environment which includes
+ transaction state management, such as an EJB server.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>transaction manager</entry>
+ <entry>
+ <para>
+ provides the services and management functions required to support transaction
+ demarcation, transactional
+ resource management, synchronization, and transaction
+ context propagation.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>resource manager</entry>
+ <entry>
+ <para>
+ Using a
+ <firstterm>resource adapter</firstterm>
+ , provides the application with access to resources. The
+ resource manager participates
+ in distributed transactions by implementing a transaction resource interface
+ used by
+ the transaction manager to communicate transaction association, transaction completion
+ and
+ recovery.
+ </para>
+ <para>
+ A resource adapter is used by an application server or client to connect to a
+ Resource Manager. JDBC
+ drivers which are used to connect to relational databases are
+ examples of Resource Adapters.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>communication resource manager</entry>
+ <entry>
+ <para>
+ supports transaction context propagation and access to the transaction service for incoming and
+ outgoing
+ requests.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>
+ From the point of view of the transaction manager, the actual implementation of the
+ transaction services does not
+ need to be exposed. You only need to define high-level interfaces
+ to allow transaction demarcation, resource
+ enlistment, synchronization and recovery process to be
+ driven from the users of the transaction services. The JTA is
+ a high-level application interface
+ that allows a transactional application to demarcate transaction boundaries, and
+ also contains a
+ mapping of the X/Open XA protocol.
+ </para>
+ <important>
+ <title>Compatibility</title>
+ <para>
+ the JTA support provided by &PRODUCT; is compliant with the 1.1 specification.
+ </para>
+ </important>
+ </section>
+ <section>
<title>Introducing the API</title>
<para>
The Java Transaction API consists of three elements:
@@ -30,120 +133,202 @@
</listitem>
<listitem>
<para>
- a standard Java mapping of the X/Open XA protocol intended for a transactional resource manager.
+ a standard Java mapping of the X/Open XA protocol intended for a transactional
+ resource manager.
</para>
</listitem>
</itemizedlist>
<para>
- All of the JTA classes and interfaces exist within the <package>javax.transaction</package> package, and the
- corresponding JBossJTA implementations within the <package>com.arjuna.ats.jta</package> package.
+ All of the JTA classes and interfaces exist within the
+ <package>javax.transaction</package>
+ package, and the
+ corresponding &PRODUCT; implementations within the
+ <package>com.arjuna.ats.jta</package>
+ package.
</para>
<para>
- Each Xid created by JBossTS needs a unique node identifier encoded within it, because JBossTS can only recover
- transactions and states that match a specified node identifier. The node identifier to use should be provided to
- JBossTS via the <varname>CoreEnvironmentBean.nodeIdentifier</varname> property. This value must be unique across
- your JBossTS instances. The identifier is alphanumeric and limited to 10 bytes in length. If you do not provide a
- value, then JBossTS generates one and reports the value via the logging infrastructure.
+ Each Xid created by JBossTS needs a unique node identifier encoded within it, because JBossTS
+ can only recover
+ transactions and states that match a specified node identifier. The node
+ identifier to use should be provided to
+ JBossTS via the
+ <varname>CoreEnvironmentBean.nodeIdentifier</varname>
+ property. This value must be unique across
+ your JBossTS instances. The identifier is
+ alphanumeric and limited to 10 bytes in length. If you do not provide a
+ value, then JBossTS
+ generates one and reports the value via the logging infrastructure.
</para>
</section>
-
+
<section id="UserTransaction_Definition">
<title>UserTransaction</title>
<para>
- The <interfacename>UserTransaction</interfacename> interface provides applications with the ability to control
- transaction boundaries. It provides methods <methodname>begin</methodname>, <methodname>commit</methodname>, and
- <methodname>rollback</methodname> to operate on top-level transactions.
+ The
+ <interfacename>UserTransaction</interfacename>
+ interface provides applications with the ability to control
+ transaction boundaries. It provides
+ methods
+ <methodname>begin</methodname>
+ ,
+ <methodname>commit</methodname>
+ , and
+ <methodname>rollback</methodname>
+ to operate on top-level transactions.
</para>
<para>
- Nested transactions are not supported, and method <methodname>begin</methodname> throws the exception
- <systemitem>NotSupportedException</systemitem> if the calling thread is already associated with a
- transaction. <interfacename>UserTransaction</interfacename> automatically associates newly created transactions
+ Nested transactions are not supported, and method
+ <methodname>begin</methodname>
+ throws the exception
+ <systemitem>NotSupportedException</systemitem>
+ if the calling thread is already associated with a
+ transaction.
+ <interfacename>UserTransaction</interfacename>
+ automatically associates newly created transactions
with the invoking thread.
</para>
<para>
- To obtain a <interfacename>UserTransaction</interfacename>, call the static method
- <methodname>com.arjuna.ats.jta.UserTransaction.userTransaction()</methodname>.
+ To obtain a
+ <interfacename>UserTransaction</interfacename>
+ , call the static method
+ <methodname>com.arjuna.ats.jta.UserTransaction.userTransaction()</methodname>
+ .
</para>
<procedure>
<title>Selecting the local JTA Implementation</title>
<step>
<para>
- Set property <varname>JTAEnvironmentBean.jtaTMImplementation</varname> to
- <literal>com.arjuna.ats.internal.jta.transaction.arjunacore.TransactionManagerImple</literal>.
+ Set property
+ <varname>JTAEnvironmentBean.jtaTMImplementation</varname>
+ to
+ <literal>com.arjuna.ats.internal.jta.transaction.arjunacore.TransactionManagerImple
+ </literal>
+ .
</para>
</step>
<step>
<para>
- Set property <varname>JTAEnvironmentBean.jtaUTImplementation</varname> to
- <literal>com.arjuna.ats.internal.jta.transaction.arjunacore.UserTransactionImple</literal>.
+ Set property
+ <varname>JTAEnvironmentBean.jtaUTImplementation</varname>
+ to
+ <literal>com.arjuna.ats.internal.jta.transaction.arjunacore.UserTransactionImple</literal>
+ .
</para>
</step>
</procedure>
</section>
-
+
<section>
<title>TransactionManager</title>
<para>
- The <interfacename>TransactionManager</interfacename> interface allows the application server to control
- transaction boundaries on behalf of the application being managed.
+ The
+ <interfacename>TransactionManager</interfacename>
+ interface allows the application server to control
+ transaction boundaries on behalf of the
+ application being managed.
</para>
<para>
- To obtain a <interfacename>TransactionManager</interfacename>, invoke the static method
- <methodname>com.arjuna.ats.jta.TransactionManager.transactionManager</methodname>.
+ To obtain a
+ <interfacename>TransactionManager</interfacename>
+ , invoke the static method
+ <methodname>com.arjuna.ats.jta.TransactionManager.transactionManager</methodname>
+ .
</para>
<para>
- The <interfacename>TransactionManager</interfacename> maintains the transaction context association with threads
- as part of its internal data structure. A thread’s transaction context may be <literal>null</literal> or it may
- refer to a specific global transaction. Multiple threads may be associated with the same global transaction. As
- noted in <xref linkend="UserTransaction_Definition" />, nested transactions are not supported.
+ The
+ <interfacename>TransactionManager</interfacename>
+ maintains the transaction context association with threads
+ as part of its internal data
+ structure. A thread’s transaction context may be
+ <literal>null</literal>
+ or it may
+ refer to a specific global transaction. Multiple threads may be associated with the
+ same global transaction. As
+ noted in
+ <xref linkend="UserTransaction_Definition" />
+ , nested transactions are not supported.
</para>
<para>
- Each transaction context is encapsulated by a Transaction object, which can be used to perform operations which
- are specific to the target transaction, regardless of the calling thread’s transaction context.
+ Each transaction context is encapsulated by a Transaction object, which can be used to
+ perform operations which
+ are specific to the target transaction, regardless of the calling
+ thread’s transaction context.
</para>
<table>
- <title><interfacename>TransactionManager</interfacename> Methods</title>
+ <title>
+ <interfacename>TransactionManager</interfacename>
+ Methods
+ </title>
<tgroup cols="2">
<tbody>
<row>
- <entry><para><methodname>begin</methodname></para></entry>
<entry>
<para>
- Starts a new top-level transaction and associates the transaction context with the calling thread. If
- the calling thread is already associated with a transaction, exception
- <systemitem>NotSupportedException</systemitem> is thrown.
+ <methodname>begin</methodname>
</para>
</entry>
+ <entry>
+ <para>
+ Starts a new top-level transaction and associates the transaction context with the
+ calling thread. If
+ the calling thread is already associated with a transaction,
+ exception
+ <systemitem>NotSupportedException</systemitem>
+ is thrown.
+ </para>
+ </entry>
</row>
<row>
- <entry><para><methodname>getTransaction</methodname></para></entry>
<entry>
<para>
- Returns the Transaction object representing the transaction context which is currently associated with
- the calling thread. You can use this object to perform various operations on the target transaction.
+ <methodname>getTransaction</methodname>
</para>
</entry>
+ <entry>
+ <para>
+ Returns the Transaction object representing the transaction context which is
+ currently associated with
+ the calling thread. You can use this object to perform
+ various operations on the target transaction.
+ </para>
+ </entry>
</row>
<row>
- <entry><para><methodname>commit</methodname></para></entry>
<entry>
<para>
- Completes the transaction currently associated with the calling thread. After it returns, the calling
- thread is associated with no transaction. If <methodname>commit</methodname> is called when the thread
- is not associated with any transaction context, an exception is thrown. In some implementations, the
- <methodname>commit</methodname> operation is restricted to the transaction originator only. If the
- calling thread is not allowed to commit the transaction, an exception is thrown. JBossTA does not
- currently impose any restriction on the ability of threads to terminate transactions.
+ <methodname>commit</methodname>
</para>
</entry>
+ <entry>
+ <para>
+ Completes the transaction currently associated with the calling thread. After it
+ returns, the calling
+ thread is associated with no transaction. If
+ <methodname>commit</methodname>
+ is called when the thread
+ is not associated with any transaction context, an
+ exception is thrown. In some implementations, the
+ <methodname>commit</methodname>
+ operation is restricted to the transaction originator only. If the
+ calling thread is
+ not allowed to commit the transaction, an exception is thrown. JBossTA does not
+ currently impose any restriction on the ability of threads to terminate
+ transactions.
+ </para>
+ </entry>
</row>
<row>
- <entry><para><methodname>rollback</methodname></para></entry>
<entry>
<para>
+ <methodname>rollback</methodname>
+ </para>
+ </entry>
+ <entry>
+ <para>
Rolls back the transaction associated with the current thread. After the
- <methodname>rollback</methodname> method completes, the thread is associated with no transaction.
+ <methodname>rollback</methodname>
+ method completes, the thread is associated with no transaction.
</para>
</entry>
</row>
@@ -151,47 +336,88 @@
</tgroup>
</table>
<para>
- In a multi-threaded environment, multiple threads may be active within the same transaction. If checked
- transaction semantics have been disabled, or the transaction times out, a transaction may terminated by a thread
- other than the one that created it. In this case, the creator usually needs to be notified. JBossTS notifies the
- creator during operations <methodname>commit</methodname> or <methodname>rollback</methodname> by throwing
- exception <systemitem>IllegalStateException</systemitem>.
+ In a multi-threaded environment, multiple threads may be active within the same transaction.
+ If checked
+ transaction semantics have been disabled, or the transaction times out, a
+ transaction may terminated by a thread
+ other than the one that created it. In this case, the
+ creator usually needs to be notified. JBossTS notifies the
+ creator during operations
+ <methodname>commit</methodname>
+ or
+ <methodname>rollback</methodname>
+ by throwing
+ exception
+ <systemitem>IllegalStateException</systemitem>
+ .
</para>
</section>
-
+
<section>
<title>Suspend and resuming a transaction</title>
<para>
- The JTA supports the concept of a thread temporarily suspending and resuming transactions in order to perform
- non-transactional work. Call the <methodname>suspend</methodname> method to temporarily suspend the current
- transaction that is associated with the calling thread. The thread then operates outside of the scope of the
- transaction. If the thread is not associated with any transaction, a <type>null</type> object reference is
- returned. Otherwise, a valid <type>Transaction</type> object is returned. Pass the <type>Transaction</type> object
- to the <methodname>resume</methodname> method to reinstate the transaction context.
+ The JTA supports the concept of a thread temporarily suspending and resuming transactions in
+ order to perform
+ non-transactional work. Call the
+ <methodname>suspend</methodname>
+ method to temporarily suspend the current
+ transaction that is associated with the calling
+ thread. The thread then operates outside of the scope of the
+ transaction. If the thread is not
+ associated with any transaction, a
+ <type>null</type>
+ object reference is
+ returned. Otherwise, a valid
+ <type>Transaction</type>
+ object is returned. Pass the
+ <type>Transaction</type>
+ object
+ to the
+ <methodname>resume</methodname>
+ method to reinstate the transaction context.
</para>
<para>
- The <methodname>resume</methodname> method associates the specified transaction context with the calling
- thread. If the transaction specified is not a valid transaction, , the thread is associated with no transaction.
- if <methodname>resume</methodname> is invoked when the calling thread is already associated with another
- transaction, the <systemitem>IllegalStateException</systemitem> exception is thrown.
+ The
+ <methodname>resume</methodname>
+ method associates the specified transaction context with the calling
+ thread. If the transaction
+ specified is not a valid transaction, , the thread is associated with no transaction.
+ if
+ <methodname>resume</methodname>
+ is invoked when the calling thread is already associated with another
+ transaction, the
+ <systemitem>IllegalStateException</systemitem>
+ exception is thrown.
</para>
<example>
- <title>Using the <methodname>suspend</methodname> method</title>
- <programlisting language="Java" role="JAVA"> <xi:include href="extras/using_suspend_method.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /> </programlisting>
+ <title>
+ Using the
+ <methodname>suspend</methodname>
+ method
+ </title>
+ <programlisting language="Java" role="JAVA"> <xi:include
+ href="extras/using_suspend_method.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /> </programlisting>
</example>
<note>
<para>
- JBossJTA allows a suspended transaction to be resumed by a different thread. This feature is not required by
+ &PRODUCT; allows a suspended transaction to be resumed by a different thread. This
+ feature is not required by
JTA, but is an important feature.
</para>
</note>
<para>
- When a transaction is suspended, the application server must ensure that the resources in use by the application
- are no longer registered with the suspended transaction. When a resource is de-listed this triggers the
- Transaction Manager to inform the resource manager to disassociate the transaction from the specified resource
- object. When the application’s transaction context is resumed, the application server must ensure that the
- resources in use by the application are again enlisted with the transaction. Enlisting a resource as a result of
- resuming a transaction triggers the Transaction Manager to inform the resource manager to re-associate the
+ When a transaction is suspended, the application server must ensure that the resources in
+ use by the application
+ are no longer registered with the suspended transaction. When a resource
+ is de-listed this triggers the
+ Transaction Manager to inform the resource manager to
+ disassociate the transaction from the specified resource
+ object. When the application’s
+ transaction context is resumed, the application server must ensure that the
+ resources in use by
+ the application are again enlisted with the transaction. Enlisting a resource as a result of
+ resuming a transaction triggers the Transaction Manager to inform the resource manager to
+ re-associate the
resource object with the resumed transaction.
</para>
</section>
@@ -199,12 +425,20 @@
<section>
<title>The Transaction interface</title>
<para>
- The <interfacename>Transaction</interfacename> interface allows you to perform operations on the transaction
- associated with the target object. Every top-level transaction is associated with one <type>Transaction</type>
+ The
+ <interfacename>Transaction</interfacename>
+ interface allows you to perform operations on the transaction
+ associated with the target
+ object. Every top-level transaction is associated with one
+ <type>Transaction</type>
object when the transaction is created.
</para>
<itemizedlist>
- <title>Uses of the <type>Transaction</type> object</title>
+ <title>
+ Uses of the
+ <type>Transaction</type>
+ object
+ </title>
<listitem>
<para>
enlist the transactional resources in use by the application.
@@ -227,68 +461,126 @@
</listitem>
</itemizedlist>
<para>
- The <methodname>commit</methodname> and <methodname>rollback</methodname> methods allow the target object to be
- committed or rolled back. The calling thread does not need to have the same transaction associated with the
- thread. If the calling thread is not allowed to commit the transaction, the transaction manager throws an
- exception. At present JBossJTA does not impose restrictions on threads terminating transactions.
+ The
+ <methodname>commit</methodname>
+ and
+ <methodname>rollback</methodname>
+ methods allow the target object to be
+ committed or rolled back. The calling thread does not
+ need to have the same transaction associated with the
+ thread. If the calling thread is not
+ allowed to commit the transaction, the transaction manager throws an
+ exception. At present
+ &PRODUCT; does not impose restrictions on threads terminating transactions.
</para>
<para>
- The JTA standard does not provide a means to obtain the transaction identifier. However, JBossJTA provides several
- ways to view the transaction identifier. Call method <methodname>toString</methodname> to print full information
- about the transaction, including the identifier. Alternatively you can cast the
- <type>javax.transaction.Transaction</type> instance to a <type>com.arjuna.ats.jta.transaction.Transaction</type>,
- then call either method <methodname>get_uid</methodname>, which returns an ArjunaCore <type>Uid</type>
- representation, or <methodname>getTxId</methodname>, which returns an <type>Xid</type> for the global identifier,
+ The JTA standard does not provide a means to obtain the transaction identifier. However,
+ &PRODUCT; provides several
+ ways to view the transaction identifier. Call method
+ <methodname>toString</methodname>
+ to print full information
+ about the transaction, including the identifier. Alternatively you
+ can cast the
+ <type>javax.transaction.Transaction</type>
+ instance to a
+ <type>com.arjuna.ats.jta.transaction.Transaction</type>
+ ,
+ then call either method
+ <methodname>get_uid</methodname>
+ , which returns an ArjunaCore
+ <type>Uid</type>
+ representation, or
+ <methodname>getTxId</methodname>
+ , which returns an
+ <type>Xid</type>
+ for the global identifier,
i.e., no branch qualifier.
</para>
</section>
-
+
<section>
<title>Resource enlistment</title>
<para>
- Typically, an application server manages transactional resources, such as database connections, in conjunction
- with some resource adapter and optionally with connection pooling optimization. For an external transaction
- manager to coordinate transactional work performed by the resource managers, the application server must enlist
- and de-list the resources used in the transaction. These resources, called <firstterm>participants</firstterm>,
- are enlisted with the transaction so that they can be informed when the transaction terminates, by being driven
+ Typically, an application server manages transactional resources, such as database
+ connections, in conjunction
+ with some resource adapter and optionally with connection pooling
+ optimization. For an external transaction
+ manager to coordinate transactional work performed by
+ the resource managers, the application server must enlist
+ and de-list the resources used in the
+ transaction. These resources, called
+ <firstterm>participants</firstterm>
+ ,
+ are enlisted with the transaction so that they can be informed when the transaction
+ terminates, by being driven
through the two-phase commit protocol.
</para>
<para>
- As stated previously, the JTA is much more closely integrated with the XA concept of resources than the arbitrary
- objects. For each resource the application is using, the application server invokes the
- <methodname>enlistResource</methodname> method with an <type>XAResource</type> object which identifies the
- resource in use.<!-- See for details on how the implementation of the XAResource can affect recovery in the event
- of a failure.-->
+ As stated previously, the JTA is much more closely integrated with the XA concept of resources
+ than the arbitrary
+ objects. For each resource the application is using, the application server
+ invokes the
+ <methodname>enlistResource</methodname>
+ method with an
+ <type>XAResource</type>
+ object which identifies the
+ resource in use.<!-- See for details on how the implementation of the
+ XAResource can affect recovery in the event of a failure. -->
</para>
<para>
- The enlistment request causes the transaction manager to inform the resource manager to start associating the
- transaction with the work performed through the corresponding resource. The transaction manager passes the
- appropriate flag in its <methodname>XAResource.start</methodname> method call to the resource manager.
+ The enlistment request causes the transaction manager to inform the resource manager to start
+ associating the
+ transaction with the work performed through the corresponding resource. The
+ transaction manager passes the
+ appropriate flag in its
+ <methodname>XAResource.start</methodname>
+ method call to the resource manager.
</para>
<para>
- The <methodname>delistResource</methodname> method disassociates the specified resource from the transaction
- context in the target object. The application server invokes the method with the two parameters: the
- <type>XAResource</type> object that represents the resource, and a flag to indicate whether the operation is due
- to the transaction being suspended (<literal>TMSUSPEND</literal>), a portion of the work has failed
- (<literal>TMFAIL</literal>), or a normal resource release by the application (<literal>TMSUCCESS</literal>).
+ The
+ <methodname>delistResource</methodname>
+ method disassociates the specified resource from the transaction
+ context in the target object.
+ The application server invokes the method with the two parameters: the
+ <type>XAResource</type>
+ object that represents the resource, and a flag to indicate whether the operation is due
+ to the
+ transaction being suspended (
+ <literal>TMSUSPEND</literal>
+ ), a portion of the work has failed
+ (
+ <literal>TMFAIL</literal>
+ ), or a normal resource release by the application (
+ <literal>TMSUCCESS</literal>
+ ).
</para>
<para>
- The de-list request causes the transaction manager to inform the resource manager to end the association of the
- transaction with the target <type>XAResource</type>. The flag value allows the application server to indicate
- whether it intends to come back to the same resource whereby the resource states must be kept intact. The
- transaction manager passes the appropriate flag value in its <methodname>XAResource.end</methodname> method call
+ The de-list request causes the transaction manager to inform the resource manager to end the
+ association of the
+ transaction with the target
+ <type>XAResource</type>
+ . The flag value allows the application server to indicate
+ whether it intends to come back to
+ the same resource whereby the resource states must be kept intact. The
+ transaction manager
+ passes the appropriate flag value in its
+ <methodname>XAResource.end</methodname>
+ method call
to the underlying resource manager.
</para>
</section>
-
+
<section>
<title>Transaction synchronization</title>
<para>
- Transaction synchronization allows the application server to be notified before and after the transaction
- completes. For each transaction started, the application server may optionally register a
- <type>Synchronization</type> call-back object to be invoked by the transaction manager, which will be one of the
+ Transaction synchronization allows the application server to be notified before and after the
+ transaction
+ completes. For each transaction started, the application server may optionally
+ register a
+ <type>Synchronization</type>
+ call-back object to be invoked by the transaction manager, which will be one of the
following:
</para>
<informaltable>
@@ -296,24 +588,33 @@
<tbody>
<row>
<entry>
- <para><methodname>beforeCompletion</methodname></para>
+ <para>
+ <methodname>beforeCompletion</methodname>
+ </para>
</entry>
<entry>
<para>
- Called before the start of the two-phase transaction complete process. This call is executed in the same
- transaction context of the caller who initiates the <methodname>TransactionManager.commit</methodname>
- or the call is executed with no transaction context if <methodname>Transaction.commit</methodname> is
+ Called before the start of the two-phase transaction complete process. This call is
+ executed in the same
+ transaction context of the caller who initiates the
+ <methodname>TransactionManager.commit</methodname>
+ or the call is executed with no transaction context if
+ <methodname>Transaction.commit</methodname>
+ is
used.
</para>
</entry>
</row>
<row>
<entry>
- <para><methodname>afterCompletion</methodname></para>
+ <para>
+ <methodname>afterCompletion</methodname>
+ </para>
</entry>
<entry>
<para>
- Called after the transaction completes. The status of the transaction is supplied in the parameter. This
+ Called after the transaction completes. The status of the transaction is
+ supplied in the parameter. This
method is executed without a transaction context.
</para>
</entry>
@@ -322,35 +623,53 @@
</tgroup>
</informaltable>
</section>
-
+
<section>
<title>Transaction equality</title>
<para>
- The transaction manager implements the <type>Transaction</type> object’s <methodname>equals</methodname> method to
- allow comparison between the target object and another <type>Transaction</type> object. The
- <methodname>equals</methodname> method returns <literal>true</literal> if the target object and the parameter
+ The transaction manager implements the
+ <type>Transaction</type>
+ object’s
+ <methodname>equals</methodname>
+ method to
+ allow comparison between the target object and another
+ <type>Transaction</type>
+ object. The
+ <methodname>equals</methodname>
+ method returns
+ <literal>true</literal>
+ if the target object and the parameter
object both refer to the same global transaction.
</para>
<example>
- <title>Method <methodname>equals</methodname></title>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/Transaction_Equality.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ <title>
+ Method
+ <methodname>equals</methodname>
+ </title>
+ <programlisting language="Java" role="JAVA"><xi:include
+ href="extras/Transaction_Equality.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
</example>
</section>
-
+
<section>
<title>TransactionSynchronizationRegistry</title>
<para>
- The <interfacename>javax.transaction.TransactionSynchronizationRegistry</interfacename> interface, added to the
- JTA API in version 1.1, provides for registering Synchronizations with special ordering behavior, and for storing
- key-value pairs in a per-transaction Map. Full details are available from the JTA 1.1 API specification and
- javadoc. Here we focus on implementation specific behavior.
+ The
+ <interfacename>javax.transaction.TransactionSynchronizationRegistry</interfacename>
+ interface, added to the
+ JTA API in version 1.1, provides for registering Synchronizations with
+ special ordering behavior, and for storing
+ key-value pairs in a per-transaction Map. Full
+ details are available from the JTA 1.1 API specification and
+ javadoc. Here we focus on
+ implementation specific behavior.
</para>
<example>
<title>Accessing the TransactionSynchronizationRegistry in standalone environments</title>
<programlisting language="Java" role="JAVA"><xi:include
- href="extras/TransactionSynchronizationRegistry_standalone.java" xmlns:xi="http://www.w3.org/2001/XInclude"
- parse="text" /></programlisting>
+ href="extras/TransactionSynchronizationRegistry_standalone.java" xmlns:xi="http://www.w3.org/2001/XInclude"
+ parse="text" /></programlisting>
<para>
This is a stateless object and hence is cheap to instantiate.
</para>
@@ -359,23 +678,51 @@
<title>Accessing the TransactionSynchronizationRegistry via JNDI</title>
<para>
In application server environments, the standard JNDI name binding is
- <literal>java:comp/TransactionSynchronizationRegistry</literal>.
+ <literal>java:comp/TransactionSynchronizationRegistry</literal>
+ .
</para>
</formalpara>
<para>
- Ordering of interposed Synchronizations is relative to other local Synchronizations only. In cases where the
- transaction is distributed over multiple JVMs, global ordering is not guaranteed.
+ Ordering of interposed Synchronizations is relative to other local Synchronizations only.
+ In cases where the
+ transaction is distributed over multiple JVMs, global ordering is not
+ guaranteed.
</para>
<para>
- The per-transaction data storage provided by the <interfacename>TransactionSynchronizationRegistry</interfacename>
- methods <methodname>getResource</methodname> and <methodname>putResource</methodname> are non-persistent and thus
- not available in <interfacename>Transactions</interfacename> during crash recovery. When running integrated with
- an application server or other container, this storage may be used for system purposes. To avoid collisions, use
- an application-specific prefix on map keys, such as <command>put(“myapp_”+key, value)</command>. The behavior of
- the <type>Map</type> on <type>Thread</type>s that have status <literal>NO_TRANSACTION</literal> or where the
- transaction they are associated with has been rolled back by another <type>Thread</type>, such as in the case of a
- timeout, is undefined. A <type>Transaction</type> can be associated with multiple <type>Thread</type>s. For such
- cases the <type>Map</type> is synchronized to provide thread safety.
+ The per-transaction data storage provided by the
+ <interfacename>TransactionSynchronizationRegistry</interfacename>
+ methods
+ <methodname>getResource</methodname>
+ and
+ <methodname>putResource</methodname>
+ are non-persistent and thus
+ not available in
+ <interfacename>Transactions</interfacename>
+ during crash recovery. When running integrated with
+ an application server or other container,
+ this storage may be used for system purposes. To avoid collisions, use
+ an application-specific
+ prefix on map keys, such as
+ <command>put(“myapp_”+key, value)</command>
+ . The behavior of
+ the
+ <type>Map</type>
+ on
+ <type>Thread</type>
+ s that have status
+ <literal>NO_TRANSACTION</literal>
+ or where the
+ transaction they are associated with has been rolled back by another
+ <type>Thread</type>
+ , such as in the case of a
+ timeout, is undefined. A
+ <type>Transaction</type>
+ can be associated with multiple
+ <type>Thread</type>
+ s. For such
+ cases the
+ <type>Map</type>
+ is synchronized to provide thread safety.
</para>
</section>
</chapter>
Deleted: labs/jbosstm/trunk/docs/development_guide/en-US/Using_JBossTA_In_Application_Servers.xml
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/Using_JBossTA_In_Application_Servers.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/Using_JBossTA_In_Application_Servers.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,86 +0,0 @@
-<?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" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "JBossJTA_Development_Guide.ent">
-%BOOK_ENTITIES;
-]>
-<chapter>
- <title>Using JBossJTA in application servers</title>
- <para>
- JBoss Application Server is discussed here. Refer to the documentation for your application server for differences.
- </para>
- <section>
- <title>Configuration</title>
- <para>
- When JBossJTA runs embedded in JBoss Application Server, the transaction system is configured primarily through the
- <filename>transaction-jboss-beans.xml</filename> deployment descriptor, which overrides properties read from the
- default properties file embedded in the .<filename>jar</filename> file.
- </para>
- <table>
- <title>Common configuration attributes</title>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>CoordinatorEnvironmentBean.defaultTimeout</entry>
- <entry>
- <para>
- The default transaction timeout to be used for new transactions. Specified as an integer in seconds.
- </para>
- </entry>
- </row>
- <row>
- <entry>CoordinatorEnvironmentBean.enableStatistics</entry>
- <entry>
- <para>
- This determines whether or not the transaction service should gather statistical information. This
- information can then be viewed using the TransactionStatistics MBean. Specified as a Boolean. The
- default is to not gather this information.
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>
- See the <filename>transaction-jboss-beans.xml</filename> file and the JBoss Application Server administration and
- configuration guide for further information.
- </para>
- </section>
-
- <section>
- <title>Logging</title>
- <para>
- To make JBossTS logging semantically consistent with JBoss Application Server, the
- <interfacename>TransactionManagerService</interfacename> modifies the level of some log messages, by overriding
- the value of the <varname>LoggingEnvironmentBean.loggingFactory</varname> property in the
- <filename>jbossts-properties.xml</filename> file. Therefore, the value of this property has no effect on the
- logging behavior when running embedded in JBoss Application Server. By forcing use of the <systemitem>log4j_releveler</systemitem>
- logger, the <interfacename>TransactionManagerService</interfacename> changes the level of all
- <literal>INFO</literal> level messages in the transaction code to <literal>DEBUG</literal>. Therefore, these
- messages do not appear in log files if the filter level is <literal>INFO</literal>. All other log messages behave
- as normal.
- </para>
- </section>
-
- <section>
- <title>The services</title>
- <para>
- The <interfacename>TransactionManager</interfacename> bean provides transaction management services to other
- components in JBoss Application Server. There are two different version of this bean and they requires different configuration. Take
- care to select the <filename>transaction-jboss-beans.xml</filename> suitable for your needs (local JTA or JTS).
- </para>
- </section>
-
- <section>
- <title>Ensuring transactional context is propagated to the server</title>
- <para>
- You can coordinate transactions from a coordinator which is not located within the JBoss server
- , such as when using transactions created by an external OTS server. To ensure the transaction context is propagated via
- JRMP invocations to the server, the transaction propagation context factory needs to be explicitly set for the
- JRMP invoker proxy. This is done as follows:
- </para>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/jrmp_invoker_proxy.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </section>
-
-
-</chapter>
-
Added: labs/jbosstm/trunk/docs/development_guide/en-US/extras/CheckedAction.java
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/extras/CheckedAction.java (rev 0)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/extras/CheckedAction.java 2011-04-14 13:12:59 UTC (rev 36934)
@@ -0,0 +1,5 @@
+public class CheckedAction
+{
+ public synchronized void check (boolean isCommit, Uid actUid,
+ BasicList list);
+};
\ No newline at end of file
Added: labs/jbosstm/trunk/docs/development_guide/en-US/extras/EnvironmentBeans.xml
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/extras/EnvironmentBeans.xml (rev 0)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/extras/EnvironmentBeans.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -0,0 +1,4 @@
+<entry key="RecoveryEnvironmentBean.recoveryModuleClassNames">
+ com.arjuna.ats.internal.arjuna.recovery.AtomicActionRecoveryModule
+ com.arjuna.ats.internal.txoj.recovery.TORecoveryModule
+</entry>
\ No newline at end of file
Added: labs/jbosstm/trunk/docs/development_guide/en-US/extras/LastResourceRecord.java
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/extras/LastResourceRecord.java (rev 0)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/extras/LastResourceRecord.java 2011-04-14 13:12:59 UTC (rev 36934)
@@ -0,0 +1,14 @@
+try
+ {
+ boolean success = false;
+ AtomicAction A = new AtomicAction();
+ OnePhase opRes = new OnePhase(); // used OnePhase interface
+
+ System.err.println("Starting top-level action.");
+
+ A.begin();
+ A.add(new LastResourceRecord(opRes));
+ A.add(new ShutdownRecord(ShutdownRecord.FAIL_IN_PREPARE));
+
+ A.commit();
+ }
\ No newline at end of file
Added: labs/jbosstm/trunk/docs/development_guide/en-US/extras/TxStats.java
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/extras/TxStats.java (rev 0)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/extras/TxStats.java 2011-04-14 13:12:59 UTC (rev 36934)
@@ -0,0 +1,61 @@
+public class TxStats
+{
+ /**
+ * @return the number of transactions (top-level and nested) created so far.
+ */
+
+ public static int numberOfTransactions();
+
+ /**
+ * @return the number of nested (sub) transactions created so far.
+ *
+
+ public static int numberOfNestedTransactions();
+
+ /**
+ * @return the number of transactions which have terminated with heuristic
+ * outcomes.
+ */
+
+ public static int numberOfHeuristics();
+ /**
+ * @return the number of committed transactions.
+ */
+
+ public static int numberOfCommittedTransactions();
+
+ /**
+ * @return the total number of transactions which have rolled back.
+ */
+
+ public static int numberOfAbortedTransactions();
+
+ /**
+ * @return total number of inflight (active) transactions.
+ */
+
+ public static int numberOfInflightTransactions ();
+
+ /**
+ * @return total number of transactions rolled back due to timeout.
+ */
+
+ public static int numberOfTimedOutTransactions ();
+ /**
+ * @return the number of transactions rolled back by the application.
+ */
+
+ public static int numberOfApplicationRollbacks ();
+
+ /**
+ * @return number of transactions rolled back by participants.
+ */
+
+ public static int numberOfResourceRollbacks ();
+
+ /**
+ * Print the current information.
+ */
+
+ public static void printStatus(java.io.PrintWriter pw);
+}
\ No newline at end of file
Added: labs/jbosstm/trunk/docs/development_guide/en-US/extras/abstract_record_subclass.java
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/extras/abstract_record_subclass.java (rev 0)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/extras/abstract_record_subclass.java 2011-04-14 13:12:59 UTC (rev 36934)
@@ -0,0 +1,53 @@
+public class SimpleRecord extends AbstractRecord
+{
+ private int _value = 0;
+
+ .....
+
+ public void increase()
+ {
+ _value++;
+ }
+
+ public int get()
+ {
+ return _value;
+ }
+
+ public String type()
+ {
+ return “/StateManager/AbstractRecord/SimpleRecord”;
+ }
+
+ public boolean restore_state(InputObjectState os, int i)
+ {
+ boolean returnValue = true;
+
+ try
+ {
+ _value = os.unpackInt();
+ }
+ catch (java.io.IOException e)
+ {
+ returnValue = false;
+ }
+
+ return returnValue;
+ }
+
+ public boolean save_state(OutputObjectState os, int i)
+ {
+ boolean returnValue = true;
+
+ try
+ {
+ os.packInt(_value);
+ }
+ catch (java.io.IOException e)
+ {
+ returnValue = false;
+ }
+
+ return returnValue;
+ }
+}
\ No newline at end of file
Added: labs/jbosstm/trunk/docs/development_guide/en-US/extras/array_get_method.java
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/extras/array_get_method.java (rev 0)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/extras/array_get_method.java 2011-04-14 13:12:59 UTC (rev 36934)
@@ -0,0 +1,19 @@
+public int get (int index) // assume -1 means error
+{
+ AtomicAction A = new AtomicAction();
+
+ A.begin();
+
+ // We only need a READ lock as the state is unchanged.
+
+ if (setlock(new Lock(LockMode.READ), 0) == LockResult.GRANTED)
+ {
+ A.commit(true);
+
+ return elements[index];
+ }
+ else
+ A.rollback();
+
+ return -1;
+}
\ No newline at end of file
Added: labs/jbosstm/trunk/docs/development_guide/en-US/extras/array_set_method.java
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/extras/array_set_method.java (rev 0)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/extras/array_set_method.java 2011-04-14 13:12:59 UTC (rev 36934)
@@ -0,0 +1,22 @@
+public boolean set (int index, int value)
+{
+ boolean result = false;
+ AtomicAction A = new AtomicAction();
+
+ A.begin();
+
+ // We need to set a WRITE lock as we want to modify the state.
+
+ if (setlock(new Lock(LockMode.WRITE), 0) == LockResult.GRANTED)
+ {
+ elements[index] = value;
+ if ((value > 0) &&(index > highestIndex
+ highestIndex = index;
+ A.commit(true);
+ result = true;
+ }
+ else
+ A.rollback();
+
+ return result;
+}
\ No newline at end of file
Added: labs/jbosstm/trunk/docs/development_guide/en-US/extras/defaultTimeout.java
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/extras/defaultTimeout.java (rev 0)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/extras/defaultTimeout.java 2011-04-14 13:12:59 UTC (rev 36934)
@@ -0,0 +1,2 @@
+int defaultTimeout =
+ arjPropertyManager.getCoordinatorEnvironmentBean().getDefaultTimeout();
Added: labs/jbosstm/trunk/docs/development_guide/en-US/extras/osv-plugin-ant.xml
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/extras/osv-plugin-ant.xml (rev 0)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/extras/osv-plugin-ant.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -0,0 +1,8 @@
+<jar jarfile="osbv-simplerecord.jar">
+ <fileset dir="build" includes="*.class”/>
+ <manifest>
+ <section name="arjuna-tools-objectstorebrowser">
+ <attribute name="plugin-classname-1" value=" SimpleRecordOSVPlugin "/>
+ </section>
+ </manifest>
+</jar>
\ No newline at end of file
Added: labs/jbosstm/trunk/docs/development_guide/en-US/extras/osv_plugin.java
===================================================================
--- labs/jbosstm/trunk/docs/development_guide/en-US/extras/osv_plugin.java (rev 0)
+++ labs/jbosstm/trunk/docs/development_guide/en-US/extras/osv_plugin.java 2011-04-14 13:12:59 UTC (rev 36934)
@@ -0,0 +1,55 @@
+public class SimpleRecordOSVPlugin implements StateViewerInterface
+{
+ /**
+ * A uid node of the type this viewer is registered against has been expanded.
+ * @param os
+ * @param type
+ * @param manipulator
+ * @param node
+ * @throws ObjectStoreException
+ */
+ public void uidNodeExpanded(ObjectStore os,
+ String type,
+ ObjectStoreBrowserTreeManipulationInterface
+ manipulator,
+ UidNode node,
+ StatePanel infoPanel)
+ throws ObjectStoreException
+ {
+ // Do nothing
+ }
+
+ /**
+ * An entry has been selected of the type this viewer is registered against.
+ *
+ * @param os
+ * @param type
+ * @param uid
+ * @param entry
+ * @param statePanel
+ * @throws ObjectStoreException
+ */
+ public void entrySelected(ObjectStore os,
+ String type,
+ Uid uid,
+ ObjectStoreViewEntry entry,
+ StatePanel statePanel)
+ throws ObjectStoreException
+ {
+ SimpleRecord rec = new SimpleRecord();
+
+ if ( rec.restore_state( os.read_committed(uid, type), ObjectType.ANDPERSISTENT ) )
+ {
+ statePanel.setData( “Value”, rec.getValue() );
+ }
+ }
+
+ /**
+ * Get the type this state viewer is intended to be registered against.
+ * @return
+ */
+ public String getType()
+ {
+ return “/StateManager/AbstractRecord/SimpleRecord”;
+ }
+}
\ No newline at end of file
Added: labs/jbosstm/trunk/docs/development_guide/en-US/images/independent_top_level_action.png
===================================================================
(Binary files differ)
Property changes on: labs/jbosstm/trunk/docs/development_guide/en-US/images/independent_top_level_action.png
___________________________________________________________________
Added: svn:mime-type
+ application/octet-stream
Modified: labs/jbosstm/trunk/docs/failure_recovery_guide/en-US/About_This_Guide.xml
===================================================================
--- labs/jbosstm/trunk/docs/failure_recovery_guide/en-US/About_This_Guide.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/docs/failure_recovery_guide/en-US/About_This_Guide.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,28 +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" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "Failure_Recovery_Guide.ent">
-<!ENTITY PRODUCT "JBoss Transactions">
-<!ENTITY BOOKID "Failure_Recovery_Guide">
-<!ENTITY VERSION "4.15">
-<!ENTITY YEAR "2011">
-<!ENTITY HOLDER "JBoss.org">
-<!ENTITY APPSERVER "JBoss Application Server">
-<!-- <!ENTITY APPSERVER "Enterprise Application Platform Server"> -->]>
+%BOOK_ENTITIES;
+]>
<chapter>
- <title>About This Guide</title>
- <para>
+ <title>About This Guide</title>
+ <para>
The Failure Recovery Guide contains information on how to use JBossTS.
</para>
- <section>
- <title>Audience</title>
- <para>
- This guide is most relevant to engineers who are responsible for administering JBoss Transactions installations.
+ <section>
+ <title>Audience</title>
+ <para>
+ This guide is most relevant to engineers who are responsible for administering JBoss
+ Transactions installations.
</para>
- </section>
- <section>
- <title>Prerequisites</title>
- <para>
+ </section>
+ <section>
+ <title>Prerequisites</title>
+ <para>
You should have installed JBossTS.
</para>
- </section>
+ </section>
</chapter>
Modified: labs/jbosstm/trunk/docs/release_notes/en-US/Release_Notes.ent
===================================================================
--- labs/jbosstm/trunk/docs/release_notes/en-US/Release_Notes.ent 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/docs/release_notes/en-US/Release_Notes.ent 2011-04-14 13:12:59 UTC (rev 36934)
@@ -1,4 +1,4 @@
<!ENTITY PRODUCT "JBoss Transaction Manager">
<!ENTITY BOOKID "4.14_JBoss_Transactions_Release_Notes">
-<!ENTITY YEAR "2010">
+<!ENTITY YEAR "2011">
<!ENTITY HOLDER "JBoss.org">
Modified: labs/jbosstm/trunk/docs/release_notes/en-US/Release_Notes.xml
===================================================================
--- labs/jbosstm/trunk/docs/release_notes/en-US/Release_Notes.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/docs/release_notes/en-US/Release_Notes.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -266,6 +266,6 @@
</section>
<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <index />
+ <!-- <index /> -->
</article>
Modified: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Transactions_Overview_Guide.xml
===================================================================
--- labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Transactions_Overview_Guide.xml 2011-04-14 10:51:26 UTC (rev 36933)
+++ labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Transactions_Overview_Guide.xml 2011-04-14 13:12:59 UTC (rev 36934)
@@ -8,6 +8,6 @@
<xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Transactions_Overview.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <index />
+ <!-- <index /> -->
</book>
More information about the jboss-svn-commits
mailing list