[jboss-svn-commits] JBL Code SVN: r31950 - labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Thu Mar 4 18:27:53 EST 2010
Author: misty at redhat.com
Date: 2010-03-04 18:27:52 -0500 (Thu, 04 Mar 2010)
New Revision: 31950
Added:
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JBossTS_basics.xml
Removed:
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_Basics.xml
Log:
Changed all instances of JbossTS to JBoss Transaction Service
Deleted: 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-04 22:23:48 UTC (rev 31949)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JBossTS_basics.xml 2010-03-04 23:27:52 UTC (rev 31950)
@@ -1,284 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
-<chapter>
- <title>JBossTS basics</title>
- <section>
- <title>Basics of JBoss TS</title>
- <para>
- JBossTS is based upon the original Arjuna system developed at the University of Newcastle between 1986 and 1995. Arjuna predates the OTS specification and includes many features not found in the OTS. JBossTS 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 specification, JBossTS provides:
- </para>
-
- <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 ORB 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. Note: checked transactions are disabled by default, i.e., any thread can terminate a transaction.
- </para>
- </listitem>
-
- <listitem>
- <para>
- JDBC 1.0 and 2.0 support.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Full JTA 1.1 support.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- There are effectively three different levels at which a programmer can approach using JBossTS. These will be briefly described in the following sections, and in more detail in subsequent chapters.
- </para>
-
- <note>
- <para>
- because of differences in ORB implementations, JBossTS 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>
-
- <formalpara>
- <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>
- </formalpara>
-
- <formalpara>
- <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. JBossTS 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>
- </formalpara>
-
- <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. JBossTS provides an additional Resource subtype which gives programmers this control.
- </para>
-
- <formalpara>
- <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, JBossTS comes with Transactional Objects for Java, which makes use of the raw Common Object Services interfaces but provides a higher-level API 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>
- </formalpara>
-
- <para>
- The architecture of the system is shown in <xref linkend="fig-jbossts-structure"/>. 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.
- </para>
-
- <figure id="fig-jbossts-structure">
- <title>JBossTS Structure</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/JBossTS_Structure.png" format="PNG"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>
- JBossTS 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.
- </para>
-
- <figure>
- <title>JBossTS class hierarchy</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/JBossTS_class_hierarchy.png" format="PNG"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>
- Apart from specifying the scopes of transactions, and setting appropriate locks within objects, the application programmer does not have any other responsibilities: JBossTS 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. JBossTS 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 JBossTS was to provide a programming system for constructing fault-tolerant distributed applications. In meeting this goal, three system properties were considered highly important:
- </para>
-
- <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 run JBossTS on any ORB.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <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>
-
- <formalpara>
- <title>JBossTS 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. JBossTS supports all optional parts of the OTS specification. In addition, if the specification allows functionality to be implemented in a variety of different ways, JBossTS supports these possible implementations. This section will briefly describe the default behaviour which JBossTS provides for certain options. More information can be obtained from relevant sections in the manual.
- </para>
- </formalpara>
- <table frame="all" pgwide="1">
- <title>JBossTS defaults</title>
- <tgroup colsep="1" cols="2">
- <colspec colnum="1" colname="c0"/>
- <colspec colnum="2" colname="c1"/>
- <thead>
- <row>
- <entry>OTS Specification</entry>
- <entry>JBossTS default implementation</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>If the transaction service chooses to restrict the availability of the transaction context, then it should raise the Unavailable exception.</entry>
- <entry>JBossTS does not restrict the availability of the transaction context</entry>
- </row>
- <row>
- <entry>An implementation of the transaction service need not initialise the transaction context for every request.</entry>
- <entry>JBossTS only initialised the transaction context if the interface supported by the target object is derived from the TransactionalObject interface.</entry>
- </row>
- <row>
- <entry>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.</entry>
- <entry>JBossTS does not impose restrictions on the propagation of these objects.</entry>
- </row>
- <row>
- <entry>The transaction service may restrict the termination of a transaction to the client that started it.</entry>
- <entry>JBossTS allows the termination of a transaction by any client that uses the Terminator interface. In addition, JBossTS does not impose restrictions when clients use the Current interface.</entry>
- </row>
- <row>
- <entry>A TransactionFactory is located using the FactoryFinder interface of the life-cycle service.</entry>
- <entry>JBossTS provides multiple ways in which the TransactionFactory can be located.</entry>
- </row>
- <row>
- <entry>A transaction service implementation may use the Event Service to report heuristic decisions.</entry>
- <entry>JBossTS does not use the Event Service to report heuristic decisions.</entry>
- </row>
-
- <row>
- <entry>An implementation of the transaction service does not need to support nested transactions.</entry>
- <entry>JBossTS supports nested transactions. To override this, see Section xxTODOxx [find and insert Section xref link here - not present in original document] .</entry>
- </row>
- <row>
- <entry>Synchronization objects are required to be called whenever the transaction commits.</entry>
- <entry>JBossTS allows Synchronizations to be called however the transaction terminates.</entry>
- </row>
- <row>
- <entry>A transaction service implementation need not support interposition.</entry>
- <entry>JBossTS supports various types of interposition.</entry>
- </row>
-
- </tbody>
-
- </tgroup>
-
- </table>
-
- <formalpara>
- <title>Thread class</title>
-
- <para>
- JBossTS 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 <methodname>method</methodname> of either the <classname>AtomicTransaction</classname> class or <classname>Current</classname>.
- </para>
- </formalpara>
-
- <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>public class OTS_Thread extends Thread
-{
-public void terminate ();
-public void run ();
-
-protected OTS_Thread ();
-};</programlisting>
-
- <para>
- The programmer must call the run method of OTS_Thread at the start of the run method of the application thread class. Likewise, it is necessary to call terminate prior to exiting the body of the application thread’s run method:
- </para>
-
- <programlisting>public void run ()
-{
- super.run();
-
- // do my work
-
- super.terminate();
-}</programlisting>
-
- <formalpara>
- <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 JBossTS 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 JBossTS 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>
-
- </formalpara>
-
- </section>
-</chapter>
-
Copied: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JBossTS_basics.xml (from rev 31949, labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JTS_Basics.xml)
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JBossTS_basics.xml (rev 0)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JBossTS_basics.xml 2010-03-04 23:27:52 UTC (rev 31950)
@@ -0,0 +1,100 @@
+<?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-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 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>
+
+ <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>
+
+ <section id="sect-JTS_Programmers_Guide-JTS_Basics-Advanced_API">
+ <title>Advanced Application Programmer Interface</title>
+ <para>
+ </para>
+ </section>
+
+ <section id="sect-JTS_Programmers_Guide-JTS_Basics-JBoss Transaction Service_And_OTS_Specification">
+ <title><application>JBoss Transaction Service</application> and the OTS Specification</title>
+ <para>
+ </para>
+ </section>
+
+ <section id="sect-JTS_Programmers_Guide-JTS_Basics-Thread_Class">
+ <title>Thread Class</title>
+ <para>
+ </para>
+ </section>
+
+ <section id="sect-JTS_Programmers_Guide-JTS_Basics-ORB_Portability_Issues">
+ <title>ORB Portability Issues</title>
+ <para>
+ </para>
+ </section>
+
+</chapter>
+
Deleted: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JTS_Basics.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JTS_Basics.xml 2010-03-04 22:23:48 UTC (rev 31949)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JTS_Basics.xml 2010-03-04 23:27:52 UTC (rev 31950)
@@ -1,100 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
-<chapter id="chap-JTS_Programmers_Guide-JTS_Basics">
- <title>JBossTS Basics</title>
- <para>
- <application>JBossTS</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 OTS specification and includes many features not found in the OTS. <application>JBossTS</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>JBossTS</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>JBossTS</application>. These will be briefly described in the following sections, and in more detail in subsequent chapters.
- </para>
-
- <note>
- <title>Note:</title>
- <para>
- Because of differences in ORB implementations, JBossTS 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>JBossTS</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>JBossTS</application> provides an additional Resource subtype which gives programmers this control.
- </para>
- </section>
-
- <section id="sect-JTS_Programmers_Guide-JTS_Basics-Advanced_API">
- <title>Advanced Application Programmer Interface</title>
- <para>
- </para>
- </section>
-
- <section id="sect-JTS_Programmers_Guide-JTS_Basics-JBossTS_And_OTS_Specification">
- <title><application>JBossTS</application> and the OTS Specification</title>
- <para>
- </para>
- </section>
-
- <section id="sect-JTS_Programmers_Guide-JTS_Basics-Thread_Class">
- <title>Thread Class</title>
- <para>
- </para>
- </section>
-
- <section id="sect-JTS_Programmers_Guide-JTS_Basics-ORB_Portability_Issues">
- <title>ORB Portability Issues</title>
- <para>
- </para>
- </section>
-
-</chapter>
-
More information about the jboss-svn-commits
mailing list