[jboss-svn-commits] JBL Code SVN: r36889 - in labs/jbosstm/trunk/docs/transactions_overview_guide/en-US: images and 1 other directory.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Tue Apr 12 07:27:04 EDT 2011
Author: tomjenkinson
Date: 2011-04-12 07:27:04 -0400 (Tue, 12 Apr 2011)
New Revision: 36889
Removed:
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Introduction.xml
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/XTS_API.xml
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/extras/
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/images/fig-2pc-participant-state-transitions.png
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/images/fig-at-model.png
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/images/fig-back-end-pattern.png
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/images/fig-bawcc-state-transitions.png
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/images/fig-bawpc-state-transitions.png
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/images/fig-context-handlers-registered-with-soap-server.png
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/images/fig-participant-backend-control.png
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/images/fig-web-services-transaction.png
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/images/fig-ws-c-overview.png
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/images/fig-ws-trans-services-participants.png
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/images/fig-wsc-four-roles.png
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/images/fig-wsc-wst-interop.png
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/images/ws-trans-global-view.png
Modified:
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/About_This_Guide.xml
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Author_Group.xml
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Book_Info.xml
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Transactions_Overview.xml
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Transactions_Overview_Guide.xml
Log:
JBTM-700 first guide attempt
Modified: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/About_This_Guide.xml
===================================================================
--- labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/About_This_Guide.xml 2011-04-12 10:51:00 UTC (rev 36888)
+++ labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/About_This_Guide.xml 2011-04-12 11:27:04 UTC (rev 36889)
@@ -1,63 +1,25 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "Transactions_XTS_Administration_And_Development_Guide.ent">
-<!ENTITY % BOOK_ENTITIES SYSTEM "Transactions_XTS_Programmers_Guide.ent">
+<!ENTITY % BOOK_ENTITIES SYSTEM "Transactions_Overview_Guide.ent">
%BOOK_ENTITIES;
]>
<chapter>
<title>About This Guide</title>
<para>
- The XTS Development Guide explains how to add resilience to distributed business processes based on web services,
- making them reliable in the event of system or network failures. It covers installation, administration, and
- development of transactional web services.
+ The Transaction Fundamentals describes what transactions are, why ACID transactions are good in most cases but extended transactions are necessary in other areas, and other useful information to best use JBossTS.
</para>
- <para>
- The &APPSERVER; implements Web Services
- Transactions standards using <firstterm>XTS (XML Transaction Service)</firstterm>. XTS supports development and
- deployment of transaction-aware web services. It also enables web service clients to create and manage web service
- transactions from which transactional web services can be invoked. XTS ensures that the client and web services
- achieve consistent outcomes even if the systems on which they are running crash or temporarily lose network
- connectivity.
- </para>
- <para>
- XTS is compliant with the <firstterm>WS-Coordination</firstterm>, <firstterm>WS-Atomic Transaction</firstterm>, and
- <firstterm>WS-Business Activity</firstterm> specifications. The implementation supports web services and clients
- which are based on the JaxWS standard. XTS is itself implemented using services based on JaxWS. While this guide
- discusses many Web Services standards like SOAP and WSDL, it does not attempt to address all of their fundamental
- constructs. However, basic concepts are provided where necessary.
- </para>
<section>
<title>Audience</title>
<para>
- This guide is most relevant for application developers and Web service developers who are interested in building
- applications and Web services that are transaction-aware. It is also useful for system analysts and project
- managers who are unfamiliar with transactions as they pertain to Web services.
+ This guide is most relevant for developers who want to understand the details behind transaction systems.
</para>
</section>
<section>
<title>Prerequisites</title>
<para>
- JBoss Transaction Service uses the Java programming language and this manual assumes that you are familiar with
- programming in Java. Additional helpful skills are outlined in <xref linkend="prereqs-list" />.
+ None.
</para>
- <itemizedlist id="prereqs-list">
- <title>Prerequisite Skills for XTS Developers</title>
- <listitem><para>A Working knowledge of Web Services, including XML, SOAP, and WSDL</para></listitem>
- <listitem><para>A general understanding of transactions</para></listitem>
- <listitem><para>A general understanding of WS-Coordination, WS-Atomic Transaction and WS-Business Activity
- protocols</para></listitem>
- </itemizedlist>
- <para>
- This guide presents overview information for all of the above. However, to aid in understanding the Web Services
- component of JBoss Transaction Service, the WS-C<footnote><para><ulink
- url="http://download.boulder.ibm.com/ibmdl/pub/software/dw/specs/ws-tx/WS-Coordination.pdf" /></para></footnote>,
- WS-Atomic Transaction<footnote><para><ulink
- url="http://download.boulder.ibm.com/ibmdl/pub/software/dw/specs/ws-tx/WS-AtomicTransaction.pdf"
- /></para></footnote>, and WS-Business Activity<footnote><para><ulink
- url="http://download.boulder.ibm.com/ibmdl/pub/software/dw/specs/ws-tx/WS-BusinessActivity.pdf"
- /></para></footnote> specifications are discussed in great detail.
- </para>
</section>
</chapter>
Modified: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Author_Group.xml
===================================================================
--- labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Author_Group.xml 2011-04-12 10:51:00 UTC (rev 36888)
+++ labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Author_Group.xml 2011-04-12 11:27:04 UTC (rev 36889)
@@ -1,26 +1,10 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "Transactions_XTS_Administration_And_Development_Guide.ent">
+<!ENTITY % BOOK_ENTITIES SYSTEM "Transactions_Overview_Guide.ent">
%BOOK_ENTITIES;
]>
<authorgroup>
<author>
- <firstname>Andrew</firstname>
- <surname>Dinn</surname>
- <affiliation>
- <orgname>Red Hat</orgname>
- </affiliation>
- <email>adinn at redhat.com</email>
- </author>
- <author>
- <firstname>Kevin</firstname>
- <surname>Connor</surname>
- <affiliation>
- <orgname>Red Hat</orgname>
- </affiliation>
- <email>kconnor at redhat.com</email>
- </author>
- <author>
<firstname>Mark</firstname>
<surname>Little</surname>
<affiliation>
Modified: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Book_Info.xml
===================================================================
--- labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Book_Info.xml 2011-04-12 10:51:00 UTC (rev 36888)
+++ labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Book_Info.xml 2011-04-12 11:27:04 UTC (rev 36889)
@@ -1,18 +1,18 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "Transactions_XTS_Administration_And_Development_Guide.ent">
+<!ENTITY % BOOK_ENTITIES SYSTEM "Transactions_Overview_Guide.ent">
%BOOK_ENTITIES;
]>
-<bookinfo id="book-Transactions_XTS_Development_Guide-Transactions_XTS_Development_Guide">
- <title>Transactions XTS Administration And Development Guide</title>
- <subtitle>Using the XTS Module of &PRODUCT; to provide Web Services Transactions</subtitle>
+<bookinfo id="book-Transactions_Overview_Guide">
+ <title>Transactions Overview Guide</title>
+ <!--subtitle>JBoss Transaction Service</subtitle-->
<productname>JBoss Transactions</productname>
- <productnumber>4.14.0</productnumber>
+ <productnumber>4.15.0</productnumber>
<edition>0</edition>
<pubsnumber>0</pubsnumber>
<abstract>
<para>
- The XTS Development Guide contains information on how to use JBoss Transaction Service to develop service-based
+ The Transactions Overview Guide contains information on how to use JBoss Transaction Service to develop
applications that use transaction technology to manage business processes.
</para>
</abstract>
Deleted: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Introduction.xml
===================================================================
--- labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Introduction.xml 2011-04-12 10:51:00 UTC (rev 36888)
+++ labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Introduction.xml 2011-04-12 11:27:04 UTC (rev 36889)
@@ -1,198 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "Transactions_XTS_Administration_And_Development_Guide.ent">
-%BOOK_ENTITIES;
-]>
-<chapter>
-
- <title>Introduction</title>
-
- <indexterm><primary>XTS</primary><secondary>XML Transaction Service</secondary></indexterm>
- <indexterm><primary>Web Services</primary></indexterm>
- <indexterm><primary>transactions</primary></indexterm>
- <indexterm><primary>WS-Coordination</primary><secondary>WS-C</secondary></indexterm>
- <indexterm><primary>WS-Atomic Transaction</primary><secondary>WS-AT</secondary></indexterm>
- <indexterm><primary>WS-Business Activity</primary><secondary>WS-BA</secondary></indexterm>
- <indexterm><primary>XTS 1.0</primary><secondary>XTS 1.1</secondary></indexterm>
- <indexterm><primary>SOAP</primary></indexterm>
- <indexterm><primary>fault-tolerance</primary></indexterm>
- <indexterm><primary>undesirable outcomes</primary></indexterm>
- <indexterm><primary>participants</primary><secondary>transaction participants</secondary></indexterm>
- <indexterm><primary>active component</primary></indexterm>
- <indexterm><primary>servlets</primary><secondary>Java servlets</secondary></indexterm>
- <indexterm><primary>RPC</primary><secondary>Remote Procedure Calls</secondary></indexterm>
- <indexterm><primary>DE</primary><secondary>Document Exchange</secondary></indexterm>
- <indexterm><primary>WSDL</primary><secondary>Web Services Description Language</secondary></indexterm>
-
- <para>
- The <firstterm>XML Transaction Service (XTS)</firstterm> component of JBoss Transaction Service 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 something 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>
- JBoss Transaction Service provides the XTS component as a transaction solution for Web Services. Using XTS, business
- partners can coordinate complex business transactions in a controlled and reliable manner. The XTS API supports a
- transactional coordination model based on the <firstterm>WS-Coordination</firstterm>, <firstterm>WS-Atomic
- Transaction</firstterm>, and <firstterm>WS-Business Activity</firstterm> specifications.
- </para>
- <itemizedlist id="protocol-spec-list">
- <title>Protocols Included in XTS</title>
- <listitem><para>WS-Coordination (WS-C) is a generic coordination framework developed by IBM, Microsoft and BEA.</para></listitem>
- <listitem><para>WS-Atomic Transaction (WS-AT) and WS-Business Activity (WS-BA) together comprise the WS-Transaction
- (WS-T) transaction protocols that utilize this framework.</para></listitem>
- </itemizedlist>
- <para>
- JBoss Transaction Service implements versions 1.0, 1.1, and 1.2 of these three specifications. Version
- specifications are available from <ulink url="http://www.oasis-open.org/specs/" />.
- </para>
- <note>
- <para>
- The 1.0, 1.1, and 1.2 specifications only differ in a small number of details. The rest of this document employs
- version 1.1 of these specifications when providing explanations and example code. On the few occasions where the
- modifications required to adapt these to the 1.1 specifications are not obvious, an explanatory note is provided.
- </para>
- </note>
-
- <para>
- <firstterm>Web Services</firstterm> 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 enable
- customers, suppliers, and trading partners to access Web Services, independent of hardware operating system, or
- programming environment. The result is a vastly improved collaboration environment as compared to today's EDI and
- <firstterm>business-to-business (B2B)</firstterm> 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 the Web Services model is an
- attractive development solution are also the same reasons that service-based applications may have drawbacks.
- </para>
- <itemizedlist>
- <title>Properties of Web Services</title>
- <listitem><para>Application components that are exposed as Web Services may be owned by third parties, which provides benefits in terms of cost of maintenance, but drawbacks in terms of having exclusive control over their behavior.</para></listitem>
- <listitem><para>Web Services are usually remotely located, increasing risk of failure due to increased network
- travel for invocations.</para></listitem>
- </itemizedlist>
-
- <para>
- Applications that have high dependability requirements need a method of minimizing the effects of errors that may
- occur when an application consumes Web Services. One method of safeguarding against such failures is to interact
- with an application’s Web Services within the context of a <firstterm>transaction</firstterm>. A transaction is a
- unit of work which is completed entirely, or in the case of failures is reversed to some agreed consistent
- state. The goal, in the event of a failure, is normally to appear as if the work had never occurred in the first
- place. With XTS, transactions can span multiple Web Services, meaning that work performed across multiple
- enterprises can be managed with transactional support.
- </para>
-
- <section>
- <title>Managing service-Based Processes</title>
- <para>
- XTS allows you to create transactions that drive complex business processes, spanning multiple Web
- Services. Current Web Services standards do not address the requirements for a high-level coordination of
- services. This is because in today’s Web Services applications, which use single request/receive interactions,
- coordination is typically not a problem. However, for applications that engage multiple services among multiple
- business partners, coordinating and controlling the resulting interactions is essential. This becomes even more
- apparent when you realize that you generally have little in the way of formal guarantees when interacting with
- third-party Web Services.
- </para>
- <para>
- XTS provides the infrastructure for coordinating services during a business process. By organizing processes as
- transactions, business partners can collaborate on complex business interactions in a reliable manner, insuring
- the integrity of their data - usually represented by multiple changes to a database – but without the usual
- overheads and drawbacks of directly exposing traditional transaction-processing engines directly onto the
- web. <xref linkend="example-application" /> demonstrates how an application may manage service-based processes as
- transactions:
- </para>
- <formalpara id="example-application">
- <title>An Evening On the Town</title>
- <para>
- The application in question allows a user to plan a social evening. This application is responsible for reserving a
- table at a restaurant, and reserving tickets to a show. Both activities are paid for using a credit card. In this
- example, each service represents exposed Web Services provided by different service providers. XTS is used to envelop
- the interactions between the theater and restaurant services into a single (potentially) long-running business
- transaction. The business transaction must insure that seats are reserved both at the restaurant and the theater. If
- one event fails the user has the ability to decline both events, thus returning both services back to their original
- state. If both events are successful, the user’s credit card is charged and both seats are booked. As you may expect,
- the interaction between the services must be controlled in a reliable manner over a period of time. In addition,
- management must span several third-party services that are remotely deployed.
- </para>
- </formalpara>
- <para>
- Without the backing of a transaction, an undesirable outcome may occur. For example, the user credit card may be
- charged, even if one or both of the bookings fail.
- </para>
- <para>
- <xref linkend="example-application" /> describes the situations where XTS excels at supporting business processes
- across multiple enterprises. This example is further refined throughout this guide, and appears as a standard
- demonstrator (including source code) with the XTS distribution.
- </para>
- </section>
-
- <section>
- <title>Servlets</title>
-
- <para>
- The WS-Coordination, WS-Atomic Transaction, and WS-Business Activity protocols are based on one-way interactions
- of entities rather than traditional synchronous request/response RPC-style interactions. One group of entities,
- called transaction participants, invoke operations on other entities, such as the transaction coordinator, in
- order to return responses to requests. The programming model is based on peer-to-peer relationships, with the
- result that all services, whether they are participants, coordinators or clients, must have an <firstterm>active
- component</firstterm> that allows them to receive unsolicited messages.
- </para>
- <para>
- <!--
- In XTS, the active component is achieved through the use of <firstterm>Java servlet</firstterm> technology. Each
- endpoint that can be communicated with via SOAP/XML is represented as a servlet, and published within
- JNDI. Fortunately for the developer, this use of servlets occurs transparently. The only drawback is that clients
- must reside within a domain capable of hosting servlets, such as an application server. In the case of Enterprise
- Application Platform, JBoss Application Server provides this functionality.-->
- In XTS, the active component is achieved through deployment of JaxWS
- endpoints. Each XTS endpoint that is reachable through SOAP/XML is
- published via JaxWS, without developer intevention. The only requirement
- is that transactional client applications and transactional web services
- must reside within a domain capable of hosting JaxWS endpoints, such as an
- application server. JBoss Application Server can provide this functionality.
- </para>
-
- <note>
- <para>
- The XTS 1.0 protocol implementation is based on servlets.
- </para>
- </note>
- </section>
-
- <section>
- <title>SOAP</title>
-
- <para>
- SOAP has emerged as the <foreignphrase>de facto</foreignphrase> message format for XML-based communication in the
- Web Services arena. It is a lightweight protocol that allows the user to define the content of a message and to
- provide hints as to how recipients should process that message.
- </para>
- <!--
- <para> SOAP messages can be divided into two main categories: <firstterm>Remote Procedure Call (RPC)</firstterm> and
- <firstterm>Document Exchange (DE)</firstterm>. The primary difference between the two categories is that the SOAP
- specification defines encoding rules and conventions for RPC. The document exchange model allows the exchange of
- arbitrary XML documents, which is a key ingredient of B2B document exchange. XTS is based on the loosely coupled DE
- style, yet it can support transactions spanning Web service that use either DE or RPC. </para>
- -->
- </section>
-
- <section>
- <title>Web Services Description Language (WDSL)</title>
- <para>
- <firstterm>Web Services Description Language (WSDL)</firstterm> is an XML-based language used to define Web
- service interfaces. An application that consumes a Web service parses the service’s WSDL document to discover the
- location of the service, the operations that the service supports, the protocol bindings the service supports
- (SOAP, HTTP, etc), and how to access them. For each operation, WSDL describes the format that the client must
- follow.
- </para>
- </section>
-
-</chapter>
\ No newline at end of file
Modified: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Transactions_Overview.xml
===================================================================
--- labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Transactions_Overview.xml 2011-04-12 10:51:00 UTC (rev 36888)
+++ labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Transactions_Overview.xml 2011-04-12 11:27:04 UTC (rev 36889)
@@ -1,102 +1,124 @@
-<?xml version='1.0' encoding='utf-8' ?>
+<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "Transactions_XTS_Administration_And_Development_Guide.ent">
-%BOOK_ENTITIES;
+<!ENTITY % BOOK_ENTITIES SYSTEM "Transactions_Overview_Guide.ent">
]>
<chapter>
-
- <title>Transactions Overview</title>
-
- <indexterm><primary>transactions</primary></indexterm>
- <indexterm><primary>ACID</primary></indexterm>
- <indexterm><primary>Coordinator</primary></indexterm>
- <indexterm><primary>Participant</primary></indexterm>
- <indexterm><primary>Two-Phase Commit</primary><secondary>2PC</secondary></indexterm>
- <indexterm><primary>One-Phase Commit</primary><secondary>1PC</secondary></indexterm>
- <indexterm><primary>Web Service</primary></indexterm>
- <indexterm><primary>Transaction Service</primary></indexterm>
- <indexterm><primary>Transaction Context</primary></indexterm>
- <indexterm><primary>Synchronization Protocol</primary></indexterm>
- <indexterm><primary>Optimizations to Synchronization Protocols</primary></indexterm>
- <indexterm><primary>Non-atomic</primary></indexterm>
- <indexterm><primary>Heuristic Outcomes</primary></indexterm>
- <indexterm><primary>Interpositions</primary></indexterm>
-
- <note>
- <para>
- This chapter deals with the theory of transactional Web Services. If you are familiar with these principles,
+ <title>Transactions Overview</title>
+ <indexterm>
+ <primary>transactions</primary>
+ </indexterm>
+ <indexterm>
+ <primary>ACID</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Coordinator</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Participant</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Two-Phase Commit</primary>
+ <secondary>2PC</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>One-Phase Commit</primary>
+ <secondary>1PC</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Web Service</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Transaction Service</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Transaction Context</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Synchronization Protocol</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Optimizations to Synchronization Protocols</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Non-atomic</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Heuristic Outcomes</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Interpositions</primary>
+ </indexterm>
+ <section>
+ <title>What is a transaction?</title>
+ <note>
+ <para>
+ This chapter deals with the theory of transactional services. If you are familiar with these principles,
consider this chapter a reference.
</para>
- </note>
- <para>
- Transactions have emerged as the dominant paradigm for coordinating interactions between parties in a distributed
- system, and in particular to manage applications that require concurrent access to shared data. Much of the JBoss
- Transaction Service Web Service API is based on contemporary transaction APIs whose familiarity will enhance
- developer productivity and lessen the learning curve. While the following section provides the essential information
- that you should know before starting to use XTS for building transactional Web Services, it should not be treated as
- a definitive reference to all transactional technology.
+ </note>
+ <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>
- A transaction is a unit of work that encapsulates multiple database actions such that that either all the
- encapsulated actions fail or all succeed.
+ <itemizedlist id="tx-properties">
+ <listitem>
+ <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>
+ </listitem>
+ <listitem>
+ <para>
+Atomicity: The transaction completes successfully (commits) or if it fails (aborts) all of its effects are undone (rolled back).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Consistency: Transactions produce consistent results and preserve application specific invariants.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Isolation: 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>
+ <listitem>
+ <para>
+Durability: The effects of a committed transaction are never lost (except by a catastrophic failure).
+ </para>
+ </listitem>
+ </itemizedlist>
+ <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>
- <para>
- Transactions ensure data integrity when an application interacts with multiple datasources.
+ <para>
+Transactions have emerged as the dominant paradigm for coordinating interactions between parties in a (distributed) system, and in particular to manage applications that require concurrent access to shared data. A classic transaction is a unit of work that either completely succeeds, or fails with all partially completed work being undone. When a transaction is committed, all changes made by the associated requests are made durable, normally by committing the results of the work to a database. If a transaction should fail and is rolled back, all changes made by the associated work are undone. Transactions in distributed systems typically require the use of a transaction manager that is responsible for coordinating all of the participants that are part of the transaction.
</para>
-
- <para>
- The main components involved in using and defining transactional Web Services using XTS are illustrated in <xref
- linkend="fig-web-services-transaction" />.
- </para>
-
- <figure id="fig-web-services-transaction">
- <title>Components Involved in an XTS Transaction</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/fig-web-services-transaction.png" format="PNG"/>
- </imageobject>
- <textobject>
- <variablelist>
- <varlistentry>
- <term>Transaction Service</term>
- <listitem>
- <para>The Transaction Service captures the model of the underlying transaction protocol and coordinates parties affiliated with the transaction according to that model.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Transaction API</term>
- <listitem>
- <para>
- Provides an interface for transaction demarcation and the registration of participants.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>A Participant</term>
- <listitem>
- <para>
- The entity that cooperates with the transaction service on behalf of its associated business logic.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>The Context</term>
- <listitem>
- <para>
- Captures the necessary details of the transaction such that participants can enlist within its scope.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </textobject>
- </mediaobject>
- </figure>
-
- <section>
- <title>The Coordinator</title>
- <para>
- <!--
+ <itemizedlist id="tx-components">
+ <title>The main components involved in using and defining transactional applications are:</title>
+ <listitem>
+ <para>
+A Transaction Service: The Transaction Service captures the model of the underlying transaction protocol and coordinates parties affiliated with the transaction according to that model.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A Transaction API: Provides an interface for transaction demarcation and the registration of participants.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+A Participant: The entity that cooperates with the transaction service on behalf of its associated business logic.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The Context: Captures the necessary details of the transaction such that participants can enlist within its scope.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>The Coordinator</title>
+ <para><!--
Every transaction is associated with a coordinator, which is responsible for governing the outcome of the
transaction. The coordinator may be implemented as a separate service or may be co-located with the user for
improved performance. Each coordinator is created by the transaction manager service, which is effectively a
@@ -113,19 +135,7 @@
parallel, so each coordinator is identified by a unique transaction
identifier.
</para>
- <para>
- <!--
- A coordinator communicates with enrolled participants to inform them of the desired termination requirements, such
- as whether they should accept (confirm) or reject (cancel) the work done within the scope of the given
- transaction. For example, a decision is needed for whether to purchase the provisionally reserved flight tickets
- for the user or to release them. An application may wish to terminate a transaction in a number of different ways
- (confirm or cancel). However, although the coordinator will attempt to terminate in a manner consistent with that
- desired by the client, the final outcome is ultimately determined by the interactions between the coordinator and
- the participants. </para> <para> A transaction manager is typically responsible for managing coordinators for
- many transactions. The initiator of the transaction (the client) communicates with a transaction manager and asks
- it to start a new transaction and associate a coordinator with the transaction. Once created, the context can be
- propagated to Web Services in order for them to associate their work with the transaction.
- -->
+ <para>
The coordinator is responsible for ensuring that the web services invoked
by the client arrive at a consistent outcome. When the client asks the
coordinator to complete the transaction, the coordinator ensures that each
@@ -137,284 +147,275 @@
started. The coordinator also reverts all changes if the client asks it to
cancel the transaction.
</para>
- <para>
+ <para>
The negotiation between the coordinator and the web services is organized to ensure that all services will make
their changes permanent, or all of them will revert to the previous state, even if the coordinator or one of the
web services crashes part of the way through the transaction."
</para>
- </section>
-
- <section>
- <title>The Transaction Context</title>
- <para>
- In order for a transaction to span a number of services, certain information has to be shared between those
- services, to propagate information about the transaction. This information is known as the
- <firstterm>Context</firstterm>. The coordination service hands a context back to the application client when it
- begins a transaction. This context is passed as an extra, hidden parameter whenever the client invokes a
- transactional web service. The XTS implementation saves and propagates this context automatically with only
- minimal involvement required on the part of the client. <!--Using XTS, the context is automatically propagated and
- processed by transaction-aware components of an application. Though XTS removes most of the work associated with
- propagating contexts,--> However, it is still helpful to understand what information is captured in a
- context. This information is listed in <xref linkend="context-contents" />.
+ </section>
+ <section>
+ <title>The Transaction Context</title>
+ <para>
+In order for a transaction to span a number of services, certain information has to be shared between those services in order to propagate information about the transaction. This information is known as the Context. The context is often automatically propagated and processed by transaction-aware components of an application:
</para>
-
- <variablelist id="context-contents">
- <title>Contents of a Context</title>
- <varlistentry>
- <term>Transaction Identifier</term>
- <listitem>
- <para>
+ <variablelist id="context-contents">
+ <title>Contents of a Context</title>
+ <varlistentry>
+ <term>Transaction Identifier</term>
+ <listitem>
+ <para>
Guarantees global uniqueness for an individual transaction.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Transaction Coordinator Location</term>
- <listitem>
- <para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Transaction Coordinator Location</term>
+ <listitem>
+ <para>
The endpoint address participants contact to enroll.
</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <figure>
- <title>Web Services and Context Flow</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/fig-web-services-context-flow.png" format="PNG"/>
- </imageobject>
- <textobject>
- <para>
- Whenever an application message is sent, the XTS Client API automatically creates a context and embeds it into
- the message. Similarly, any transaction-aware services can extract that context using the XTS service-side
- infrastructure and use it to perform work within the context of a particular transaction, even if that
- transaction was initiated elsewhere on the Web. The value of this approach is that the business logic contained
- within the client application and services are not peppered with transaction-processing code.
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <figure>
+ <title>Web Services and Context Flow</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/fig-web-services-context-flow.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <para>
+ As shown in Figure 1, whenever an application message is sent, the Client API automatically creates a context and embeds it into the message. Similarly, any transaction-aware services are able to extract that context using the service-side infrastructure and use it to perform work within the context of a particular transaction – even though that transaction was initiated elsewhere! The value of this approach is that the business logic contained within the client application and services are not peppered with transaction-processing code.
</para>
- </textobject>
- </mediaobject>
- </figure>
- </section>
-
- <section>
- <title>Participants</title>
- <para>
+ </textobject>
+ </mediaobject>
+ </figure>
+ </section>
+ <section>
+ <title>Participants</title>
+ <para>
The coordinator cannot know the details of how every transactional service is implemented. In fact this knowledge
is not even necessary for it to negotiate a transactional outcome. It treats each service taking part in a
transaction as a participant and communicates with it according to some predefined participant coordination models
- appropriate to the type of transaction. <!--When a service begins performing work within the scope of a
- transaction it enrolls itself with the coordinator as a participant, specifying the participant model it wishes to
- follow.--> When a web service receives its first service request in some given transaction, it enrolls with the
+ appropriate to the type of transaction. When a web service receives its first service request in some given transaction, it enrolls with the
coordinator as a participant, specifying the participant model it wishes to follow. The context contains a URL for
the endpoint of the coordination service which handles enrollment requests. So, the term participant merely refers
a transactional service enrolled in a specific transaction using a specific participant model.
</para>
- </section>
-
- <section>
- <title>ACID Transactions</title>
- <para>
+ </section>
+ <section>
+ <title>ACID Transactions</title>
+ <para>
Traditionally, transaction processing systems support <firstterm>ACID</firstterm> properties. ACID is an acronym
for <emphasis>A</emphasis>tomic, <emphasis>C</emphasis>onsistent, <emphasis>I</emphasis>solated, and
<emphasis>D</emphasis>urable. A unit of work has traditionally been considered transactional only if the ACID
- properties are maintained, as describe in <xref linkend="acid-properties" />.
+ properties are maintained, as describe in <xref linkend="acid-properties"/>.
</para>
-
- <variablelist id="acid-properties">
- <title>ACID Properties</title>
- <varlistentry>
- <term>Atomicity</term>
- <listitem>
- <para>
+ <variablelist id="acid-properties">
+ <title>ACID Properties</title>
+ <varlistentry>
+ <term>Atomicity</term>
+ <listitem>
+ <para>
The transaction executes completely, or not at all.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Consistency</term>
- <listitem>
- <para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Consistency</term>
+ <listitem>
+ <para>
The effects of the transaction preserve the internal consistency of an underlying data structure.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Isolated</term>
- <listitem>
- <para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Isolated</term>
+ <listitem>
+ <para>
The transaction runs as if it were running alone, with no other transactions running, and is not visible to other
transactions.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Durable</term>
- <listitem>
- <para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Durable</term>
+ <listitem>
+ <para>
The transaction's results are not lost in the event of a failure.
</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section>
- <title>Two Phase Commit</title>
-
- <para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+ <section>
+ <title>Two Phase Commit</title>
+ <para>
The classical two-phase commit approach is the bedrock of JBoss Transaction Service, and more generally of Web
Services transactions. Two-phase commit provides coordination of parties that are involved in a transaction. The
- general flow of a two-phase commit transaction is described in <xref linkend="two-phase-commit-overview" />.
+ general flow of a two-phase commit transaction is described in <xref linkend="two-phase-commit-overview"/>.
</para>
-
- <figure id="two-phase-commit-overview">
- <title>Two-Phase Commit Overview</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/fig-two-phase-commit-overview.png" format="PNG"/>
- </imageobject>
- <textobject>
- <itemizedlist>
- <listitem><para>A transaction is started, and some work is performed.</para></listitem>
- <listitem><para>Once the work is finished, the two-phase commit begins.</para></listitem>
- <listitem><para>The coordinator (transaction manager) of the transaction asks each resource taking part in the
- transaction whether it is prepared to commit.</para></listitem>
- <listitem><para>If all resources respond positively, the coordinator instructs the resources to make all work performed durable (usually committed to a database).</para></listitem>
- <listitem><para>If not, all work performed is rolled back (undone) such that the underlying data structures are
- in their original states.</para></listitem>
- </itemizedlist>
- </textobject>
- </mediaobject>
- </figure>
-
- <note>
- <para>
+ <figure id="two-phase-commit-overview">
+ <title>Two-Phase Commit Overview</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/fig-two-phase-commit-overview.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <itemizedlist>
+ <listitem>
+ <para>A transaction is started, and some work is performed.</para>
+ </listitem>
+ <listitem>
+ <para>Once the work is finished, the two-phase commit begins.</para>
+ </listitem>
+ <listitem>
+ <para>The coordinator (transaction manager) of the transaction asks each resource taking part in the
+ transaction whether it is prepared to commit.</para>
+ </listitem>
+ <listitem>
+ <para>If all resources respond positively, the coordinator instructs the resources to make all work performed durable (usually committed to a database).</para>
+ </listitem>
+ <listitem>
+ <para>If not, all work performed is rolled back (undone) such that the underlying data structures are
+ in their original states.</para>
+ </listitem>
+ </itemizedlist>
+ </textobject>
+ </mediaobject>
+ </figure>
+ <note>
+ <para>
During two-phase commit transactions, coordinators and resources keep track of activity in non-volatile data stores
so that they can recover in the case of a failure.
</para>
- </note>
-
- </section>
-
- <section>
- <title>The Synchronization Protocol</title>
- <para>
+ </note>
+ </section>
+ <section>
+ <title>The Synchronization Protocol</title>
+ <para>
Besides the two-phase commit protocol, traditional transaction processing systems employ an additional protocol,
often referred to as the <firstterm>synchronization protocol</firstterm>. With the original ACID properties,
Durability is important when state changes need to be available despite failures. Applications interact with a
persistence store of some kind, such as a database, and this interaction can impose a significant overhead,
because disk access is much slower to access than main computer memory.
</para>
- <para>
+ <para>
One solution to the problem disk access time is to cache the state in main memory and only operate on the cache
for the duration of a transaction. Unfortunately, this solution needs a way to flush the state back to the
persistent store before the transaction terminates, or risk losing the full ACID properties. This is what the
synchronization protocol does, with <firstterm>Synchronization Participants</firstterm>.
</para>
- <para>
+ <para>
Synchronizations are informed that a transaction is about to commit. At that point, they can flush cached state,
which might be used to improve performance of an application, to a durable representation prior to the transaction
committing. The synchronizations are then informed about when the transaction completes and its completion state.
</para>
-
- <procedure>
- <title>The "Four Phase Protocol" Created By Synchronizations</title>
- <para>
+ <procedure>
+ <title>The "Four Phase Protocol" Created By Synchronizations</title>
+ <para>
Synchronizations essentially turn the two-phase commit protocol into a four-phase protocol:
</para>
- <step>
- <title>Step 1</title>
- <para>
+ <step>
+ <title>Step 1</title>
+ <para>
Before the transaction starts the two-phase commit, all registered Synchronizations are informed. Any failure at
this point will cause the transaction to roll back.
</para>
- </step>
- <step>
- <title>Steps 2 and 3</title>
- <para>
+ </step>
+ <step>
+ <title>Steps 2 and 3</title>
+ <para>
The coordinator then conducts the normal two-phase commit protocol.
</para>
- </step>
- <step>
- <title>Step 4</title>
- <para>
+ </step>
+ <step>
+ <title>Step 4</title>
+ <para>
Once the transaction has terminated, all registered Synchronizations are informed. However, this is a courtesy
invocation because any failures at this stage are ignored: the transaction has terminated so there’s nothing to
affect.
</para>
- </step>
- </procedure>
- <para>
+ </step>
+ </procedure>
+ <para>
The synchronization protocol does not have the same failure requirements as the traditional two-phase commit
protocol. For example, Synchronization participants do not need the ability to recover in the event of failures,
because any failure before the two-phase commit protocol completes cause the transaction to roll back, and
failures after it completes have no effect on the data which the Synchronization participants are responsible for.
</para>
- </section>
-
- <section>
- <title>Optimizations to the Protocol</title>
- <para>
+ </section>
+ <section>
+ <title>Optimizations to the Protocol</title>
+ <para>
There are several variants to the standard two-phase commit protocol that are worth knowing about, because they
- can have an impact on performance and failure recovery. <xref linkend="two-phase-variants" /> gives more
+ can have an impact on performance and failure recovery. <xref linkend="two-phase-variants"/> gives more
information about each one.
</para>
- <table id="two-phase-variants">
- <title>Variants to the Two-Phase Commit Protocol</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry><para>Variant</para></entry>
- <entry><para>Description</para></entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><para>Presumed Abort</para></entry>
- <entry><para>If a transaction is going to roll back, the coordinator may record this information locally and tell
+ <table id="two-phase-variants">
+ <title>Variants to the Two-Phase Commit Protocol</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>
+ <para>Variant</para>
+ </entry>
+ <entry>
+ <para>Description</para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>Presumed Abort</para>
+ </entry>
+ <entry>
+ <para>If a transaction is going to roll back, the coordinator may record this information locally and tell
all enlisted participants. Failure to contact a participant has no effect on the transaction outcome. The
coordinator is informing participants only as a courtesy. Once all participants have been contacted, the
information about the transaction can be removed. If a subsequent request for the status of the transaction
occurs, no information will be available and the requester can assume that the transaction has aborted. This
optimization has the benefit that no information about participants need be made persistent until the transaction
has progressed to the end of the <systemitem>prepare</systemitem> phase and decided to commit, since any failure
- prior to this point is assumed to be an abort of the transaction.</para></entry>
- </row>
- <row>
- <entry><para>One-Phase</para></entry>
- <entry><para>If only a single participant is involved in the transaction, the coordinator does not need to drive
+ prior to this point is assumed to be an abort of the transaction.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>One-Phase</para>
+ </entry>
+ <entry>
+ <para>If only a single participant is involved in the transaction, the coordinator does not need to drive
it through the <systemitem>prepare</systemitem> phase. Thus, the participant is told to commit, and the
coordinator does not need to record information about the decision, since the outcome of the transaction is the
- responsibility of the participant.</para></entry>
- </row>
- <row>
- <entry><para>Read-Only</para></entry>
- <entry><para>When a participant is asked to prepare, it can indicate to the coordinator that no information or
+ responsibility of the participant.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>Read-Only</para>
+ </entry>
+ <entry>
+ <para>When a participant is asked to prepare, it can indicate to the coordinator that no information or
data that it controls has been modified during the transaction. Such a participant does not need to be informed
about the outcome of the transaction since the fate of the participant has no affect on the
transaction. Therefore, a read-only participant can be omitted from the second phase of the commit
- protocol.</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <note>
- <para>
- The WS-Atomic Transaction protocol does not support the one-phase commit optimization.
- </para>
- </note>
- </section>
-
- <section>
- <title>Non-Atomic Transactions and Heuristic Outcomes</title>
- <para>
+ protocol.</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+ <section>
+ <title>Non-Atomic Transactions and Heuristic Outcomes</title>
+ <para>
In order to guarantee atomicity, the two-phase commit protocol is <firstterm>blocking</firstterm>. As a result of
failures, participants may remain blocked for an indefinite period of time, even if failure recovery mechanisms
exist. Some applications and participants cannot tolerate this blocking.
</para>
- <para>
+ <para>
To break this blocking nature, participants that are past the <systemitem>prepare</systemitem> phase are allowed
to make autonomous decisions about whether to commit or rollback. Such a participant must record its decision, so
that it can complete the original transaction if it eventually gets a request to do so. If the coordinator
@@ -422,78 +423,93 @@
made, no conflict exists. If the decisions of the participant and coordinator are different, the situation is
referred to as a non-atomic outcome, and more specifically as a <firstterm>heuristic outcome</firstterm>.
</para>
- <para>
+ <para>
Resolving and reporting heuristic outcomes to the application is usually the domain of complex, manually driven
system administration tools, because attempting an automatic resolution requires semantic information about the
nature of participants involved in the transactions.
</para>
- <para>
+ <para>
Precisely when a participant makes a heuristic decision depends on the specific implementation. Likewise, the
choice the participant makes about whether to commit or to roll back depends upon the implementation, and possibly
the application and the environment in which it finds itself. The possible heuristic outcomes are discussed in
<xref linkend="tbl-heuristic-outcomes"/>.
</para>
-
- <table id="tbl-heuristic-outcomes">
- <title>Heuristic Outcomes</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry><para>Outcome</para></entry>
- <entry><para>Description</para></entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><para>Heuristic Rollback</para></entry>
- <entry><para>The commit operation failed because some or all of the participants unilaterally rolled back the
- transaction.</para></entry>
- </row>
- <row>
- <entry><para>Heuristic Commit</para></entry>
- <entry><para>An attempted rollback operation failed because all of the participants unilaterally committed. One
+ <table id="tbl-heuristic-outcomes">
+ <title>Heuristic Outcomes</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>
+ <para>Outcome</para>
+ </entry>
+ <entry>
+ <para>Description</para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>Heuristic Rollback</para>
+ </entry>
+ <entry>
+ <para>The commit operation failed because some or all of the participants unilaterally rolled back the
+ transaction.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>Heuristic Commit</para>
+ </entry>
+ <entry>
+ <para>An attempted rollback operation failed because all of the participants unilaterally committed. One
situation where this might happen is if the coordinator is able to successfully <systemitem>prepare</systemitem>
the transaction, but then decides to roll it back because its transaction log could not be updated. While the
- coordinator is making its decision, the participants decides to commit.</para></entry>
- </row>
- <row>
- <entry><para>Heuristic Mixed</para></entry>
- <entry><para>Some participants commit ed, while others were rolled back.</para></entry>
- </row>
- <row>
- <entry><para>Heuristic Hazard</para></entry>
- <entry><para>The disposition of some of the updates is unknown. For those which are known, they have either all
- been committed or all rolled back.</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>
+ coordinator is making its decision, the participants decides to commit.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>Heuristic Mixed</para>
+ </entry>
+ <entry>
+ <para>Some participants commit ed, while others were rolled back.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>Heuristic Hazard</para>
+ </entry>
+ <entry>
+ <para>The disposition of some of the updates is unknown. For those which are known, they have either all
+ been committed or all rolled back.</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
Heuristic decisions should be used with care and only in exceptional circumstances, since the decision may
possibly differ from that determined by the transaction service. This type of difference can lead to a loss of
integrity in the system. Try to avoid needing to perform resolution of heuristics, either by working with services
and participants that do not cause heuristics, or by using a transaction service that provides assistance in the
resolution process.
</para>
-
- </section>
-
- <section>
- <title>Interposition</title>
- <para>
- <firstterm>Interposition</firstterm> is a scoping mechanism which allows coordination of a transaction to be
- delegated across a hierarchy of coordinators. See <xref linkend="fig-interpositions" /> for a graphical
+ </section>
+ <section>
+ <title>Interposition</title>
+ <para><firstterm>Interposition</firstterm> is a scoping mechanism which allows coordination of a transaction to be
+ delegated across a hierarchy of coordinators. See <xref linkend="fig-interpositions"/> for a graphical
representation of this concept.
</para>
- <figure id="fig-interpositions">
- <title>Interpositions</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/fig-interpositions.png" format="PNG"/>
- </imageobject>
- <textobject>
- <para>
+ <figure id="fig-interpositions">
+ <title>Interpositions</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/fig-interpositions.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <para>
The diagram shows a <firstterm>top-level coordinator</firstterm> and an <firstterm>interposed
coordinator</firstterm>. The top-level coordinator is responsible for driving the original, top-level transaction
to completion or rollback. The interposed coordinator manages its participants in a subordinate transaction, but
@@ -502,97 +518,87 @@
incoming <systemitem>prepare</systemitem> and <systemitem>commit</systemitem>/<systemitem>rollback</systemitem>
messages to its participants, combining their responses and returning them back to its parent coordinator.
</para>
- </textobject>
- </mediaobject>
- </figure>
-
- <para>
+ </textobject>
+ </mediaobject>
+ </figure>
+ <para>
Interposition is particularly useful for Web Services transactions, as a way of limiting the amount of network
traffic required for coordination. For example, if communications between the top-level coordinator and a web
service are slow because of network traffic or distance, the web service might benefit from executing in a
- subordinate transaction which employs a local coordinator service. In <xref linkend="fig-interpositions" />,to
+ subordinate transaction which employs a local coordinator service. In <xref linkend="fig-interpositions"/>,to
<systemitem>prepare</systemitem>, the top-level coordinator only needs to send one
<systemitem>prepare</systemitem> message to the subordinate coordinator, and receive one
<systemitem>prepared</systemitem> or <systemitem>aborted</systemitem> reply. The subordinate coordinator forwards
a <systemitem>prepare</systemitem> locally to each participant and combines the results to decide whether to send
a single <systemitem>prepared</systemitem> or <systemitem>aborted</systemitem> reply.
</para>
- </section>
-
- <section>
- <title>A New Transaction Protocol</title>
-
- <para>
+ </section>
+ <section>
+ <title>A New Transaction Protocol</title>
+ <para>
Many component technologies offer mechanisms for coordinating ACID transactions based on two-phase commit
semantics. Some of these are CORBA/OTS, JTS/JTA, and MTS/MSDTC. ACID transactions are not suitable for all Web
- Services transactions, as explained in <xref linkend="acid-not-suitable" />.
+ Services transactions, as explained in <xref linkend="acid-not-suitable"/>.
</para>
-
- <itemizedlist id="acid-not-suitable">
- <title>Reasons ACID is Not Suitable for Web Services</title>
- <listitem>
- <para>
+ <itemizedlist id="acid-not-suitable">
+ <title>Reasons ACID is Not Suitable for Web Services</title>
+ <listitem>
+ <para>
Classic ACID transactions assume that an organization that develops and deploys applications owns the entire
infrastructure for the applications. This infrastructure has traditionally taken the form of an Intranet. Ownership
implies that transactions operate in a trusted and predictable manner. To assure ACIDity, potentially long-lived
locks can be kept on underlying data structures during two-phase commit. Resources can be used for any period of
time and released when the transaction is complete.
</para>
- <para>
+ <para>
In Web Services, these assumptions are no longer valid. One obvious reason is that the owners of data exposed
through a Web service refuse to allow their data to be locked for extended periods, since allowing such locks
invites denial-of-service attacks.
</para>
- </listitem>
- <listitem>
- <para>
+ </listitem>
+ <listitem>
+ <para>
All application infrastructures are generally owned by a single party. Systems using classical ACID transactions
normally assume that participants in a transaction will obey the directives of the transaction manager and only
infrequently make unilateral decisions which harm other participants in a transaction.
</para>
- <para>
+ <para>
Web Services participating in a transaction can effectively decide to resign from the transaction at any time, and
the consumer of the service generally has little in the way of quality of service guarantees to prevent this.
</para>
- </listitem>
- </itemizedlist>
-
- <section>
- <title>Transaction in Loosely Coupled Systems</title>
-
- <para>
- Extended transaction models which relax the ACID properties have been proposed over the years. WS-T provides a new
- transaction protocol to implement these concepts for the Web Services architecture. XTS is designed to accommodate
- four underlying requirements inherent in any loosely coupled architecture like Web Services. These requirements are
- discussed in <xref linkend="web-services-requirements" />.
+ </listitem>
+ </itemizedlist>
+ <section>
+ <title>Addressing the Problems of Transactioning in Loosely Coupled Systems</title>
+ <para>
+ Though extended transaction models which relax the ACID properties have been proposed over the years, standards such as OASIS WS-TX provide a new transaction protocol to implement these concepts for the Web services architecture. The are designed to accommodate four underlying requirements inherent in any loosely coupled architecture like Web services:.
</para>
- <itemizedlist id="web-services-requirements">
- <title>Requirements of Web Services</title>
- <listitem>
- <para>
+ <itemizedlist id="web-services-requirements">
+ <title>Requirements of Web Services</title>
+ <listitem>
+ <para>
Ability to handle multiple successful outcomes to a transaction, and to involve operations whose effects may not
be isolated or durable.
</para>
- </listitem>
- <listitem>
- <para>
+ </listitem>
+ <listitem>
+ <para>
Coordination of autonomous parties whose relationships are governed by contracts, rather than the dictates of a
central design authority.
</para>
- </listitem>
- <listitem>
- <para>
+ </listitem>
+ <listitem>
+ <para>
Discontinuous service, where parties are expected to suffer outages during their lifetimes, and coordinated work
must be able to survive such outages.
</para>
- </listitem>
- <listitem>
- <para>
+ </listitem>
+ <listitem>
+ <para>
Interoperation using XML over multiple communication protocols. XTS uses SOAP encoding carried over HTTP.
</para>
- </listitem>
- </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </section>
</section>
- </section>
</chapter>
-
Modified: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Transactions_Overview_Guide.xml
===================================================================
--- labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Transactions_Overview_Guide.xml 2011-04-12 10:51:00 UTC (rev 36888)
+++ labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Transactions_Overview_Guide.xml 2011-04-12 11:27:04 UTC (rev 36889)
@@ -6,9 +6,7 @@
<book>
<xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <!-- <xi:include href="Chapter.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />-->
<xi:include href="Transactions_Overview.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-
<xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<index />
</book>
Deleted: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/XTS_API.xml
===================================================================
--- labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/XTS_API.xml 2011-04-12 10:51:00 UTC (rev 36888)
+++ labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/XTS_API.xml 2011-04-12 11:27:04 UTC (rev 36889)
@@ -1,743 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "Transactions_XTS_Administration_And_Development_Guide.ent">
-%BOOK_ENTITIES;
-]>
-<chapter id="sec-xts-api">
-
- <title>The XTS API</title>
-
- <indexterm><primary>vote</primary></indexterm>
- <indexterm><primary>TXContext</primary></indexterm>
- <indexterm><primary>UserTransaction</primary></indexterm>
- <indexterm><primary>UserTransactionFactory</primary></indexterm>
- <indexterm><primary>TransactionManager</primary></indexterm>
- <indexterm><primary>TransactionManagerFactory</primary></indexterm>
- <indexterm><primary>UserBusinessActivity</primary></indexterm>
- <indexterm><primary>UserBusinessActivityFactory</primary></indexterm>
- <indexterm><primary>BusinessActivityManager</primary></indexterm>
- <indexterm><primary>BusinessActivityManagerFactory</primary></indexterm>
- <indexterm><primary>API</primary></indexterm>
-
-
- <para>
- This chapter discusses the XTS API. You can use this information to write client and server applications which
- consume transactional Web Services and coordinate back-end systems.
- </para>
-
- <section>
- <title>API for the Atomic Transaction Protocol</title>
-
- <section>
- <title>Vote</title>
- <para>
- During the two-phase commit protocol, a participant is asked to vote on whether it can prepare to confirm the work
- that it controls. It must return an instance of one of the subtypes of
- <interfacename>com.arjuna.wst11.Vote</interfacename> listed in <xref linkend="vote-subclasses" />.
- </para>
- <variablelist id="vote-subclasses">
- <title>Subclasses of <interfacename>com.arjuna.wst11.Vote</interfacename></title>
- <varlistentry>
- <term>Prepared</term>
- <listitem>
- <para>
- Indicates that the participant can can prepare if the coordinator requests it. Nothing has been committed,
- because the participant does not know the final outcome of the transaction.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Aborted</term>
- <listitem>
- <para>
- The participant cannot prepare, and has rolled back. The participant should not expect to get a second phase
- message.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>ReadOnly</term>
- <listitem>
- <para>
- The participant has not made any changes to state, and it does not need to know the final outcome of the
- transaction. Essentially the participant is resigning from the transaction.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <example>
- <title>Example Implementation of 2PC Participant's <methodname>prepare</methodname> Method</title>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/example-prepare-method.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
- </section>
-
-
- <section>
- <title>TXContext</title>
- <!-- Unsupported in 1.0 and 1.1 <para> A transaction is typically represented by a unique identifier and a
- reference to the coordinator which manages the transaction. This reference usually takes the form oa
- URL. With XTS, transactions to be nested in a nested tree structure. Thus, a transaction context may be a set
- of transactions, with the top-most transaction the root parent. </para>
- -->
- <para>
- <package>com.arjuna.mw.wst11.TxContext</package> is an opaque representation of a transaction context. It returns one
- of two possible values, as listed in <xref linkend="TxContext-values" />.
- </para>
- <variablelist id="TxContext-values">
- <title>TxContext Return Values</title>
- <varlistentry>
- <term>valid</term>
- <listitem>
- <para>
- Indicates whether the contents are valid.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>equals</term>
- <listitem>
- <para>
- Can be used to compare two instances for equality.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <note>
- <para>
- The corresponding participant interfaces used in the 1.0 protocol implementation are located in package
- <package>com.arjuna.wst</package>.
- </para>
- </note>
- </section>
-
- <section id="ref-UserTransaction">
- <title>UserTransaction</title>
- <para>
- <classname>com.arjuna.mw.wst11.UserTransaction</classname> is the class that clients typically employ. Before a
- client can begin a new atomic transaction, it must first obtain a <classname>UserTransaction</classname> from the
- <classname>UserTransactionFactory</classname>. This class isolates the user from the underlying protocol-specific
- aspects of the XTS implementation. A <classname>UserTransaction</classname> does not represent a specific
- transaction. Instead, it provides access to an implicit per-thread transaction context, similar to the
- <classname>UserTransaction</classname> in the JTA specification. All of the <classname>UserTransaction</classname>
- methods implicitly act on the current thread of control.
- </para>
- <variablelist>
- <title><classname>userTransaction</classname> Methods</title>
- <varlistentry>
- <term>begin</term>
- <listitem>
- <para>
- Used to begin a new transaction and associate it with the invoking thread.
- </para>
- <variablelist>
- <title>Parameters</title>
- <varlistentry>
- <term>timeout</term>
- <listitem>
- <!--
- <para> This optional parameter, measured in milliseconds, causes the <methodname>begin</methodname> method to
- time out. </para>
- -->
- <para>
- This optional parameter, measured in milliseconds, specifies a time interval after which the newly created
- transaction may be automatically rolled back by the coordinator
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <title>Exceptions</title>
- <varlistentry>
- <term><systemitem>WrongStateException</systemitem></term>
- <listitem>
- <para>
- A transaction is already associated with the thread.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>commit</term>
- <listitem>
- <para>
- <!--
- Commits the transaction. The <methodname>commit</methodname> method executes the Volatile2PC and Durable2PC
- protocols before returning. When complete, the <methodname>commit</methodname> method disassociates the
- transaction from the current thread, leaving it unassociated with any transactions.
- -->
- Volatile2PC and Durable2PC participants enrolled in the transaction
- are requested first to prepare and then to commit their changes. If
- any of the participants fails to prepare in the first phase then all
- other participants are requested to abort.
- </para>
- <variablelist>
- <title>Exceptions</title>
- <varlistentry>
- <term><systemitem>UnknownTransactionException</systemitem></term>
- <listitem>
- <para>
- No transaction is associated with the invoking thread.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>TransactionRolledBackException</methodname></term>
- <listitem>
- <para>
- <!--
- The transaction rolled back, due to another participant.
- -->
- The transaction was rolled back either because of a timeout or
- because a participant was unable to commit.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>rollback</term>
- <listitem>
- <para>
- Terminates the transaction. Upon completion, the <methodname>rollback</methodname> method disassociates the
- transaction from the current leaving it unassociated with any transactions.
- </para>
- <variablelist>
- <title>Exceptions</title>
- <varlistentry>
- <term><systemitem>UnknownTransactionException</systemitem></term>
- <listitem>
- <para>
- No transaction is associated with the invoking thread.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section>
- <title>UserTransactionFactory</title>
- <para>
- Call the <methodname>getUserTransaction</methodname> method to obtain a <xref linkend="ref-UserTransaction" />
- instance from a <classname>UserTransactionFactory</classname>.
- </para>
- </section>
-
- <section id="ref-TransactionManager">
- <title>TransactionManager</title>
- <para>
- Defines the interaction between a transactional web service and the underlying transaction service implementation. A
- <classname>TransactionManager</classname> does not represent a specific transaction. Instead, it provides access to
- an implicit per-thread transaction context.
- </para>
- <variablelist>
- <title>Methods</title>
- <varlistentry>
- <term><methodname>currentTransaction</methodname></term>
- <listitem>
- <para>
- Returns a <systemitem>TxContext</systemitem> for the current transaction, or null if there is no context. Use
- the <methodname>currentTransaction</methodname> method to determine whether a web service has been invoked from
- within an existing transaction. You can also use the returned value to enable multiple threads to execute
- within the scope of the same transaction. Calling the <methodname>currentTransaction</methodname> method does
- not disassociate the current thread from the transaction.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>suspend</methodname></term>
- <listitem>
- <para>
- Dissociates a thread from any transaction. This enables a thread to do work that is not associated with a
- specific transaction.
- </para>
- <para>The <methodname>suspend</methodname> method returns a <systemitem>TxContext</systemitem> instance, which is a handle on the transaction.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>resume</methodname></term>
- <listitem>
- <para>
- Associates or re-associates a thread with a transaction, using its <systemitem>TxContext</systemitem>. Prior to
- association or re-association, the thread is disassociated from any transaction with which it may be currently
- associated. If the <systemitem>TxContext</systemitem> is null, then the thread is associated with no
- transaction. In this way, the result is the same as if the <methodname>suspend</methodname> method were used
- instead.
- </para>
- <variablelist>
- <title>Parameters</title>
- <varlistentry>
- <term>txContext</term>
- <listitem>
- <para>
- A TxContext instance as return by <methodname>suspend</methodname>, identifying the transaction to be resumed.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <title>Exceptions</title>
- <varlistentry>
- <term><systemitem>UnknownTransactionException</systemitem></term>
- <listitem>
- <para>
- The transaction referred to by the <systemitem>TxContext</systemitem> is invalid in the scope of the invoking
- thread.
- </para>
- </listitem>
- </varlistentry>
- <!--
- <varlistentry> <term><systemitem>WrongStateException</systemitem></term> <listitem> <para> The transaction is
- not in a state that allows participants to be enrolled. For instance, it may be in the process of terminating.
- </para> </listitem> </varlistentry>
- -->
- </variablelist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><varname>enlistForVolitaleTwoPhase</varname></term>
- <listitem>
- <para>
- Enroll the specified participant with the current transaction, causing it to participate in the Volatile2PC
- protocol. You must pass a unique identifier for the participant.
- </para>
- <variablelist>
- <title>Parameters</title>
- <varlistentry>
- <term>participant</term>
- <listitem>
- <para>
- An implementation of interface Volatile2PCParticipant whose prepare, commit and abort methods are called when
- the corresponding coordinator message is received.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>id</term>
- <listitem>
- <para>
- A unique identifier for the participant. The value of this String should differ for each enlisted
- participant. It should also be possible for a given identifier to determine that the participant belongs to
- the enlisting web service rather than some other web service deployed to the same container.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <title>Exceptions</title>
- <varlistentry>
- <term>UnknownTransactionException</term>
- <listitem>
- <para>
- No transaction is associated with the invoking thread.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><systemitem>WrongStateException</systemitem></term>
- <listitem>
- <para>
- The transaction is not in a state that allows participants to be enrolled. For instance, it may be in the
- process of terminating.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><varname>enlistForDurableTwoPhase</varname></term>
- <listitem>
- <para>
- Enroll the specified participant with the current transaction, causing it to participate in the Durable2PC
- protocol. You must pass a unique identifier for the participant.
- </para>
- <variablelist>
- <title>Exceptions</title>
- <varlistentry>
- <term>UnknownTransactionException</term>
- <listitem>
- <para>
- No transaction is associated with the invoking thread.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><systemitem>WrongStateException</systemitem></term>
- <listitem>
- <para>
- The transaction is not in a state that allows participants to be enrolled. For instance, it may be in the
- process of terminating.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section>
- <title>TransactionManagerFactory</title>
- <para>
- Use the <methodname>getTransactionManager</methodname> method to obtain a <xref linkend="ref-TransactionManager" />
- from a <classname>TransactionManagerFactory</classname>.
- </para>
- </section>
- </section>
-
- <section>
-
- <title>API for the Business Activity Protocol</title>
-
- <section>
- <title>Compatibility</title>
- <para>
- Previous implementations of XTS locate the Business Activity Protocol classes in the
- <package>com.arjuna.mw.wst</package> package. In the current implementation, these classes are located in the
- <package>com.arjuna.mw.wst11</package> package.
- </para>
- </section>
-
- <section id="ref-UserBusinessActivity">
- <title>UserBusinessActivity</title>
- <para>
- <classname>com.arjuna.wst11.UserBusinessActivity</classname> is the class that most clients employ. A client begins a
- new business activity by first obtaining a <classname>UserBusinessActivity</classname> from the
- <classname>UserBusinessActivityFactory</classname>. This class isolates them from the underlying protocol-specific
- aspects of the XTS implementation. A UserBusinessActivity does not represent a specific business activity. Instead,
- it provides access to an implicit per-thread activity. Therefore, all of the
- <classname>UserBusinessActivity</classname> methods implicitly act on the current thread of control.
- </para>
- <variablelist>
- <title>Methods</title>
- <varlistentry>
- <term><methodname>begin</methodname></term>
- <listitem>
- <para>
- Begins a new activity, associating it with the invoking thread.
- </para>
- <variablelist>
- <title>Parameters</title>
- <varlistentry>
- <term>timeout</term>
- <listitem>
- <para>
- The interval, in milliseconds, after which an activity times out. Optional.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <title>Exceptions</title>
- <varlistentry>
- <term><systemitem>WrongStateException</systemitem></term>
- <listitem>
- <para>
- The thread is already associated with a business activity.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>close</methodname></term>
- <listitem>
- <!--
- <para> Terminates the business activity. The <methodname>close</methodname> method executes the
- <systemitem>BusinessAgreementWithParticipantCompletion</systemitem> protocol and then returns, dissociating the
- business activity from the current thread, so that it is not associated with any activity. </para>
- -->
- <para>
- First, all Coordinator Completion participants enlisted in the activity are requested to complete the
- activity. Next all participants, whether they enlisted for Coordinator or Participant Completion, are requested
- to close the activity. If any of the Coordinator Completion participants fails to complete at the first stage
- then all completed participants are asked to compensate the activity while any remaining uncompleted
- participants are requested to cancel the activity.
- </para>
- <variablelist>
- <title>Exceptions</title>
- <varlistentry>
- <term>UnknownTransactionException</term>
- <listitem>
- <para>
- No activity is associated with the invoking thread.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>TransactionRolledBackException</term>
- <listitem>
- <para>
- The activity has been cancelled because one of the Coordinator Completion participants failed to
- complete. This exception may also thrown if one of the Participant Completion participants has not completed
- before the client calls close.
- </para>
- <!--
- <para> The activity has canceled. </para>
- -->
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>cancel</term>
- <listitem>
- <!--
- <para> Terminates the business activity. After the <methodname>cancel</methodname> method completes, </para>
- -->
- <para>
- Terminates the business activity. All Participant Completion participants enlisted in the activity which have
- already completed are requested to compensate the activity. All uncompleted Participant Completion participants
- and all Coordinator Completion participants are requested to cancel the activity.
- </para>
- <variablelist>
- <title>Exceptions</title>
- <varlistentry>
- <term><systemitem>UnknownTransactionException</systemitem></term>
- <listitem>
- <para>
- No activity is associated with the invoking thread. Any participants that previous completed are directed to
- compensate their work.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
- </variablelist>
- <!--
- <para> In some cases participants in a business activity may register for the
- <systemitem>BusinessAgreementWithCoordinatorCompletion</systemitem> protocol. In this case, the coordinator needs
- to notify them that all the work that they need to do within the scope of a business activity is complete. When
- the the client application has finished requesting work to be done by these participants, it must call the
- <methodname>complete</methodname> method before attempting to call the <methodname>close</methodname> or
- <methodname>cancel</methodname> methods. </para>
- -->
- </section>
-
-
- <section>
- <title>UserBusinessActivityFactory</title>
- <para>
- Use the <methodname>getuserbusinessActivity</methodname> method to obtain a <xref linkend="ref-UserBusinessActivity"
- /> instance from a <classname>userBusinessActivityFactory</classname>.
- </para>
- </section>
-
- <section id="ref-BusinessActivityManager">
- <title>BusinessActivityManager</title>
- <para>
- <package>com.arjuna.mw.wst11.BusinessActivityManager</package> is the class that web services typically
- employ. Defines how a web service interacts with the underlying business activity service implementation. A
- <classname>BusinessActivityManager</classname> does not represent a specific activity. Instead, it provides access to
- an implicit per-thread activity.
- </para>
- <variablelist>
- <title>Methods</title>
- <varlistentry>
- <term><methodname>currentTransaction</methodname></term>
- <listitem>
- <para>
- Returns the <systemitem>TxContext</systemitem> for the current business activity, or <literal>NULL</literal> if
- there is no <systemitem>TxContext</systemitem>. The returned value can be used to enable multiple threads to
- execute within the scope of the same business activity. Calling the <methodname>currenTransaction</methodname>
- method does not dissociate the current thread from its activity.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>suspend</methodname></term>
- <listitem>
- <para>
- Dissociates a thread from any current business activity, so that it can perform work not associated with a
- specific activity. The <methodname>suspend</methodname> method returns a <systemitem>TxContext</systemitem>
- instance, which is a handle on the activity. The thread is then no longer associated with any activity.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>resume</methodname></term>
- <listitem>
- <para>
- Associates or re-associates a thread with a business activity, using its
- <systemitem>TxContext</systemitem>. Before associating or re-associating the thread, it is disassociated from
- any business activity with which it is currently associated. If the <systemitem>TxContext</systemitem> is
- <literal>NULL</literal>, the thread is disassociated with all business activities, as though the
- <methodname>suspend</methodname> method were called.
- </para>
- <variablelist>
- <title>Parameters</title>
- <varlistentry>
- <term>txContext</term>
- <listitem>
- <para>
- A TxContext instance as returned by <methodname>suspend</methodname>, identifying the transaction to be
- resumed.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <variablelist>
- <title>Exceptions</title>
- <varlistentry>
- <term><systemitem>UnknownTransactionException</systemitem></term>
- <listitem>
- <para>
- The business activity to which the <systemitem>TxContext</systemitem> refers is invalid in the scope of the
- invoking thread.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><varname>enlistForBusinessAgreementWithParticipantCompletion</varname></term>
- <listitem>
- <para>
- Enroll the specified participant with current business activity, causing it to participate in the
- <systemitem>BusinessAgreementWithParticipantCompletion</systemitem> protocol. A unique identifier for the
- participant is also required.
- </para>
- <para>
- The return value is an instance of BAParticipantManager which can be used to notify the coordinator of changes
- in the participant state. In particular, since the participant is enlisted for the Participant Completion
- protcol it is expected to call the completed method of this returned instance when it has completed all the
- work it expects to do in this activity and has made all its changes permanent. Alternatively, if the
- participant does not need to perform any compensation actions should some other participant fail it can leave
- the activity by calling the exit method of the returned BAParticipantManager instance.
- </para>
- <variablelist>
- <title>Parameters</title>
- <varlistentry>
- <term>participant</term>
- <listitem>
- <para>
- An implementation of interface
- <interfacename>BusinessAgreementWithParticipantCompletionParticipant</interfacename> whose
- <methodname>close</methodname>, <methodname>cancel</methodname>, and <methodname>compensate</methodname>
- methods are called when the corresponding coordinator message is received.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>id</term>
- <listitem>
- <para>
- A unique identifier for the participant. The value of this String should differ for each enlisted
- participant. It should also be possible for a given identifier to determine that the participant belongs to
- the enlisting web service rather than some other web service deployed to the same container.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <title>Exceptions</title>
- <varlistentry>
- <term>UnknownTransactionException</term>
- <listitem>
- <para>
- No transaction is associated with the invoking thread.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>WrongStateException</term>
- <listitem>
- <para>
- The transaction is not in a state where new participants may be enrolled, as when it is terminating.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><varname>enlistForBusinessAgreementWithCoordinatorCompletion</varname></term>
- <listitem>
- <para>
- Enroll the specified participant with current activity, causing it to participate in the
- <systemitem>BusinessAgreementWithCoordinatorCompletion</systemitem> protocol. A unique identifier for the
- participant is also required.
- </para>
- <para>
- The return value is an instance of <interfacename>BAParticipantManager</interfacename> which can be used to
- notify the coordinator of changes in the participant state. Note that in this case it is an error to call the
- <methodname>completed</methodname> method of this returned instance. With the Coordinator Completion protocol
- the participant is expected to wait until its <methodname>completed</methodname> method is called before it
- makes all its changes permanent. Alternatively, if the participant determiens that it has no changes to make,
- it can leave the activity by calling the <methodname>exit</methodname> method of the returned
- <interfacename>BAParticipantManager</interfacename> instance.
- </para>
- <variablelist>
- <title>Parameters</title>
- <varlistentry>
- <term>participant</term>
- <listitem>
- <para>
- An implementation of interface BusinessAgreementWithCoordinatorCompletionParticipant whose completed, close,
- cancel and compensate methods are called when the corresponding coordinator message is received.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>id</term>
- <listitem>
- <para>
- A unique identifier for the participant. The value of this String should differ for each enlisted
- participant. It should also be possible for a given identifier to determine that the participant belongs to
- the enlisting web service rather than some other web service deployed to the same container.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <title>Exceptions</title>
- <varlistentry>
- <term>UnknownTransactionException</term>
- <listitem>
- <para>
- No transaction is associated with the invoking thread.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>WrongStateException</term>
- <listitem>
- <para>
- The transaction is not in a state where new participants may be enrolled, as when it is terminating.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section>
- <title>BusinessActivityManagerFactory</title>
- <para>
- Use the <methodname>getBusinessActivityManager</methodname> method to obtain a <xref
- linkend="ref-BusinessActivityManager" /> instance from a <classname>BusinessActivityManagerFactory</classname>.
- </para>
- </section>
- </section>
-
-</chapter>
-
Deleted: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/images/fig-2pc-participant-state-transitions.png
===================================================================
(Binary files differ)
Deleted: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/images/fig-at-model.png
===================================================================
(Binary files differ)
Deleted: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/images/fig-back-end-pattern.png
===================================================================
(Binary files differ)
Deleted: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/images/fig-bawcc-state-transitions.png
===================================================================
(Binary files differ)
Deleted: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/images/fig-bawpc-state-transitions.png
===================================================================
(Binary files differ)
Deleted: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/images/fig-context-handlers-registered-with-soap-server.png
===================================================================
(Binary files differ)
Deleted: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/images/fig-participant-backend-control.png
===================================================================
(Binary files differ)
Deleted: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/images/fig-web-services-transaction.png
===================================================================
(Binary files differ)
Deleted: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/images/fig-ws-c-overview.png
===================================================================
(Binary files differ)
Deleted: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/images/fig-ws-trans-services-participants.png
===================================================================
(Binary files differ)
Deleted: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/images/fig-wsc-four-roles.png
===================================================================
(Binary files differ)
Deleted: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/images/fig-wsc-wst-interop.png
===================================================================
(Binary files differ)
Deleted: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/images/ws-trans-global-view.png
===================================================================
(Binary files differ)
More information about the jboss-svn-commits
mailing list