[jboss-svn-commits] JBL Code SVN: r35872 - in labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US: extras and 1 other directory.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Fri Nov 5 03:03:18 EDT 2010
Author: misty at redhat.com
Date: 2010-11-05 03:03:15 -0400 (Fri, 05 Nov 2010)
New Revision: 35872
Added:
labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/
labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/TransactionSynchronizationRegistry_standalone.java
labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/Transaction_Equality.java
labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/resource_sharing_example.java
labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/using_suspend_method.java
Modified:
labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/The_Resource_Manager.xml
labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/Transactions.xml
Log:
Conversion continues
Modified: labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/The_Resource_Manager.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/The_Resource_Manager.xml 2010-11-04 18:44:01 UTC (rev 35871)
+++ labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/The_Resource_Manager.xml 2010-11-05 07:03:15 UTC (rev 35872)
@@ -4,6 +4,391 @@
%BOOK_ENTITIES;
]>
<chapter>
- <title></title>
+ <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 adaptor 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 behaviour 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 comform 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 subsdequent
+ 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 adaptor 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" />
+ </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
+ kames 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>
-
Modified: labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/Transactions.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/Transactions.xml 2010-11-04 18:44:01 UTC (rev 35871)
+++ labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/Transactions.xml 2010-11-05 07:03:15 UTC (rev 35872)
@@ -5,5 +5,370 @@
]>
<chapter>
<title></title>
+
+ <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>
-
Added: labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/TransactionSynchronizationRegistry_standalone.java
===================================================================
--- labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/TransactionSynchronizationRegistry_standalone.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/TransactionSynchronizationRegistry_standalone.java 2010-11-05 07:03:15 UTC (rev 35872)
@@ -0,0 +1 @@
+javax.transaction.TransactionSynchronizationRegistry tsr = new com.arjuna.ats.internal.jta.transaction.arjunacore.TransactionSynchronizationRegistryImple();
Added: labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/Transaction_Equality.java
===================================================================
--- labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/Transaction_Equality.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/Transaction_Equality.java 2010-11-05 07:03:15 UTC (rev 35872)
@@ -0,0 +1,5 @@
+Transaction txObj = TransactionManager.getTransaction();
+Transaction someOtherTxObj = ..
+..
+
+boolean isSame = txObj.equals(someOtherTxObj);
Added: labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/resource_sharing_example.java
===================================================================
--- labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/resource_sharing_example.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/resource_sharing_example.java 2010-11-05 07:03:15 UTC (rev 35872)
@@ -0,0 +1,14 @@
+XAResource xares = r1.getXAResource();
+
+xares.start(xid1); // associate xid1 to the connection
+
+..
+xares.end(xid1); // disassociate xid1 to the connection
+..
+xares.start(xid2); // associate xid2 to the connection
+..
+// While the connection is associated with xid2,
+// the TM starts the commit process for xid1
+status = xares.prepare(xid1);
+..
+xares.commit(xid1, false);
Added: labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/using_suspend_method.java
===================================================================
--- labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/using_suspend_method.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTA/docs/ArjunaTA_Development_Guide/en-US/extras/using_suspend_method.java 2010-11-05 07:03:15 UTC (rev 35872)
@@ -0,0 +1,3 @@
+Transaction tobj = TransactionManager.suspend();
+..
+TransactionManager.resume(tobj);
\ No newline at end of file
More information about the jboss-svn-commits
mailing list