[jboss-svn-commits] JBL Code SVN: r32027 - in labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US: images and 1 other directory.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Wed Mar 10 18:50:25 EST 2010
Author: misty at redhat.com
Date: 2010-03-10 18:50:24 -0500 (Wed, 10 Mar 2010)
New Revision: 32027
Added:
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/OTS_Introduction.xml
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-subtransaction_creation_indirect.png
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-top_level_transaction_creation_indirect.png
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure_OTS_architecture.png
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure_control-relationship.png
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure_thread-and-context-relationships.png
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure_top-level-transaction-creation.png
Modified:
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JBossTS_basics.xml
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JTS_Programmers_Guide.xml
Log:
Almost finished with OTS Introduction chapter
Modified: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JBossTS_basics.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JBossTS_basics.xml 2010-03-10 20:23:01 UTC (rev 32026)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JBossTS_basics.xml 2010-03-10 23:50:24 UTC (rev 32027)
@@ -2,313 +2,314 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<chapter id="chap-JTS_Programmers_Guide-JTS_Basics">
- <title>JBoss Transaction Service Basics</title>
- <para>
- <application>JBoss Transaction Service</application> is based upon the original <application>Arjuna</application> system developed at the University of Newcastle between 1986 and 1995. <application>Arjuna</application> predates the Object Transaction Service (OTS) specification and includes many features not found in the OTS. <application>JBoss Transaction Service</application> is a superset of the OTS: applications written using the standard OTS interfaces will be portable across OTS implementations.
- </para>
- <para>
- In terms of the OTS specfiication, <application>JBoss Transaction Service</application> provides:
- <itemizedlist>
- <listitem>
- <para>full draft 5 compliance, with support for Synchronization objects and PropagationContexts.</para>
- </listitem>
- <listitem>
- <para>support for subtransactions.</para>
- </listitem>
- <listitem>
- <para>implicit context propagation where support from the <application>ORB</application> is available.</para>
- </listitem>
- <listitem>
- <para>support for multi-threaded applications.</para>
- </listitem>
- <listitem>
- <para>fully distributed transaction managers, i.e., there is no central transaction manager, and the creator of a top-level transaction is responsible for its termination. Separate transaction manager support is also available, however.</para>
- </listitem>
- <listitem>
- <para>transaction interposition.</para>
- </listitem>
- <listitem>
- <para>X/Open compliance, including checked transactions. This checking can optionally be disabled.</para>
- <note>
- <title>Note:</title>
- <para>Checked transactions are disabled by default, i.e., any thread can terminate a transaction.</para>
- </note>
- </listitem>
- <listitem>
- <para><application>JDBC</application> 1.0 and 2.0 support.</para>
- </listitem>
- <listitem>
- <para>Full JTA 1.1 support.</para>
- </listitem>
- </itemizedlist>
- </para>
-
- <para>
- There are effectively three different levels at which a programmer can approach using <application>JBoss Transaction Service</application>. These will be briefly described in the following sections, and in more detail in subsequent chapters.
- </para>
-
+ <title>JBoss Transaction Service Basics</title>
+ <para>
+ <application>JBoss Transaction Service</application> is based upon the original <application>Arjuna</application> system developed at the University of Newcastle between 1986 and 1995. <application>Arjuna</application> predates the Object Transaction Service (OTS) specification and includes many features not found in the OTS. <application>JBoss Transaction Service</application> is a superset of the OTS: applications written using the standard OTS interfaces will be portable across OTS implementations.
+ </para>
+ <para>
+ In terms of the OTS specfiication, <application>JBoss Transaction Service</application> provides:
+ <itemizedlist>
+ <listitem>
+ <para>full draft 5 compliance, with support for Synchronization objects and PropagationContexts.</para>
+ </listitem>
+ <listitem>
+ <para>support for subtransactions.</para>
+ </listitem>
+ <listitem>
+ <para>implicit context propagation where support from the <application>ORB</application> is available.</para>
+ </listitem>
+ <listitem>
+ <para>support for multi-threaded applications.</para>
+ </listitem>
+ <listitem>
+ <para>fully distributed transaction managers, i.e., there is no central transaction manager, and the creator of a top-level transaction is responsible for its termination. Separate transaction manager support is also available, however.</para>
+ </listitem>
+ <listitem>
+ <para>transaction interposition.</para>
+ </listitem>
+ <listitem>
+ <para>X/Open compliance, including checked transactions. This checking can optionally be disabled.</para>
<note>
<title>Note:</title>
- <para>
- Because of differences in ORB implementations, JBoss Transaction Service has been written with a separate ORB Portability library which hides these differences; many of the examples used throughout this manual have also been written using this library, and it is therefore recommended that the ORB Portability Manual is read first.
- </para>
+ <para>Checked transactions are disabled by default, i.e., any thread can terminate a transaction.</para>
</note>
-
- <section id="sect-JTS_Programmers_Guide-JTS_Basics-Raw_OTS">
- <title>Raw OTS</title>
- <para>
- The OTS is actually only a protocol engine for driving registered resources through a two-phase commit protocol. Application programmers are responsible for building and registering the Resource objects which take care of persistence and concurrency control to ensure ACID properties for transactional application objects. The programmer must ensure that Resources are registered at appropriate times, and that a given Resource is only registered within a single transaction. Therefore, programming at the raw OTS level is extremely basic: the programmer is responsible for many things, including managing persistence and concurrency control on behalf of every transactional object.
- </para>
-
- </section>
-
- <section id="sect-JTS_Programmers_Guide-JTS_Basics-Enhanced_OTS_Functionality">
- <title>Enhanced OTS Functionality</title>
- <para>
- The OTS implementation of nested transactions is extremely limited, and can lead to the generation of heuristic-like results: a subtransaction coordinator discovers part way through committing that some resources cannot commit; however, it cannot tell the committed resources to abort. <application>JBoss Transaction Service</application> allows nested transactions to execute a full two-phase commit protocol, thus removing the possibility that some resources will have been committed whereas others will have been rolled back.
- </para>
- <para>
- When resources are registered with a transaction the programmer has no control over the order in which these resources will be invoked during the commit/abort protocol, or whether previously registered resources should be replaced with newly registered resources, for example, then resources registered with a subtransaction are merged with its parent. <application>JBoss Transaction Service</application> provides an additional Resource subtype which gives programmers this control.
- </para>
- </section>
+ </listitem>
+ <listitem>
+ <para><application>JDBC</application> 1.0 and 2.0 support.</para>
+ </listitem>
+ <listitem>
+ <para>Full JTA 1.1 support.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
- <section id="sect-JTS_Programmers_Guide-JTS_Basics-Advanced_API">
- <title>Advanced Application Programmer Interface</title>
- <para>
- The OTS does not provide any Resource implementations. These must be provided by the application programmer or the OTS implementer. The interfaces defined within the OTS specification are too low-level for most application programmers. Therefore, <application>JBoss Transaction Service</application> comes with Transactional Objects for Java, which makes use of the raw Common Object Services interfaces but provides a higher-level API (Application Programmer Interface) for building transactional applications and frameworks. This API automates much of the activities concerned with participating in an OTS transaction, allowing the programmer to concentrate on application development, rather than transaction management.
- </para>
- <para>
- The architecture of the system is shown in the figure below. The API interacts with the concurrency control and persistence services, and automatically registers appropriate resources for transactional objects. These resources may also use the persistence and concurrency services.
- <figure id="figure-JTS-Architecture">
- <title><application>JBoss Transaction Service</application> Architecture</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/figure_JBossTS-Architecture.png" format="PNG" />
- </imageobject>
- <textobject>
- <para><application>JBoss Transaction Service</application> Architecture</para>
- </textobject>
- </mediaobject>
- </figure>
- </para>
- <para>
- <application>JBoss Transaction Service</application> exploits object-oriented techniques to present programmers with a toolkit of Java classes from which application classes can inherit to obtain desired properties, such as persistence and concurrency control. These classes form a hierarchy, part of which is shown below.
- <figure id="figure-JTS-Class-Hierarchy">
- <title><application>JBoss Transaction Service</application> Class Hierarchy</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/figure_JBossTS-Class-Hierarchy.png" format="PNG" />
- </imageobject>
- <textobject>
- <para><application>JBoss Transaction Service</application> Class Hierarchy</para>
- </textobject>
- </mediaobject>
- </figure>
- </para>
- <para>
- Apart from specifying the scopes of transactions, and setting appropriate locks within objects, the application programmer does not have any other responsibilities: <application>JBoss Transaction Service</application> guarantees that transactional objects will be registered with, and be driven by, the appropriate transactions, and crash recovery mechanisms are invoked automatically in the event of failures. Using these interfaces, programmers need not worry about either creating or registering Resource objects and calling persistence and concurrency control services. <application>JBoss Transaction Service</application> guarantees that appropriate resources will be registered with, and driven by, the transaction. If a transaction is nested, resources will also be automatically propagated to the transaction’s parent upon commit.
- </para>
- <para>
- The design and implementation goal of <application>JBoss Transaction Service</application> was to provide a programming system for constructing fault-tolerant distributed applications. In meeting this goal, three system properties were considered highly important:
- <variablelist>
- <varlistentry>
- <term> Integration of Mechanisms</term>
- <listitem>
- <para>
- A fault-tolerant distributed system requires a variety of system functions for naming, locating and invoking operations upon objects and also for concurrency control, error detection and recovery from failures. These mechanisms must be integrated such that their use by a programmer is easy and natural.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Flexibility</term>
- <listitem>
- <para>
- These mechanisms must be flexible, permitting application specific enhancements, such as type-specific concurrency and recovery control, to be easily produced from existing defaults.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Portability</term>
- <listitem>
- <para>
- It should be possible to use <application>JBoss Transaction Service</application> on any ORB.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- <para>
- The system is implemented in Java and extensively uses the type-inheritance facilities provided by the language to provide user-defined objects with characteristics such as persistence and recoverability.
- </para>
- </section>
+ <para>
+ There are effectively three different levels at which a programmer can approach using <application>JBoss Transaction Service</application>. These will be briefly described in the following sections, and in more detail in subsequent chapters.
+ </para>
- <section id="sect-JTS_Programmers_Guide-JTS_Basics-JTS_And_OTS_Specification">
- <title><application>JBoss Transaction Service</application> and the OTS Specification</title>
- <para>
- The OTS specification is written to allow its implementation in a flexible manner, in order to cope with different application requirements for transactions. <application>JBoss Transaction Service</application> supports all optional parts of the OTS specification. In addition, if the specification allows functionality to be implemented in a variety of different ways, <application>JBoss Transaction Service</application> supports these possible implementations. This section will briefly describe the default behaviour which <application>JBoss Transaction Service</application> provides for certain options. More information can be obtained from relevant sections in the manual.
- </para>
- <table>
- <title>OTS Specifications and <application>JBoss Transaction Service</application> Implementations</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>OTS Specification</entry>
- <entry><application>Jboss Transaction Service</application> Default Implementation</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <para>
- If the transaction service chooses to restrict the availability of the transaction context, then it should raise the Unavailable exception.
- </para>
- </entry>
- <entry>
- <para>
- <application>JBoss Transaction Service</application> does not restrict the availability of the transaction context
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- An implementation of the transaction service need not initialise the transaction context for every request.
- </para>
- </entry>
- <entry>
- <para>
- <application>JBoss Transaction Service</application> only initialises the transaction context if the interface supported by the target object is derived from the TransactionalObject interface.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- An implementation of the transaction service may restrict the ability for the Coordinator, Terminator and Control objects to be transmitted or used in other execution environments to enable it to guarantee transaction integrity.
- </para>
- </entry>
- <entry>
- <para>
- <application>JBoss Transaction Service</application> does not impose restrictions on the propagation of these objects.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- The transaction service may restrict the termination of a transaction to the client that started it.
+ <note>
+ <title>Note:</title>
+ <para>
+ Because of differences in ORB implementations, JBoss Transaction Service has been written with a separate ORB Portability library which hides these differences; many of the examples used throughout this manual have also been written using this library, and it is therefore recommended that the ORB Portability Manual is read first.
+ </para>
+ </note>
+
+ <section id="sect-JTS_Programmers_Guide-JTS_Basics-Raw_OTS">
+ <title>Raw OTS</title>
+ <para>
+ The OTS is actually only a protocol engine for driving registered resources through a two-phase commit protocol. Application programmers are responsible for building and registering the Resource objects which take care of persistence and concurrency control to ensure ACID properties for transactional application objects. The programmer must ensure that Resources are registered at appropriate times, and that a given Resource is only registered within a single transaction. Therefore, programming at the raw OTS level is extremely basic: the programmer is responsible for many things, including managing persistence and concurrency control on behalf of every transactional object.
+ </para>
+
+ </section>
+
+ <section id="sect-JTS_Programmers_Guide-JTS_Basics-Enhanced_OTS_Functionality">
+ <title>Enhanced OTS Functionality</title>
+ <para>
+ The OTS implementation of nested transactions is extremely limited, and can lead to the generation of heuristic-like results: a subtransaction coordinator discovers part way through committing that some resources cannot commit; however, it cannot tell the committed resources to abort. <application>JBoss Transaction Service</application> allows nested transactions to execute a full two-phase commit protocol, thus removing the possibility that some resources will have been committed whereas others will have been rolled back.
+ </para>
+ <para>
+ When resources are registered with a transaction the programmer has no control over the order in which these resources will be invoked during the commit/abort protocol, or whether previously registered resources should be replaced with newly registered resources, for example, then resources registered with a subtransaction are merged with its parent. <application>JBoss Transaction Service</application> provides an additional Resource subtype which gives programmers this control.
+ </para>
+ </section>
- </para>
- </entry>
- <entry>
- <para>
- <application>JBoss Transaction Service</application> allows the termination of a transaction by any client that uses the Terminator interface. In addition, <application>JBoss Transaction Service</application> does not impose restrictions when clients use the Current interface.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- A TransactionFactory is located using the FactoryFinder interface of the life-cycle service.
- </para>
- </entry>
- <entry>
- <para>
- <application>JBoss Transaction Service</application> provides multiple ways in which the TransactionFactory can be located.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- A transaction service implementation may use the Event Service to report heuristic decisions.
- </para>
- </entry>
- <entry>
- <para>
- <application>JBossTS</application> does not use the Event Service to report heuristic decisions.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- An implementation of the transaction service does not need to support nested transactions.
- </para>
- </entry>
- <entry>
- <para>
- <application>JBoss Transaction Service</application> supports nested transactions. To override this, see Section . <remark>DOCFAIL - Fix Me</remark>
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- Synchronization objects are required to be called whenever the transaction commits.
- </para>
- </entry>
- <entry>
- <para>
- <application>JBoss Transaction Service</application> allows Synchronizations to be called however the transaction terminates.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- A transaction service implementation need not support interposition.
- </para>
- </entry>
- <entry>
- <para>
- <application>JBoss Transaction Service</application> supports various types of interposition.
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
+ <section id="sect-JTS_Programmers_Guide-JTS_Basics-Advanced_API">
+ <title>Advanced Application Programmer Interface</title>
+ <para>
+ The OTS does not provide any Resource implementations. These must be provided by the application programmer or the OTS implementer. The interfaces defined within the OTS specification are too low-level for most application programmers. Therefore, <application>JBoss Transaction Service</application> comes with Transactional Objects for Java, which makes use of the raw Common Object Services interfaces but provides a higher-level API (Application Programmer Interface) for building transactional applications and frameworks. This API automates much of the activities concerned with participating in an OTS transaction, allowing the programmer to concentrate on application development, rather than transaction management.
+ </para>
+ <para>
+ The architecture of the system is shown in the figure below. The API interacts with the concurrency control and persistence services, and automatically registers appropriate resources for transactional objects. These resources may also use the persistence and concurrency services.
+ <figure id="figure-JTS-Architecture">
+ <title><application>JBoss Transaction Service</application> Architecture</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/figure_JBossTS-Architecture.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para><application>JBoss Transaction Service</application> Architecture</para>
+ </textobject>
+ </mediaobject>
+ </figure>
+ </para>
+ <para>
+ <application>JBoss Transaction Service</application> exploits object-oriented techniques to present programmers with a toolkit of Java classes from which application classes can inherit to obtain desired properties, such as persistence and concurrency control. These classes form a hierarchy, part of which is shown below.
+ <figure id="figure-JTS-Class-Hierarchy">
+ <title><application>JBoss Transaction Service</application> Class Hierarchy</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/figure_JBossTS-Class-Hierarchy.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para><application>JBoss Transaction Service</application> Class Hierarchy</para>
+ </textobject>
+ </mediaobject>
+ </figure>
+ </para>
+ <para>
+ Apart from specifying the scopes of transactions, and setting appropriate locks within objects, the application programmer does not have any other responsibilities: <application>JBoss Transaction Service</application> guarantees that transactional objects will be registered with, and be driven by, the appropriate transactions, and crash recovery mechanisms are invoked automatically in the event of failures. Using these interfaces, programmers need not worry about either creating or registering Resource objects and calling persistence and concurrency control services. <application>JBoss Transaction Service</application> guarantees that appropriate resources will be registered with, and driven by, the transaction. If a transaction is nested, resources will also be automatically propagated to the transaction’s parent upon commit.
+ </para>
+ <para>
+ The design and implementation goal of <application>JBoss Transaction Service</application> was to provide a programming system for constructing fault-tolerant distributed applications. In meeting this goal, three system properties were considered highly important:
+ <variablelist>
+ <varlistentry>
+ <term> Integration of Mechanisms</term>
+ <listitem>
+ <para>
+ A fault-tolerant distributed system requires a variety of system functions for naming, locating and invoking operations upon objects and also for concurrency control, error detection and recovery from failures. These mechanisms must be integrated such that their use by a programmer is easy and natural.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Flexibility</term>
+ <listitem>
+ <para>
+ These mechanisms must be flexible, permitting application specific enhancements, such as type-specific concurrency and recovery control, to be easily produced from existing defaults.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Portability</term>
+ <listitem>
+ <para>
+ It should be possible to use <application>JBoss Transaction Service</application> on any ORB.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ <para>
+ The system is implemented in Java and extensively uses the type-inheritance facilities provided by the language to provide user-defined objects with characteristics such as persistence and recoverability.
+ </para>
+ </section>
- <section id="sect-JTS_Programmers_Guide-JTS_Basics-Thread_Class">
- <title>Thread Class</title>
- <para>
- <application>JBoss Transaction Service</application> is fully multi-threaded and supports the OTS notion of allowing multiple threads to be active within a transaction, and for a thread to execute multiple transactions (although a thread can only be active within a single transaction at a time). By default, if a thread is created within the scope of a transaction (i.e., the creating thread has a transaction context associated with it), the new thread will not be associated with the transaction. If the thread is to be associated with the transaction then use the resume method of either the AtomicTransaction class or Current.
- </para>
- <para>
- However, if it is required that newly created threads automatically inherit the transaction context of their parent, then they should be derived from the OTS_Thread class:
- </para>
- <programlisting language="Java" role="JAVA">
- public class OTS_Thread extends Thread
- {
- public void terminate ();
- public void run ();
+ <section id="sect-JTS_Programmers_Guide-JTS_Basics-JTS_And_OTS_Specification">
+ <title><application>JBoss Transaction Service</application> and the OTS Specification</title>
+ <para>
+ The OTS specification is written to allow its implementation in a flexible manner, in order to cope with different application requirements for transactions. <application>JBoss Transaction Service</application> supports all optional parts of the OTS specification. In addition, if the specification allows functionality to be implemented in a variety of different ways, <application>JBoss Transaction Service</application> supports these possible implementations. This section will briefly describe the default behaviour which <application>JBoss Transaction Service</application> provides for certain options. More information can be obtained from relevant sections in the manual.
+ </para>
+ <table>
+ <title>OTS Specifications and <application>JBoss Transaction Service</application> Implementations</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>OTS Specification</entry>
+ <entry><application>Jboss Transaction Service</application> Default Implementation</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ If the transaction service chooses to restrict the availability of the transaction context, then it should raise the Unavailable exception.
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <application>JBoss Transaction Service</application> does not restrict the availability of the transaction context
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ An implementation of the transaction service need not initialise the transaction context for every request.
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <application>JBoss Transaction Service</application> only initialises the transaction context if the interface supported by the target object is derived from the TransactionalObject interface.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ An implementation of the transaction service may restrict the ability for the Coordinator, Terminator and Control objects to be transmitted or used in other execution environments to enable it to guarantee transaction integrity.
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <application>JBoss Transaction Service</application> does not impose restrictions on the propagation of these objects.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ The transaction service may restrict the termination of a transaction to the client that started it.
- protected OTS_Thread ();
- };
- </programlisting>
- <para>
- The programmer must call the run method of <methodname>OTS_Thread</methodname> at the start of the run method of the application thread class. Likewise, it is necessary to call <methodname>terminate</methodname> prior to exiting the body of the application thread’s run method:
- </para>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <application>JBoss Transaction Service</application> allows the termination of a transaction by any client that uses the Terminator interface. In addition, <application>JBoss Transaction Service</application> does not impose restrictions when clients use the Current interface.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ A TransactionFactory is located using the FactoryFinder interface of the life-cycle service.
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <application>JBoss Transaction Service</application> provides multiple ways in which the TransactionFactory can be located.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ A transaction service implementation may use the Event Service to report heuristic decisions.
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <application>JBossTS</application> does not use the Event Service to report heuristic decisions.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ An implementation of the transaction service does not need to support nested transactions.
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <application>JBoss Transaction Service</application> supports nested transactions. To override this, see Section . <remark>DOCFAIL - Fix Me</remark>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ Synchronization objects are required to be called whenever the transaction commits.
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <application>JBoss Transaction Service</application> allows Synchronizations to be called however the transaction terminates.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ A transaction service implementation need not support interposition.
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <application>JBoss Transaction Service</application> supports various types of interposition.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
- <programlisting language="Java" role="JAVA">
- public void run ()
- {
- super.run();
+ <section id="sect-JTS_Programmers_Guide-JTS_Basics-Thread_Class">
+ <title>Thread Class</title>
+ <para>
+ <application>JBoss Transaction Service</application> is fully multi-threaded and supports the OTS notion of allowing multiple threads to be active within a transaction, and for a thread to execute multiple transactions (although a thread can only be active within a single transaction at a time). By default, if a thread is created within the scope of a transaction (i.e., the creating thread has a transaction context associated with it), the new thread will not be associated with the transaction. If the thread is to be associated with the transaction then use the resume method of either the AtomicTransaction class or Current.
+ </para>
+ <para>
+ However, if it is required that newly created threads automatically inherit the transaction context of their parent, then they should be derived from the OTS_Thread class:
+ </para>
+ <programlisting language="Java" role="JAVA">
+ public class OTS_Thread extends Thread
+ {
+ public void terminate ();
+ public void run ();
- // do my work
+ protected OTS_Thread ();
+ };
+ </programlisting>
+ <para>
+ The programmer must call the run method of <methodname>OTS_Thread</methodname> at the start of the run method of the application thread class. Likewise, it is necessary to call <methodname>terminate</methodname> prior to exiting the body of the application thread’s run method:
+ </para>
- super.terminate();
- }
- </programlisting>
- </section>
+ <programlisting language="Java" role="JAVA">
+ public void run ()
+ {
+ super.run();
- <section id="sect-JTS_Programmers_Guide-JTS_Basics-ORB_Portability_Issues">
- <title>ORB Portability Issues</title>
- <para>
- </para>
- </section>
-
+ // do my work
+
+ super.terminate();
+ }
+ </programlisting>
+ </section>
+
+ <section id="sect-JTS_Programmers_Guide-JTS_Basics-ORB_Portability_Issues">
+ <title>ORB Portability Issues</title>
+ <para>
+ Although the CORBA specification is a standard, it is written in such a way that there are several different ways in which an ORB can be implemented. As such, writing portable client and server code can be difficult. Because <application>JBoss Transaction Service</application> has been ported to most of the widely available ORBs we believe that we have encountered many of the incompatibilities which can exist between them. As such, in order to make <application>JBoss Transaction Service</application> portable between ORBs we have developed a series of ORB Portability classes and macros. If an application is written using these classes then it should be more portable between different ORBs. These classes are described in the separate ORB Portability Manual.
+ </para>
+ </section>
+
</chapter>
Modified: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JTS_Programmers_Guide.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JTS_Programmers_Guide.xml 2010-03-10 20:23:01 UTC (rev 32026)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JTS_Programmers_Guide.xml 2010-03-10 23:50:24 UTC (rev 32027)
@@ -6,6 +6,7 @@
<xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Transaction_Processing_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_Introduction.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>
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/OTS_Introduction.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/OTS_Introduction.xml (rev 0)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/OTS_Introduction.xml 2010-03-10 23:50:24 UTC (rev 32027)
@@ -0,0 +1,838 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<chapter id="chap-JTS_Programmers_Guide-Test_Chapterasdf">
+ <title>An Introduction to the OTS</title>
+ <para>
+ Basic <application>JBoss Transaction Service</application> programming involves using the Object Transaction Service (OTS) interfaces provided in the <systemitem>CosTransactions</systemitem> module, specified in <filename>CosTransactions.idl</filename>. This chapter is based on the OTS Specification1. We will only consider those aspects of the OTS which are relevant to an application programmer wishing to use JBoss Transaction Service, rather than an OTS implementer. Where relevant, each section will describe JBoss Transaction Service implementation decisions and runtime choices available to the application programmer. These choices are also summarised at the end of this chapter. In subsequent chapters we will illustrate how these interfaces can be used to construct transactional applications.
+
+ </para>
+ <section id="sect-JTS_Programmers_Guide-Test_Chapter-Test_Section_1asdfasdf">
+ <title>What is the OTS?</title>
+ <para>
+ The raw <systemitem>CosTransactions</systemitem> interfaces can be found in the <systemitem>org.omg.CosTransactions</systemitem> package. The <application>JBoss Transaction Service</application> implementations of these interfaces are located in the <systemitem>com.arjuna.CosTransactions</systemitem> package and its sub packages.
+ </para>
+
+ <note>
+ <para>
+ In the following discussion it will be shown how many run-time decisions of <application>JBoss Transaction Service</application> can be overridden using Java properties specified at run-time. The property names are mentioned in the <classname>com.arjuna.ats.jts.common.Environment</classname> class.
+ </para>
+ </note>
+
+ <para>
+ The fundamental architecture of the OTS is captured in Figure 4. Aspects of this architecture will be described in the rest of the chapter.
+ </para>
+
+ <figure id="figure-OTS-architecture">
+ <title>OTS Architecture</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/figure_OTS-Architecture.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <para>OTS Architecture</para>
+ </textobject>
+ </mediaobject>
+ </figure>
+ </section>
+
+ <section id="sect-JTS_Programmers_Guide-Test_Chapter-Test_Section_2dfasdfa">
+ <title>Application Programming Models</title>
+ <para>
+ A client application program may use direct or indirect context management to manage a transaction. With indirect context management, an application uses the pseudo object called <systemitem>Current</systemitem>, provided by the Transaction Service, to associate the transaction context with the application thread of control. In direct context management, an application manipulates the <systemitem>Control</systemitem> object and the other objects associated with the transaction.
+ </para>
+
+ <para>
+ An object may require transactions to be either explicitly or implicitly propagated to its operations.
+
+ <variablelist>
+ <varlistentry>
+ <term>Explicit Propagation</term>
+ <listitem>
+ <para>
+ An application propagates a transaction context by passing objects defined by the Transaction Service as explicit parameters. This should typically be the <systemitem>PropagationContext</systemitem> structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Implicit Propagation</term>
+ <listitem>
+ <para>
+ Requests are implicitly associated with the client’s transaction; they share the client’s transaction context. It is transmitted implicitly to the objects, without direct client intervention. Implicit propagation depends on indirect context management, since it propagates the transaction context associated with the <systemitem>Current</systemitem> pseudo object. An object that supports implicit propagation would not typically expect to receive any Transaction Service object as an explicit parameter.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ <note>
+ <para>
+ With the release of draft 4 of the specification, <systemitem>Current</systemitem> should now be provided by the ORB.
+ </para>
+ </note>
+
+ <para>
+ A client may use one or both forms of context management, and may communicate with objects that use either method of transaction propagation. (Details of how to enable implicit propagation were described in Section and Section ). This results in four ways in which client applications may communicate with transactional objects:
+
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>Direct Context Management/Explicit Propagation</term>
+ <listitem>
+ <para>
+ The client application directly accesses the Control object and the other objects which describe the state of the transaction. To propagate the transaction to an object, the client must include the appropriate Transaction Service object as an explicit parameter of an operation; typically this should be the <systemitem>PropagationContext</systemitem> structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Indirect Context Management/Implicit Propagation</term>
+ <listitem>
+ <para>
+ The client application uses operations on the <systemitem>Current</systemitem> pseudo object to create and control its transactions. When it issues requests on transactional objects, the transaction context associated with the current thread is implicitly propagated to the object.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Indirect Context Management/Explicit Propagation</term>
+ <listitem>
+ <para>
+ For an implicit model application to use explicit propagation, it can get access to the Control using the <systemitem>get_control</systemitem> operation on the <systemitem>Current</systemitem> pseudo object. It can then use a Transaction Service object as an explicit parameter to a transactional object; for efficiency reasons this should be the <systemitem>PropagationContext</systemitem> structure, obtained by calling <systemitem>get_txcontext</systemitem> on the appropriate <systemitem>Coordinator</systemitem> reference. This is explicit propagation.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Direct Context Management/Implicit Propagation</term>
+ <listitem>
+ <para>
+ A client that accesses the Transaction Service objects directly can use the <systemitem>resume</systemitem> pseudo object operation to set the implicit transaction context associated with its thread. This allows the client to invoke operations of an object that requires implicit propagation of the transaction context.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The main difference between direct and indirect context management is the effect on the invoking thread’s transaction context. If using indirect (i.e., invoking operations through the <systemitem>Current</systemitem> pseudo object), then the thread’s transaction context will be modified automatically by the OTS, e.g., if <systemitem>begin</systemitem> is called then the thread’s notion of the current transaction will be modified to the newly created transaction; when that is terminated, the transaction previously associated with the thread (if any) will be restored as the thread’s context (assuming subtransactions are supported by the OTS implementation). However, if using direct management, no changes to the thread's transaction context are performed by the OTS: the application programmer assumes responsibility for this.
+ </para>
+ </section>
+
+ <section>
+ <title>Interfaces</title>
+
+ <table>
+ <title>Interfaces</title>
+ <tgroup cols="4">
+ <thead>
+ <row>
+ <entry><para>Position</para></entry>
+ <entry><para>Used By</para></entry>
+ <entry><para>Direct Context Management</para></entry>
+ <entry><para>Indirect Context Management</para></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><para>Create a transaction</para></entry>
+ <entry><para>Transaction originator</para></entry>
+ <entry>
+ <code>
+ Factory::create
+ Control::get_terminator Control::get_coordinator
+ </code>
+ </entry>
+ <entry><para>begin, set timeout</para></entry>
+ </row>
+ <row>
+ <entry><para>Terminate a transaction</para></entry>
+ <entry>
+ <para>
+ <itemizedlist>
+ <listitem><para>Transaction originator—implicit</para></listitem>
+ <listitem><para>All—explicit</para></listitem>
+ </itemizedlist>
+ </para>
+ </entry>
+ <entry>
+ <classname>Terminator::commit</classname>
+ <classname>Terminator::rollback</classname>
+ </entry>
+ <entry><para>commit, rollback</para></entry>
+ </row>
+ <row>
+ <entry><para>Rollback a Transaction</para></entry>
+ <entry><para>Server</para></entry>
+ <entry><para><classname>Terminator::rollback_only</classname></para></entry>
+ <entry><para>rollback_only</para></entry>
+ </row>
+ <row>
+ <entry><para>Control propagation of transaction to a server</para></entry>
+ <entry><para>Server</para></entry>
+ <entry><para>Declaraction of method parameter</para></entry>
+ <entry><para><systemitem>TransactionalObject interface</systemitem></para></entry>
+ </row>
+ <row>
+ <entry><para>Control by client of transaction propagation to a server</para></entry>
+ <entry><para>All</para></entry>
+ <entry><para>Request parameters</para></entry>
+ <entry><para><classname>get_control</classname>, <classname>suspend</classname>, <classname>resume</classname></para></entry>
+ </row>
+ <row>
+ <entry><para>Become a participant in a transaction</para></entry>
+ <entry><para>Recoverable server</para></entry>
+ <entry><para><classname>Coordinator::register_resource</classname></para></entry>
+ <entry><para>Not applicable</para></entry>
+ </row>
+ <row>
+ <entry><para>Miscellaneous</para></entry>
+ <entry><para>All</para></entry>
+ <entry><para><classname>Coordinator::get_status Coordinator::get_transaction_name</classname>, <classname>Coordinator::is_same_transaction Coordinator::hash_transaction</classname></para></entry>
+ <entry><para><classname>get_status</classname>, <classname>get_transaction_name</classname>, Not applicable, Not applicable</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <note>
+ <para>For clarity, subtransaction operations are not shown.</para>
+ </note>
+
+ </section>
+
+ <section>
+ <title>The Transaction Factory</title>
+
+ <para>
+ The <systemitem>TransactionFactory</systemitem> interface is provided to allow the transaction originator to begin a top-level transaction. (Subtransactions must be created using the begin method of <systemitem>Current</systemitem>, or the <methodname>create_subtransaction</methodname> method of the parent’s Coordinator.) Operations on the factory and Coordinator to create new transactions are direct context management, and as such will not modify the calling thread’s transaction context.
+ </para>
+ <para>
+ The <systemitem>create</systemitem> operation creates a new top-level transaction and returns its Control object, which can be used to manage or control participation in the new transaction. The parameter to create is an application specific timeout value, in seconds: if the transaction has not completed before this timeout has elapsed it will be subject to being rolled back. If the parameter is zero, then no application specified timeout is established. This can be represented in UML as shown below:
+ </para>
+ <figure id="figure-top_level_transaction_creation">
+ <title>Top-level transaction creation (direct mode)</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/figure_top-level-transaction-creation.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <para>Top-level transaction creation (direct mode)</para>
+ </textobject>
+ </mediaobject>
+ </figure>
+
+ <note>
+ <para>Subtransactions do not have a timeout associated with them.</para>
+ </note>
+
+ <para>
+ The Transaction Service implementation allows the <systemitem>TransactionFactory</systemitem> to be a separate server from the application (e.g., a typical Transaction Monitor) which transaction clients share, and which manages transactions on their behalf. However, the specification also enables the <systemitem>TransactionFactory</systemitem> to be implemented by an object within each transactional client. This is the default implementation used by <application>JBoss Transaction Service</application> since it removes the need for a separate service to be available in order for transactional applications to execute.
+ </para>
+ <para>
+ When running applications which require a separate transaction manager, you must set the <varname>OTS_TRANSACTION_MANAGER</varname> environment variable to have the value <wordasword>YES</wordasword>. The system will then locate the transaction manager server in a manner specific to the ORB being used. The server can be located in a number of ways: by being registered with a name server, added to the ORB’s initial references, via a <application>JBoss Transaction Service</application> specific references file, or by the ORB’s specific location mechanism (if applicable).
+ </para>
+ </section>
+
+ <section>
+ <title>OTS configuration file</title>
+ <para>
+ Similar to the <systemitem>resolve_initial_references</systemitem>, <application>JBoss Transaction Service</application> supports an initial reference file where references for specific services can be stored and used at runtime. The file, <filename>CosServices.cfg</filename>, consists of two columns: the service name (in the case of the OTS server <systemitem>TransactionService</systemitem>) and the IOR, separated by a single space. <filename>CosServices.cfg</filename> normally resides in the <filename>/etc</filename> directory of the <application>JBoss Transaction Service</application> installation. The OTS server will automatically register itself in this file (creating it if necessary) if this option is being used. Stale information is also automatically removed. The name and location of the file can be overridden using the <varname>INITIAL_REFERENCES_FILE</varname> and <varname>INITIAL_REFERENCES_ROOT</varname> property variables, respectively. For example:
+
+ <code>
+ INITIAL_REFERENCES_FILE=myFile
+ INITIAL_REFERENCES_ROOT=c:\\temp
+ </code>
+ </para>
+
+ <section>
+ <title>Name Service</title>
+ <para>
+ If the ORB you are using supports a name service, and JBossTS has been configured to use it, then the transaction manager will automatically be registered with it. There is no further work required.
+ </para>
+ </section>
+
+ <section>
+ <title>ORB Specific Location Mechanism</title>
+ <para>
+ This configuration option is currently only supported for VisiBroker. At runtime the OTS server supports the following option:
+ </para>
+ <itemizedlist>
+ <listitem><para>-otsname: when using VisiBroker this is the marker name for the OTS transaction manager object.</para></listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Overriding the Default Location Mechanism</title>
+ <para>
+ It is possible to override the default location mechanism by using the RESOLVE_SERVICE property variable. This can have one of the following values:
+ </para>
+ <itemizedlist>
+ <listitem><para> <varname>CONFIGURATION_FILE</varname>: the default, this causes the system to use the CosServices.cfg file.</para></listitem>
+ <listitem><para><varname>NAME_SERVICE</varname>: <application>JBoss Transaction Service</application> will attempt to use a name service to locate the transaction factory. If this is not supported, an exception will be thrown</para></listitem>
+ <listitem><para><varname>BIND_CONNECT</varname>: <application>JBoss Transaction Service</application> will use the ORB-specific bind mechanism. If this is not supported, an exception will be thrown.</para></listitem>
+ </itemizedlist>
+ <para>
+ If <varname>RESOLVE_SERVICE</varname> is specified when the transaction factory is run, then the factory will register itself with the specified resolution mechanism.
+ </para>
+ </section>
+ </section>
+
+ <section>
+ <title>Transaction Timeouts</title>
+ <para>
+ Refer to the relevant section in the ArjunaCore Programmers Guide.
+ </para>
+ <note>
+ <para>
+ As of <application>JBoss Transaction Service</application> 4.5 transaction timeouts have been unified across all transaction components and are controlled by <application>ArjunaCore</application>.
+ </para>
+ </note>
+ </section>
+
+ <section>
+ <title>Transaction Contexts</title>
+
+ <para>
+ Fundamental to the OTS architecture is the notion of a transaction context. Each thread is associated with a context. This association may be null, indicating that the thread has no associated transaction, or it refers to a specific transaction. Contexts may be shared across multiple threads. In the presence of nested transactions a context remembers the stack of transactions started within the environment such that when the nested transaction ends the context of the thread can be restored to that in effect before the nested transaction was started. This relationship is shown below in UML, where Current is the object most commonly used by a thread for manipulating its transaction context information (represented by Control objects):
+ </para>
+ <figure id="figure-thraed-and-context-relationship">
+ <title>Thread and Context Relationship</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/figure_thread-and-context-relationship.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <para>Thread and Context Relationships</para>
+ </textobject>
+ </mediaobject>
+ </figure>
+
+ <para>
+ Management of transaction contexts may be undertaken by an application in either a direct or an indirect manner. In the direct approach the transaction originator issues a request to a TransactionFactory to begin a new top-level transaction. The factory returns a Control object that enables two further interfaces to be obtained. These latter interfaces allow an application to end the transaction (via a Terminator interface), to become a participant in the transaction, or to start a nested transaction (both via a Coordinator interface). These interfaces (shown in detail in Interface 1) are expected to be passed as explicit parameters in operation invocations since transaction creation using these interfaces does not change a thread’s current context. If it is necessary to set the current context for a thread to the context represented by the control object returned by the factory the resume operation of the Current interface must be used.
+ </para>
+
+ <example>
+ <title>Interface 1: Direct Context Management Interface</title>
+
+ <programlisting language="Java" role="JAVA">
+
+ interface Terminator
+ {
+ void commit (in boolean report_heuristics) raises (HeuristicMixed, HeuristicHazard);
+ void rollback ();
+ };
+ </programlisting>
+
+ <programlisting language="Java" role="JAVA">
+
+ interface Coordinator
+ {
+ Status get_status ();
+ Status get_parent_status ();
+ Status get_top_level_status ();
+
+ RecoveryCoordinator register_resource (in Resource r) raises (Inactive);
+ Control create_subtransaction () raises (SubtransactionsUnavailable,
+ Inactive);
+
+ void rollback_only () raises (Inactive);
+
+ ...
+ };
+
+ </programlisting>
+
+ <programlisting language="Java" role="JAVA">
+ interface Control
+ {
+ Terminator get_terminator () raises (Unavailable);
+ Coordinator get_coordinator () raises (Unavailable);
+ };
+
+ interface TransactionFactory
+ {
+ Control create (in unsigned long time_out);
+ };
+ Inter
+
+ </programlisting>
+
+ </example>
+ <para>
+ The relationship between a Control and its Coordinator and Terminator interfaces is shown below:
+ </para>
+ <figure id="figure-control_relationship">
+ <title>Control Relationship</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/figure-control_relationship.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <para>Control Relationships</para>
+ </textobject>
+ </mediaobject>
+ </figure>
+
+ <para>
+ When a transaction is created by the factory it is possible to specify a timeout value in seconds; if the transaction has not completed within this timeout then it is subject to possible rollback. If the timeout value is zero then no application specific timeout will be set.
+ </para>
+ <para>
+ In contrast to explicit context management, implicit context management is handled by the Current interface (Interface 2) which provides simplified transaction management functionality and automatically creates nested transactions etc. as required. Transactions created using this interface do alter a thread’s current transaction context.
+ </para>
+ <example>
+ <title>Indirect Context Management Interface</title>
+ <programlisting role="JAVA" language="Java">
+
+ interface Current : CORBA::Current
+ {
+ void begin () raises (SubtransactionsUnavailable);
+ void commit (in boolean report_heuristics) raises (NoTransaction,
+ HeuristicMixed,
+ HeuristicHazard);
+ void rollback () raises (NoTransaction);
+ void rollback_only () raises (NoTransaction);
+
+ . . .
+
+ Control get_control ();
+ Control suspend ();
+ void resume (in Control which) raises (InvalidControl);
+ };
+ </programlisting>
+ </example>
+
+ <section>
+ <title>Nested Transactions</title>
+ <para>
+ The provision of nested transaction (subtransactions) by an OTS implementation is optional; <application>JBoss Transaction Service</application> supports subtransactions. Subtransactions are a useful mechanism for two reasons:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>fault-isolation</term>
+ <listitem><para>if a subtransaction rolls back (e.g., because an object it was using fails) then this does not require the enclosing transaction to rollback, thus undoing all of the work performed so far.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>modularity</term>
+ <listitem><para>if using indirect transaction management (through the Current pseudo-object) there is no special syntax for creating subtransactions: a transaction is simply begun, and if there is already a transaction associated with the calling thread then the new transaction will automatically be nested within it. Therefore, a programmer who knows that an object require transactions can use them within the object: if the object’s methods are invoked without a client transaction, then the object’s transactions will simply be top-level; otherwise, they will be nested within the scope of the client’s transactions. Likewise, a client need not know that the object is transactional, and can begin its own transaction.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ When nested transactions are provided, the transaction context forms a hierarchy. The outermost transaction of such a hierarchy is typically referred to as the top-level transaction. Unlike top-level transactions, the commits of subtransactions are provisional upon the commit/rollback of the enclosing transactions. Resources acquired within a subtransaction should be inherited (retained) by parent transactions upon the commit of the subtransaction, and (assuming no failures) only released when the top-level transaction completes, i.e., they should be retained for the duration of the top-level transaction. If a subtransaction rolls back, it can release any resources it acquired, and undo any changes to resources it inherited.
+ </para>
+ <para>
+ Unlike top-level transactions, in the OTS subtransactions behave differently at commit time. Whereas top-level transactions undergo a two-phase commit protocol, nested transactions do not perform any commit protocol: when a program commits a nested transaction then the transaction is considered committed, and it simply informs any registered resources of its outcome. If a resource cannot commit then it raises an exception, and the OTS implementation is free to ignore this or attempt to rollback the subtransaction. Obviously rolling back a subtransaction may not be possible if some resources have already been told that the transaction has committed.
+ </para>
+ </section>
+ <section>
+ <title>Transaction Propagation</title>
+ <para>
+ The OTS supports both implicit (system driven) propagation and explicit (application driven) propagation of transactional behaviour. In the implicit case no transactional behaviour is specified in an operation signature and any transaction context associated with the calling thread is automatically sent with each operation invocation. With explicit propagation, applications must define their own mechanism for propagating transactions. This allows:
+ </para>
+ <itemizedlist>
+ <listitem><para>A client to control if its transaction is propagated with any operation invocation.</para></listitem>
+ <listitem><para>A client can invoke operations on both transactional and non-transactional objects within a transaction.</para></listitem>
+ </itemizedlist>
+
+ <para>
+ Note that transaction context management and transaction propagation are different things that may be controlled independently of each other. Furthermore, mixing of direct and indirect context management with implicit and explicit transaction propagation is supported. Use of implicit propagation requires co-operation from the ORB, in that the current context associated with the thread must be sent with any operation invocations by a client and extracted by the server prior to actually calling the target operation.
+ </para>
+ <para>
+ If implicit context propagation is required, then the programmer must ensure that <application>JBoss Transaction Service</application> is correctly initialised prior to objects being created; obviously it is necessary for both client and server to agree to use implicit propagation. Implicit context propagation is only possible on those ORBs which either support filters/interceptors, or the <systemitem>CosTSPortability</systemitem> interface. To use implicit transaction propagation, the programmer must perform the following:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>Implicit context propagation</term>
+ <listitem><para>set the OTS_CONTEXT_PROP_MODE property variable to CONTEXT.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Interposition</term>
+ <listitem><para>set the OTS_CONTEXT_PROP_MODE property variable to INTERPOSITION.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ If using the <application>JBoss Transaction Service</application> advanced API then interposition is required.
+ </para>
+ <para>
+ Further information on this subject can be found in Chapter 4.
+ </para>
+ </section>
+
+ <section>
+ <title>Examples</title>
+ <para>
+ To aid in comprehension of the above discussions Program 1 illustrates a simple transactional client using both direct context management and explicit transaction propagation.
+ </para>
+
+ <example>
+ <title>Simple Transactional Client (direct / explicit)</title>
+ <programlisting language="Java" role="JAVA">
+
+ {
+ ...
+ org.omg.CosTransactions.Control c;
+ org.omg.CosTransactions.Terminator t;
+ org.omg.CosTransactions.PropagationContext pgtx;
+
+ c = transFact.create(0); // create top-level action
+
+ pgtx = c.get_coordinator().get_txcontext();
+ ...
+ trans_object.operation(arg, pgtx); // explicit propagation
+ ...
+ t = c.get_terminator(); // get terminator
+ t.commit(false); // so it can be used to commit
+ ...
+ }
+ </programlisting>
+ </example>
+
+ <para>
+ In contrast Program 2 shows the same program using indirect context management and implicit propagation. This example is considerably simpler since the application only has to be concerned with starting and then committing or aborting actions:
+ </para>
+ <example>
+ <title>Simple Transactional Client (indirect / implicit)</title>
+ <programlisting language="Java" role="JAVA">
+
+ {
+ ...
+ current.begin(); // create new action
+ ...
+ trans_object2.operation(arg); // implicit propagation
+ ...
+ current.commit(false); // simple commit
+ ...
+ }
+ </programlisting>
+ </example>
+
+ <para>
+ Finally, Program 3 illustrates the potential flexibility of OTS by using both direct and indirect context management in conjunction with explicit and implicit transaction propagation.
+ </para>
+ <example>
+ <title>Mixed Transactional Client</title>
+ <programlisting language="Java" role="JAVA">
+
+ {
+ ...
+ org.omg.CosTransactions.Control c;
+ org.omg.CosTransactions.Terminator t;
+ org.omg.CosTransactions.PropagationContext pgtx;
+
+ c = transFact.create(0); // create top-level action
+ pgtx = c.get_coordinator().get_txcontext();
+
+ current.resume(c); // set implicit context
+ ...
+ trans_object.operation(arg, pgtx); // explicit propagation
+ trans_object2.operation(arg); // implicit propagation
+ ...
+ current.rollback(); // oops! rollback
+ ...
+ }
+ </programlisting>
+ </example>
+
+ </section>
+ </section>
+
+ <section>
+ <title>Transaction Controls</title>
+ <para>
+ The Control interface allows a program to explicitly manage or propagate a transaction context. An object supporting the Control interface is associated with one specific transaction. The Control interface supports two operations, <methodname>get_terminator</methodname> and <methodname>get_coordinator</methodname>, which return instances of the Terminator and Coordinator interfaces, respectively. Both of these methods throw the Unavailable exception if the Control cannot provide the requested object, e.g., the transaction has terminated. The OTS implementation can restrict the ability for the Terminator and Coordinator to be used in other execution environments or threads; at a minimum the creator must be able to use them.
+ </para>
+ <para>
+ The Control object for a transaction can be obtained when the transaction is created either using the TransactionFactory or the <methodname>create_subtransaction</methodname> method defined by the Coordinator interface. In addition, it is possible to obtain a Control for the current transaction (associated with the current thread) using the <methodname>get_control</methodname> or <methodname>suspend</methodname> methods defined by the Current interface.
+ </para>
+
+ <section>
+ <title><application>JBoss Transaction Service</application> specifics</title>
+ <para>
+ The transaction creator (client thread) must be able to use its Control, but it is OTS implementation specific as to whether other threads can use this object. In the current version of <application>JBoss Transaction Service</application> no restrictions are placed on the users of the Control.
+ </para>
+ <para>
+ It is implementation dependant as to how long a Control remains able to access a transaction after it terminates; in fact, the OTS specification does not provide a means to indicate to the transaction system that information and objects associated with a given transaction can be purged from the system. In <application>JBoss Transaction Service</application>, if using the Current interface then all information about a transaction is destroyed when it terminates. Therefore, the programmer should not use any Control references to the transaction after issuing the commit/rollback operations.
+ </para>
+ <para>
+ However, if the transaction is terminated using the Terminator interface, it is up to the programmer to signal that the transaction information is no longer required: this can be done using the <methodname>destroyControl</methodname> method of the OTS class in the <classname>com.arjuna.CosTransactions</classname> package. Once the program has indicated that the transaction information is no longer required, the same restrictions on using Control references apply as described above. If destroyControl is not called then transaction information will persist until garbage collected by the Java runtime.
+ </para>
+ <para>
+ In the current version of <application>JBoss Transaction Service</application>, both Coordinators and Terminators can be propagated between execution environments.
+ </para>
+ </section>
+ </section>
+
+ <section>
+ <title>The Terminator interface</title>
+ <para>
+ The Terminator interface supports operations to commit or rollback the transaction. Typically, these operations are used by the transaction originator. Each object supporting the Terminator interface is associated with a single transaction. Direct context management via the Terminator interface does not change the client thread’s notion of the current transaction.
+ </para>
+ <para>
+ The commit operation attempts to commit the transaction: to successfully commit, the transaction must not have been marked rollback only, and all of its participants must agree to commit. Otherwise, the TRANSACTION_ROLLEDBACK exception is thrown. If the report_heuristics parameter is true, the Transaction Service will report inconsistent results using the HeuristicMixed and HeuristicHazard exceptions.
+ </para>
+ <para>
+ When a transaction is committed, the coordinator will drive any registered Resources using their <methodname>prepare</methodname> or <methodname>commit methods</methodname>. It is the responsibility of these Resources to ensure that any state changes to recoverable objects are made permanent to guarantee the <acronym>ACID</acronym> (Atomicity, Consistency, Isolation, Durability) properties.
+ </para>
+ <para>
+ When <methodname>rollback</methodname> is called, the registered Resources are responsible for guaranteeing that all changes to recoverable objects made within the scope of the transaction (and its descendants) are undone. All resources locked by the transaction are made available to other transactions as appropriate to the degree of isolation enforced by the resources.
+ </para>
+
+ <section>
+ <title><application>JBoss Transaction Service</application> Specifics</title>
+ <para>
+ See the <application>JBoss Transaction Service</application> specific section of Control for how long Terminator references remain valid after a transaction terminates.
+ </para>
+ <para>
+ When a transaction is committing it is necessary for it to make certain state changes persistent in order that it can recover in the event of a failure and either continue to commit, or rollback. To guarantee ACID properties, these state changes must be flushed to the persistence store implementation before the transaction can proceed to commit; if they are not, the application may assume that the transaction has committed when in fact the state changes may still reside within an operating system cache, and may be lost by a subsequent machine failure. By default, <application>JBoss Transaction Service</application> ensures that such state changes are flushed. However, doing so can impose a significant performance penalty on the application. To prevent transaction state flushes, set the <varname>TRANSACTION_SYNC</varname> variable to OFF.
+ </para>
+ <para>
+ When a transaction commits, if there is only a single registered resource then the transaction manager need not perform the two-phase protocol: a single phase commit is possible, and the outcome of the transaction will be completely determined by the resource. In a distributed environment this optimization result in an important performance improvement. Therefore, by default <application>JBoss Transaction Service</application> performs single phase commit in this situation. However, this can be overridden at runtime by setting the <varname>COMMIT_ONE_PHASE</varname> property variable to NO.
+ </para>
+ </section>
+ </section>
+
+ <section>
+ <title>The Coordinator interface</title>
+ <para>
+ Returned by the get_coordinator method of Control, the Coordinator interface supports the operations needed by resources to participate in the transaction. These participants are typically either recoverable objects or agents of recoverable objects, such as subordinate coordinators. Each object supporting the Coordinator interface is associated with a single transaction. Direct context management via the Coordinator interface does not change the client thread’s notion of the current transaction. Note, it is possible for a transaction to be terminated directly (i.e., through the Terminator) and then an attempt to terminate the transaction again through Current can be made (or vice versa). In this situation, an exception will be thrown for the subsequent termination attempt.
+ </para>
+ <para>
+ The operations supported by the Coordinator interface of interest to application programmers are:
+ </para>
+ <itemizedlist>
+ <listitem><para>get_status, get_parent_status, get_top_level_status: these operations return the status of the associated transaction. At any given time a transaction can have one of the following status values representing its progress:</para></listitem>
+ <listitem><para>StatusActive: the transaction is currently running, and has not been asked to prepare or marked for rollback.</para></listitem>
+ <listitem><para>StatusMarkedRollback: the transaction has been marked for rollback.</para></listitem>
+ <listitem><para>StatusPrepared: the transaction has been prepared, i.e., all subordinates have responded VoteCommit.</para></listitem>
+ <listitem><para>StatusCommitted: the transaction has completed commitment. It is likely that heuristics exist, otherwise the transaction would have been destroyed and StatusNoTransaction returned.</para></listitem>
+ <listitem><para>StatusRolledBack: the transaction has rolled back. It is likely that heuristics exist, otherwise the transaction would have been destroyed and StatusNoTransaction returned.</para></listitem>
+ <listitem><para>StatusUnknown: the Transaction Service cannot determine the current status of the transaction. This is a transient condition, and a subsequent invocation will ultimately return a different status.</para></listitem>
+ <listitem><para>StatusNoTransaction: no transaction is currently associated with the target object. This will occur after a transaction has completed.</para></listitem>
+ <listitem><para>StatusPreparing: the transaction is in the process of preparing and has not yet determined the final outcome.</para></listitem>
+ <listitem><para>StatusCommitting: the transaction is in the process of committing.</para></listitem>
+ <listitem><para>StatusRollingBack: the transaction is in the process of rolling back.</para></listitem>
+ <listitem><para>is_same_transaction et al: these operations can be used for transaction comparison. Resources may use these various operations to guarantee that they are registered only once with a specific transaction.</para></listitem>
+ <listitem><para>hash_transaction, hash_top_level_tran: returns a hash code for the specified transaction.</para></listitem>
+ <listitem><para>register_resource: registers the specified Resource as a participant in the transaction. The Inactive exception is raised if the transaction has already been prepared. The TRANSACTION_ROLLEDBACK exception is raised if the transaction has been marked rollback only. If the Resource is a SubtransactionAwareResource and the transaction is a subtransaction, then this operation registers the resource with this transaction and indirectly with the top-level transaction when the subtransaction’s ancestors have committed. Otherwise, the resource will only be registered with the current transaction. This operation returns a RecoveryCoordinator which can be used by this Resource during recovery. Note, there is no ordering of registered Resources implied by this operation, i.e., if A is registered after B the OTS is free to operate on them in any order when the transaction terminates. Therefore, Resources should not be implemented that assume (or require) such an!
ordering to exist.</para></listitem>
+ <listitem><para>register_subtran_aware: registers the specified subtransaction aware resource with the current transaction only such that it will be informed when the subtransaction commits or rolls back. This method cannot be used to register the resource as a participant in the top-level transaction. The NotSubtransaction exception is raised if the current transaction is not a subtransaction. As with register_resource, no ordering is implied by this operation.</para></listitem>
+ <listitem><para>register_synchronization: registers the Synchronization object with the transaction such that it will be invoked prior to prepare and after the transaction has completed. Synchronizations can only be associated with top-level transactions, and an exception (SynchronizationsUnavailable) will be raised if an attempt is made to register a Synchronization with a subtransaction. As with register_resource, no ordering is implied by this operation.</para></listitem>
+ <listitem><para>rollback_only: marks the transaction so that the only possible outcome is for it to rollback. The Inactive exception is raised if the transaction has already been prepared/completed.</para></listitem>
+ <listitem><para>create_subtransaction: a new subtransaction is created whose parent is the current transaction. The Inactive exception is raised if the current transaction has already been prepared/completed. An implementation of the Transaction Service need not support nested transactions, in which case the SubtransactionsUnavailable exception is raised.</para></listitem>
+ </itemizedlist>
+ <section>
+ <title><application>JBoss Transaction Service</application> specifics</title>
+ <para>
+ See <application>JBoss Transaction Service</application> specific section of Control for how long Coordinator references remain valid after a transaction terminates.
+ </para>
+ <para>
+ <application>JBoss Transaction Service</application> supports subtransactions. If this is not required, then set the <varname>OTS_SUPPORT_SUBTRANSACTIONS</varname> property variable to NO.
+ </para>
+ </section>
+ </section>
+
+ <section>
+ <title>Heuristics</title>
+ <para>
+ The OTS permits individual servers/resources to make so-called Heuristic decisions. Such decisions are unilateral decisions made by one or more participants to commit or abort the transaction without waiting for the consensus decision from the transaction service. Heuristic decisions should be used with care and only in exceptional circumstances since there is the possibility that the decision will differ from that determined by the transaction service and will thus lead to a loss of integrity in the system. If a heuristic decision is made by a participant then an appropriate exception is raised during commit/abort processing. The possible heuristic exceptions are:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>HeuristicRollback</term>
+ <listitem><para>Raised on an attempted commit operation invocation to indicate that the resource has already unilaterally rolled back the transaction.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>HeuristicCommit</term>
+ <listitem><para>Raised on an attempted rollback operation invocation to indicate that the resource has already unilaterally committed the transaction.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>HeuristicMixed</term>
+ <listitem><para>Indicates that a heuristic decision has been made in which some updates have committed while others have been rolled back.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>HeuristicHazard</term>
+ <listitem><para>Indicates that a heuristic decision may have been made, and the disposition of some of the updates is unknown. For those updates which are known they have either all been committed or all rolled back.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Heuristics are ordered such that HeuristicMixed takes priority over HeuristicHazard. Heuristic decisions are only reported back to the originator if the report_heuristics argument was set to true when the commit operation was invoked.
+ </para>
+ </section>
+
+ <section>
+ <title>Current</title>
+ <para>
+ The Current interface defines operations that allow a client to explicitly manage the association between threads and transactions, i.e., indirect context management. It also defines operations that simplify the use of the Transaction Service. Current supports the following operations:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>begin</term>
+ <listitem><para>a new transaction is created, and associated with the current thread. If the client thread is currently associated with a transaction, and the OTS implementation supported nested transactions, the new transaction is a subtransaction of that transaction. Otherwise, the new transaction is a top-level transaction. If the OTS implementation does not support nested transactions, the SubtransactionsUnavailable exception may be thrown. The thread’s notion of the current context will be modified to this transaction.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>commit</term>
+ <listitem><para>the transaction commits; if the client thread does not have permission to commit the transaction, the standard exception NO_PERMISSION is raised. The effect is the same as performing the commit operation on the corresponding Terminator object. The client thread transaction context is returned to the state prior to the begin request.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>rollback</term>
+ <listitem><para>the transaction rolls back; if the client thread does not have permission to terminate the transaction, the standard exception NO_PERMISSION is raised. The effect is the same as performing the rollback operation on the corresponding Terminator object. The client thread transaction context is returned to the state prior to the begin request.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>rollback_only</term>
+ <listitem><para>the transaction is modified so the only possible outcome is for it to rollback. If the transaction has already been terminated (or is in the process of terminating) an appropriate exception will be thrown.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>get_status</term>
+ <listitem><para>returns the status of the current transaction, or StatusNoTransaction if there is no transaction associated with the thread.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>set_timeout</term>
+ <listitem><para>modifies the timeout associated with top-level transactions for subsequent begin requests for this thread only. Subsequent transactions will be subject to being rolled back if they have not completed after the specified number of seconds. It is implementation dependant as to what timeout value will be used for a transaction if one is not explicitly specified prior to begin. <application>JBoss Transaction Service</application> uses a value of zero, i.e., no timeout will be associated with the transaction. There is no interface in the OTS for obtaining the current timeout associated with a thread. However, <application>JBoss Transaction Service</application> provides additional support for this; see the <application>JBoss Transaction Service</application> specific section.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>get_control</term>
+ <listitem><para>if the client thread is not associated with a transaction, a null object reference is returned. Otherwise, a Control object is returned that represents the current transaction. The operation is not dependent on the state of the transaction; in particular, it does not raise the TRANSACTION_ROLLEDBACK exception.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>suspend</term>
+ <listitem><para>if the client thread is not associated with a transaction, a null object reference is returned. Otherwise, an object that represents the transaction context is returned. This object can be given to the resume operation to re-establish this context in a thread. The operation is not dependent on the state of the transaction; in particular, it does not raise the TRANSACTION_ROLLEDBACK exception. When this call returns, the current thread has no transaction context associated with it.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>resume</term>
+ <listitem><para>if the parameter is a null object reference, the client thread becomes associated with no transaction. Otherwise, if the parameter is valid in the current execution environment, the client thread becomes associated with that transaction. Any previous transaction will be forgotten by the thread.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ If we consider the creation of a top-level transaction using the Current pseudo-object, the course of events within the OTS can be represented as follows:
+ </para>
+
+ <figure id="figure-top_level_transaction_creation_indirect">
+ <title>JBoss Community Logo</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/figure-top_level_transaction_creation_indirect.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <para>Top-Level Transaction Creation (indirect)</para>
+ </textobject>
+ </mediaobject>
+ </figure>
+
+ <para>
+ Likewise, creation of a subtransaction through Current can be represented as shown below:
+ </para>
+
+ <figure id="figure-subtransaction_creation_indirect">
+ <title>Subtransaction Creation (indirect)</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/figure-subtransaction_creation_indirect.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <para>Subtransaction Creation (indirect)</para>
+ </textobject>
+ </mediaobject>
+ </figure>
+
+ <para>
+ Given the descriptions of Current, indirect context management, Resource, SubtransactionAwareResource and Synchronization, we can consider the course of events involved in terminating a top-level transaction and a subtransaction. These are illustrated in the following diagrams.
+ </para>
+
+ <section>
+ <title><application>JBoss Transaction Service</application> Specifics</title>
+ <para>
+ The pseudo-object should be obtained using factory finder of the life-cycle service. However, very few ORBs support this. Therefore, in the current implementation of <application>JBoss Transaction Service</application> the programmer should use the <methodname>get_current</methodname> method on the <application>JBoss Transaction Service</application> class OTS. This class hides any ORB specific mechanisms required for obtaining Current.
+ </para>
+ <para>
+ If no timeout value has previously been associated with Current by a thread then <application>JBoss Transaction Service</application> uses a default value of zero, i.e., no timeout will be associated with the transaction. To override this default behaviour, see Section <remark>Fix Me</remark>. The current OTS specification does not provide a means whereby the timeout associated with transaction creation can be obtained. However, <application>JBoss Transaction Service</application> Current supports a <methodname>get_timeout</methodname> method.
+ </para>
+ <para>
+ By default, the <application>JBoss Transaction Service</application> implementation of Current does not use a separate TransactionFactory server when creating new top-level transactions. Each transactional client has its own TransactionFactory which is co-located with it. By setting the <varname>OTS_TRANSACTION_MANAGER</varname> variable to YES this can be overridden at runtime.
+ </para>
+ <para>
+ The transaction factory is located in the <filename>/bin</filename> directory of the <application>JBoss Transaction Service</application> distribution, and can be started by executing the OTS script. Current locates the factory in an ORB specific manner, e.g., using the name service, through resolve_initial_references, or via the CosServices.cfg file located in the /etc directory of the <application>JBoss Transaction Service</application> distribution. This file is similar to resolve_initial_references, and is automatically updated when the transaction factory is started on a particular machine. This file must be copied to the installation of all machines which require to share the same transaction factory.
+ </para>
+ <para>
+ <application>JBoss Transaction Service</application> supports subtransactions. If this is not required, then set the <varname>OTS_SUPPORT_SUBTRANSACTIONS</varname> property variable to NO.
+ </para>
+ <para>
+ The <methodname>setCheckedAction</methodname> method can be used to override the CheckedAction implementation associated with each transaction the thread creates.
+ </para>
+ </section>
+ </section>
+
+ <section>
+ <title>Resource</title>
+ <para>
+ </para>
+ </section>
+
+ <section>
+ <title>SubtransactionAwareResource</title>
+ <para>
+ </para>
+
+ <section>
+ <title><application>JBoss Transaction Service</application> Specifics</title>
+ <para>
+ </para>
+ </section>
+ </section>
+
+ <section>
+ <title>The Synchronization Interface</title>
+ <para>
+ </para>
+
+ <section>
+ <title><application>JBoss Transaction Service</application> Specifics</title>
+ <para>
+ </para>
+ </section>
+ </section>
+
+ <section>
+ <title>Transactions and Registered Resources</title>
+ <para>
+ </para>
+ </section>
+
+ <section>
+ <title>TransactionalObject Interface</title>
+ <para>
+ </para>
+
+ <section>
+ <title><application>JBoss Transaction Service</application> Specifics</title>
+ <para>
+ </para>
+ </section>
+ </section>
+
+ <section>
+ <title>Interposition</title>
+ <para>
+ </para>
+ </section>
+
+ <section>
+ <title>The RecoverCoordinator</title>
+ <para>
+ </para>
+ </section>
+
+ <section>
+ <title>Checked Transaction Behavior</title>
+ <para>
+ </para>
+ <section>
+ <title><application>JBoss Transaction Service</application> Specifics</title>
+ <para>
+ </para>
+ </section>
+ </section>
+
+ <section>
+ <title>Summary of <application>JBoss Transaction Service</application> Implementation Decisions</title>
+ <para>
+ </para>
+ </section>
+
+</chapter>
+
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-subtransaction_creation_indirect.png
===================================================================
(Binary files differ)
Property changes on: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-subtransaction_creation_indirect.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-top_level_transaction_creation_indirect.png
===================================================================
(Binary files differ)
Property changes on: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure-top_level_transaction_creation_indirect.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure_OTS_architecture.png
===================================================================
(Binary files differ)
Property changes on: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure_OTS_architecture.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure_control-relationship.png
===================================================================
(Binary files differ)
Property changes on: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure_control-relationship.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure_thread-and-context-relationships.png
===================================================================
(Binary files differ)
Property changes on: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure_thread-and-context-relationships.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure_top-level-transaction-creation.png
===================================================================
(Binary files differ)
Property changes on: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/figure_top-level-transaction-creation.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
More information about the jboss-svn-commits
mailing list