[jboss-svn-commits] JBL Code SVN: r31928 - in labs/jbosstm/enterprise/tags/EAP_5_0_1: Transactions_JTS_Programmers_Guide and 3 other directories.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Wed Mar 3 23:50:58 EST 2010
Author: laubai
Date: 2010-03-03 23:50:57 -0500 (Wed, 03 Mar 2010)
New Revision: 31928
Added:
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Author_Group.xml
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Book_Info.xml
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Chapter.xml
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.ent
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/Preface.xml
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Revision_History.xml
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Transaction_Processing_Overview.xml
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/JBossTS_Structure.png
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/JBossTS_class_hierarchy.png
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/email folders.png
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/two_phase_commit_protocol.png
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/publican.cfg
Modified:
labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Web_Services_Programmers_Guide/en-US/Introduction.xml
Log:
Added partially-converted JTS Programmers Guide.
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Author_Group.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Author_Group.xml (rev 0)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Author_Group.xml 2010-03-04 04:50:57 UTC (rev 31928)
@@ -0,0 +1,15 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<authorgroup>
+ <author>
+ <firstname>Dude</firstname>
+ <surname>McPants</surname>
+ <affiliation>
+ <orgname>Somewhere</orgname>
+ <orgdiv>Someone</orgdiv>
+ </affiliation>
+ <email>Dude.McPants at example.com</email>
+ </author>
+</authorgroup>
+
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Book_Info.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Book_Info.xml (rev 0)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Book_Info.xml 2010-03-04 04:50:57 UTC (rev 31928)
@@ -0,0 +1,26 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<bookinfo id="book-JTS_Programmers_Guide-JTS_Programmers_Guide">
+ <title>JTS Programmers Guide</title>
+ <subtitle>short description</subtitle>
+ <productname>Documentation</productname>
+ <productnumber>4.6.0</productnumber>
+ <edition>1</edition>
+ <pubsnumber>0</pubsnumber>
+ <abstract>
+ <para>
+ A short overview and summary of the book's subject and purpose, traditionally no more than one paragraph long. Note: the abstract will appear in the front matter of your book and will also be placed in the description field of the book's RPM spec file.
+ </para>
+ </abstract>
+ <corpauthor>
+ <inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="Common_Content/images/title_logo.svg" format="SVG" />
+ </imageobject>
+ </inlinemediaobject>
+ </corpauthor>
+ <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</bookinfo>
+
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Chapter.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Chapter.xml (rev 0)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Chapter.xml 2010-03-04 04:50:57 UTC (rev 31928)
@@ -0,0 +1,31 @@
+<?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_Chapter">
+ <title>Test Chapter</title>
+ <para>
+ This is a test paragraph
+ </para>
+ <section id="sect-JTS_Programmers_Guide-Test_Chapter-Test_Section_1">
+ <title>Test Section 1</title>
+ <para>
+ This is a test paragraph in a section
+ </para>
+ </section>
+
+ <section id="sect-JTS_Programmers_Guide-Test_Chapter-Test_Section_2">
+ <title>Test Section 2</title>
+ <para>
+ This is a test paragraph in Section 2
+ <orderedlist>
+ <listitem>
+ <para>
+ listitem text
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+</chapter>
+
Added: 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 (rev 0)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JBossTS_basics.xml 2010-03-04 04:50:57 UTC (rev 31928)
@@ -0,0 +1,284 @@
+<?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>
+
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JTS_Programmers_Guide.ent
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JTS_Programmers_Guide.ent (rev 0)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JTS_Programmers_Guide.ent 2010-03-04 04:50:57 UTC (rev 31928)
@@ -0,0 +1,4 @@
+<!ENTITY PRODUCT "Documentation">
+<!ENTITY BOOKID "JTS_Programmers_Guide">
+<!ENTITY YEAR "2010">
+<!ENTITY HOLDER "| You need to change the HOLDER entity in the en-US/JTS_Programmers_Guide.ent file |">
Added: 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 (rev 0)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/JTS_Programmers_Guide.xml 2010-03-04 04:50:57 UTC (rev 31928)
@@ -0,0 +1,12 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<book>
+ <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="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="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/Preface.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Preface.xml (rev 0)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Preface.xml 2010-03-04 04:50:57 UTC (rev 31928)
@@ -0,0 +1,11 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<preface id="pref-JTS_Programmers_Guide-Preface">
+ <title>Preface</title>
+ <xi:include href="Common_Content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude"><xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude"><xi:include href="Common_Content/Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </xi:fallback>
+ </xi:include>
+</preface>
+
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Revision_History.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Revision_History.xml (rev 0)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Revision_History.xml 2010-03-04 04:50:57 UTC (rev 31928)
@@ -0,0 +1,25 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<appendix id="appe-JTS_Programmers_Guide-Revision_History">
+ <title>Revision History</title>
+ <simpara>
+ <revhistory>
+ <revision>
+ <revnumber>0</revnumber>
+ <date>Wed Mar 3 2010</date>
+ <author>
+ <firstname>Dude</firstname>
+ <surname>McPants</surname>
+ <email>Dude.McPants at example.com</email>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Initial creation of book by publican</member>
+ </simplelist>
+ </revdescription>
+ </revision>
+ </revhistory>
+ </simpara>
+</appendix>
+
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Transaction_Processing_Overview.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Transaction_Processing_Overview.xml (rev 0)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/Transaction_Processing_Overview.xml 2010-03-04 04:50:57 UTC (rev 31928)
@@ -0,0 +1,157 @@
+<?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_Chapter">
+ <title>An overview of transactin processing</title>
+ <section>
+ <title>What is a transaction?</title>
+ <para>
+ Consider the following situation: a user wishes to purchase access to an on-line newspaper and requires to pay for this access from an account maintained by an on-line bank. Once the newspaper site has received the user’s credit from the bank, they will deliver an electronic token to the user granting access to their site. Ideally the user would like the debiting of the account, and delivery of the token to be “all or nothing” (atomic). However, hardware and software failures could prevent either event from occurring, and leave the system in an indeterminate state.
+ </para>
+
+ <para>
+ Atomic transactions (transactions) possess an “all-or-nothing” property, and are a well-known technique for guaranteeing application consistency in the presence of failures. Transactions possess the following ACID properties:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>Atomicity</term>
+ <listitem><para>The transaction completes successfully (commits) or if it fails (aborts) all of its effects are undone (rolled back).</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Consistency</term>
+ <listitem><para>Transactions produce consistent results and preserve application specific invariants.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Isolation</term>
+ <listitem><para>Intermediate states produced while a transaction is executing are not visible to others. Furthermore transactions appear to execute serially, even if they are actually executed concurrently.</para> </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Durability</term>
+ <listitem><para>The effects of a committed transaction are never lost (except by a catastrophic failure).</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ A transaction can be terminated in two ways: committed or aborted (rolled back). When a transaction is committed, all changes made within it are made durable (forced on to stable storage, e.g., disk). When a transaction is aborted, all of the changes are undone. Atomic actions can also be nested; the effects of a nested action are provisional upon the commit/abort of the outermost (top-level) atomic action.
+ </para>
+ </section>
+
+ <section id="sect-JTS_Programmers_Guide-Test_Chapter-Test_Section_2">
+ <title>Commit Protocol</title>
+ <para>
+ A two-phase commit protocol is required to guarantee that all of the action participants either commit or abort any changes made. Figure 1 illustrates the main aspects of the commit protocol: during phase 1, the action coordinator, C, attempts to communicate with all of the action participants, A and B, to determine whether they will commit or abort. An abort reply from any participant acts as a veto, causing the entire action to abort. Based upon these (lack of) responses, the coordinator arrives at the decision of whether to commit or abort the action. If the action will commit, the coordinator records this decision on stable storage, and the protocol enters phase 2, where the coordinator forces the participants to carry out the decision. The coordinator also informs the participants if the action aborts.
+ </para>
+
+ <para>
+ When each participant receives the coordinator’s phase 1 message, they record sufficient information on stable storage to either commit or abort changes made during the action. After returning the phase 1 response, each participant who returned a commit response must remain blocked until it has received the coordinator’s phase 2 message. Until they receive this message, these resources are unavailable for use by other actions. If the coordinator fails before delivery of this message, these resources remain blocked. However, if crashed machines eventually recover, crash recovery mechanisms can be employed to unblock the protocol and terminate the action.
+ </para>
+
+ <figure>
+ <title>Two phase commit protocol</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/two_phase_commit_protocol.png" format="PNG"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+
+ <section>
+ <title>Transactional proxies</title>
+
+ <para>
+ The action coordinator maintains a transaction context where resources taking part in the action are required to be registered. Such a resource must obey the transaction commit protocol guaranteeing ACID properties; typically this means that the resource will provide specific operations which the action can invoke during the commit/abort protocol. However, it may not be possible to make all resources transactional in this way, e.g., legacy code which cannot be modified. To use these resources within an action it is often possible to provide transactional proxies: the proxy is registered with, and manipulated by, the action as though it were a transactional resource, and the proxy performs implementation specific work to make the resource it represents transactional. This requires that the proxy participate within the commit/abort protocol. Because the work of the proxy is performed as part of the action, it is guaranteed to be completed or undone despite failures of the !
action coordinator or action participants.
+ </para>
+ </section>
+
+ <section>
+ <title>Nested transactions</title>
+
+ <para>
+ Given a system that provides transactions for certain operations, it is sometimes necessary to combine them to form another operation, which is also required to be a transaction. The resulting transaction’s effects are a combination of the effects of the transactions from which it is composed. The transactions which are contained within the resulting transaction are said to be nested (or subtransactions), and the resulting transaction is referred to as the enclosing transaction. The enclosing transaction is sometimes referred to as the parent of a nested (or child) transaction. A hierarchical transaction structure can thus result, with the root of the hierarchy being referred to as the top-level transaction.
+ </para>
+
+ <para>
+ An important difference exists between nested and top-level transactions: the effect of a nested transaction is provisional upon the commit/roll back of its enclosing transaction(s), i.e., the effects will be recovered if the enclosing transaction aborts, even if the nested transaction has committed.
+ </para>
+
+ <para>
+ Subtransactions are a useful mechanism for two reasons:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>fault-isolation</term>
+ <listitem><para>if 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 there is already a transaction associated with a call when a new transaction is begun, then the transaction will 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>
+
+ </section>
+
+ <section>
+ <title>The Object Transaction Service</title>
+
+ <para>The CORBA architecture, as defined by the OMG, is a standard derived by an industrial consortium which promotes the construction of interoperable applications that are based upon the concepts of distributed objects. The architecture principally contains the following components:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Object Request Broker (ORB)</term>
+ <listitem><para>which enables objects to transparently make and receive requests in a distributed, heterogeneous environment. This component is the core of the OMG reference model.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Object Services</term>
+ <listitem><para>a collection of services that support functions for using and implementing objects. Such services are considered to be necessary for the construction of any distributed application. Of particular relevance to this manual is the Object Transaction Service (OTS).</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Common Facilities</term>
+ <listitem><para>are other useful services that applications may need, but which are not considered to be fundamental such as desktop management and help facilities.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The CORBA architecture is structured to allow both its implementation in, and the integration of, a wide variety of object systems. In particular, applications are independent of the location of an object and the language in which an object is implemented, unless the interface the object supports explicitly reveals such details. As defined in the OMG CORBA Services documentation, object services are a collection of services (interfaces and objects) that support the basic functions for using and implementing objects. Such services are necessary in the construction of any distributed application and are always independent of an application domain. The document specifies several core services including naming, event management, persistence, concurrency control and transactions.
+ </para>
+
+ <para>
+ The OTS specification allows transactions to be nested. However, an implementation need not provide this functionality. Appropriate exceptions are raised if an attempt is made to use nested transactions in this case. JBossTS is a fully compliant version of the OTS version 1.1 draft 5, and support nested transactions.
+ </para>
+
+ <para>
+ The transaction service provides interfaces that allow multiple, distributed objects to co-operate in a transaction such that all objects commit or abort their changes together. However, the OTS does not require all objects to have transactional behaviour. Instead objects can choose not to support transactional operations at all, or to support it for some requests but not others. Transaction information may be propagated between client and server explicitly, or implicitly, giving the programmer finer-grained control over an objects transactionality. Objects supporting (partial) transactional behaviour must have interfaces derived from the TransactionalObject interface.
+ </para>
+
+ <para>
+ The Transaction Service specification also distinguishes between recoverable objects and transactional objects. Recoverable objects are those that contain the actual state that may be changed by a transaction and must therefore be informed when the transaction commits or aborts to ensure the consistency of the state changes. This is achieved be registering appropriate objects that support the Resource interface (or the derived SubtransactionAwareResource interface) with the current transaction. Recoverable objects are also by definition transactional objects.
+ </para>
+
+ <para>
+ In contrast, a simple transactional object need not necessarily be a recoverable object if its state is actually implemented using other recoverable objects. A simple transactional object need not take part in the commit protocol used to determine the outcome of the transaction since it does not maintain any state itself, having delegated that responsibility to other recoverable objects which will take part in the commit process.
+ </para>
+
+ <para>
+ The OTS is simply a protocol engine that guarantees that transactional behaviour is obeyed but does not directly support all of the transaction properties given above. As such it requires other co-operating services that implement the required functionality, including:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Persistence/Recovery Service</term>
+ <listitem><para>Required to support the atomicity and durability properties.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Concurrency Control Service</term>
+ <listitem><para>Required to support the isolation properties.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The application programmer is responsible for using appropriate services to ensure that transactional objects have the necessary ACID properties.
+ </para>
+ </section>
+
+</chapter>
+
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/JBossTS_Structure.png
===================================================================
(Binary files differ)
Property changes on: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/JBossTS_Structure.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/JBossTS_class_hierarchy.png
===================================================================
(Binary files differ)
Property changes on: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/JBossTS_class_hierarchy.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/email folders.png
===================================================================
(Binary files differ)
Property changes on: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/email folders.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/two_phase_commit_protocol.png
===================================================================
(Binary files differ)
Property changes on: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/en-US/images/two_phase_commit_protocol.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/publican.cfg
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/publican.cfg (rev 0)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_JTS_Programmers_Guide/publican.cfg 2010-03-04 04:50:57 UTC (rev 31928)
@@ -0,0 +1,7 @@
+# Config::Simple 4.59
+# Wed Mar 3 14:31:40 2010
+
+xml_lang: en-US
+type: Book
+brand: JBoss
+
Modified: labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Web_Services_Programmers_Guide/en-US/Introduction.xml
===================================================================
--- labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Web_Services_Programmers_Guide/en-US/Introduction.xml 2010-03-04 01:02:23 UTC (rev 31927)
+++ labs/jbosstm/enterprise/tags/EAP_5_0_1/Transactions_Web_Services_Programmers_Guide/en-US/Introduction.xml 2010-03-04 04:50:57 UTC (rev 31928)
@@ -7,16 +7,16 @@
<section id="sect-Transactions_Web_Services_Programmers_Guide-Introduction-JBossTS_Web_Services_transactions_overview">
<title>JBossTS Web Services transactions overview</title>
<para>
- The XML transaction service component of JBossTS (shorthand referred to as XTS) supports the coordination of private and public Web services in a business transaction. Therefore, to understand XTS, you must be familiar with Web services, and also understand a little about transactions. This chapter introduces XTS and provides a brief overview of the technologies that form the Web services standard. Additionally, this chapter explores some of the fundamentals of transactioning technology and how it can be applied to Web services. Much of the content presented in this chapter is detailed throughout this guide; however, only overview information about Web services is provided. If you are new to creating Web services, please see consult your Web services platform documentation.
+ The XML Transaction Service (XTS) component of JBossTS supports the coordination of private and public Web services in a business transaction. Therefore, to understand XTS, you must be familiar with Web services, and also understand a little about transactions. This chapter introduces XTS and provides a brief overview of the technologies that form the Web services standard. Additionally, this chapter explores some of the fundamentals of transactioning technology and how it can be applied to Web services. Much of the content presented in this chapter is detailed throughout this guide; however, only overview information about Web services is provided. If you are new to creating Web services, please see consult your Web services platform documentation.
</para>
<para>
- JBossTS provides as the XTS component a transaction solution for Web services. Using XTS, business partners can coordinate complex business transactions in a controlled and reliable manner. The JBossTS Web Services API supports a transactional coordination model based on the WS-C, WS-Atomic Transaction and WS-Business Activity specifications. WS-C is a generic coordination framework developed by IBM, Microsoft and BEA, WS-Atomic Transaction and WS-Business Activity are transaction protocols that utilize this framework.
+ As the XTS component, JBossTS provides a transaction solution for Web services. Using XTS, business partners can coordinate complex business transactions in a controlled and reliable manner. The JBossTS Web Services API supports a transactional coordination model based on the WS-C, WS-Atomic Transaction and WS-Business Activity specifications. WS-C is a generic coordination framework developed by IBM, Microsoft and BEA. WS-Atomic Transaction and WS-Business Activity are transaction protocols that utilize this framework.
</para>
<para>
- Web services are modular, reusable software components that are created by exposing business functionality through a Web service interface. Web services communicate directly with other Web services using standards-based technologies such as SOAP and HTTP. These standards-based communication technologies allow Web services to be accessed by customers, suppliers, and trading partners, independent of hardware operation system or programming environment. The result is a vastly improved collaboration environment as compared to today's EDI and business-to-business (B2B) solutions—an environment where businesses can expose their current and future business applications as Web services that can be easily discovered and accessed by external partners.
+ Web services are modular, reusable software components that are created by exposing business functionality through a Web service interface. Web services communicate directly with other Web services using standards-based technologies such as SOAP and HTTP. These standards-based communication technologies allow Web services to be accessed by customers, suppliers, and trading partners, independent of hardware operation system or programming environment. The result is a vastly improved collaboration environment as compared to today's EDI and business-to-business (B2B) solutions—an environment where businesses can expose their current and future business applications as Web services that can be easily discovered and accessed by external partners.
</para>
<para>
- Web services, by themselves, are not fault tolerant. In fact, some of the reasons that make it an attractive development solution are also the same reasons that service-based applications may have drawbacks:
+ Web services themselves are not fault tolerant. The features that make Web services an attractive development solution are also behind the drawbacks to service-based applications:
</para>
<itemizedlist>
<listitem>
More information about the jboss-svn-commits
mailing list