[jboss-svn-commits] JBL Code SVN: r36888 - in labs/jbosstm/trunk/docs: transactions_overview_guide and 1 other directories.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Tue Apr 12 06:51:00 EDT 2011
Author: tomjenkinson
Date: 2011-04-12 06:51:00 -0400 (Tue, 12 Apr 2011)
New Revision: 36888
Added:
labs/jbosstm/trunk/docs/transactions_overview_guide/
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Transactions_Overview_Guide.ent
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Transactions_Overview_Guide.xml
Removed:
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Chapter.xml
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Getting_Started.xml
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Participant_Crash_Recovery.xml
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Participants.xml
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Protocols_Overview.xml
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Stand_Alone_Coordination.xml
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Transactions_XTS_Administration_And_Development_Guide.ent
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Transactions_XTS_Administration_And_Development_Guide.xml
labs/jbosstm/trunk/docs/transactions_overview_guide/publican-maven.cfg
Modified:
labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Revision_History.xml
labs/jbosstm/trunk/docs/transactions_overview_guide/publican.cfg
Log:
JBTM-700 first guide attempt
Deleted: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Chapter.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/Transactions_XTS_Administration_And_Development_Guide/en-US/Chapter.xml 2011-04-12 04:47:52 UTC (rev 36887)
+++ labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Chapter.xml 2011-04-12 10:51:00 UTC (rev 36888)
@@ -1,33 +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="chap-Transactions_XTS_Programmers_Guide-Test_Chapter">
- <title>Test Chapter</title>
- <para>
- This is a test paragraph
- </para>
- <section id="sect-Transactions_XTS_Programmers_Guide-Test_Chapter-Test_Section_1">
- <title>Test Section 1</title>
- <para>
- This is a test paragraph in a section
- </para>
- </section>
-
- <section id="sect-Transactions_XTS_Programmers_Guide-Test_Chapter-Test_Section_2">
- <title>Test Section 2</title>
- <para>
- This is a test paragraph in Section 2
- <orderedlist>
- <listitem>
- <para>
- listitem text
- </para>
- </listitem>
- </orderedlist>
- </para>
- </section>
-
-</chapter>
-
Deleted: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Getting_Started.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/Transactions_XTS_Administration_And_Development_Guide/en-US/Getting_Started.xml 2011-04-12 04:47:52 UTC (rev 36887)
+++ labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Getting_Started.xml 2011-04-12 10:51:00 UTC (rev 36888)
@@ -1,338 +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>Getting Started</title>
-
- <indexterm><primary>user transactions</primary></indexterm>
- <indexterm><primary>business activities</primary></indexterm>
- <indexterm><primary>context handlers</primary></indexterm>
- <indexterm><primary>participants</primary></indexterm>
- <indexterm><primary>service-side handlers</primary></indexterm>
- <indexterm><primary>JAX-RPC</primary></indexterm>
- <indexterm><primary>com.arjuna.mw.wst11</primary><secondary>XTS API</secondary></indexterm>
-
-
- <section>
- <title>Installing the XTS Service Archive into JBoss Transaction Service</title>
- <para>
- XTS, which is the Web Services component of JBoss Transaction Service, provides WS-AT and WS-BA support for Web
- Services hosted on the &APPSERVER;. The module is packaged as a <firstterm>Service Archive (.sar)</firstterm>
- located in <filename><replaceable>$JBOSS_HOME</replaceable>/docs/examples/transactions/</filename>. To install it,
- follow <xref linkend="procedure-install-xts" />.
- </para>
-
- <procedure id="procedure-install-xts">
- <title>Installing the XTS Module</title>
- <step>
- <para>
- Create a sub-directory in the
- <filename><replaceable>$JBOSS_HOME</replaceable>/server/[<replaceable>name</replaceable>]/deploy/</filename>
- directory, called <filename>jbossxts.sar/</filename>.
- </para>
- </step>
- <step>
- <para>
- Unpack the SAR, which is a ZIP archive, into this new directory.
- </para>
- </step>
- <step>
- <para>
- Restart &APPSERVER; to activate the module.
- </para>
- </step>
- </procedure>
- </section>
-
- <section>
- <title>Creating Client Applications</title>
-
- <para>
- There are two aspects to a client application using XTS, the transaction declaration aspects, and the business
- logic. The business logic includes the invocation of Web Services.
- </para>
- <para>
- Transaction declaration aspects are handled automatically with the XTS client API. This API provides simple
- transaction directives such as <methodname>begin</methodname>, <methodname>commit</methodname>, and
- <methodname>rollback</methodname>, which the client application can use to initialize, manage, and terminate
- transactions. Internally, this API uses SOAP to invoke operations on the various WS-C, WS-AT and WS-BA services,
- in order to create a coordinator and drive the transaction to completion.
- </para>
-
- <section>
- <title>User Transactions</title>
- <para>
- A client uses the <classname>UserTransactionFactory</classname> and <classname>UserTransaction</classname> classes to
- create and manage WS-AT transactions. These classes provide a simple API which operates in a manner similar to the
- JTA API. A WS-AT transaction is started and associated with the client thread by calling the
- <methodname>begin</methodname> method of the <methodname>UserTransaction</methodname> class. The transaction can be
- committed by calling the <methodname>commit</methodname> method, and rolled back by calling the
- <methodname>rollback</methodname> method.
- </para>
- <para>
- More complex transaction management, such as suspension and resumption of transactions, is supported by the
- <classname>TransactionManagerFactory</classname> and <classname>TransactionManager</classname> classes.
- </para>
- <para>
- Full details of the WS-AT APIs are provided in <xref linkend="sec-xts-api" />.
- </para>
- </section>
-
- <section>
- <title>Business Activities</title>
-
- <para>
- A client creates and manages Business Activities using the <classname>UserBusinessActivityFactory</classname> and
- <classname>UserBusinessActivity</classname> classes. A WS-BA activity is started and associated with the client
- thread by calling the <methodname>begin</methodname> method of the <methodname>UserBusinessActivity</methodname>
- class. A client can terminate a business activity by calling the <methodname>close</methodname> method, and cancel it
- by calling the <methodname>cancel</methodname> method.
- </para>
- <para>
- If any of the Web Services invoked by the client register for the
- <systemitem>BusinessActivityWithCoordinatorCompletion</systemitem> protocol, the client can call the
- <methodname>completed</methodname> method before calling the <methodname>close</methodname> method, to notify the
- services that it has finished making service invocations in the current activity.
- </para>
- <para>
- More complex business activity management, such as suspension and resumption of business activities, is supported by
- the <classname>BusinessActivityManagerFactory</classname> and <classname>BusinessActivityManager</classname> classes.
- </para>
- <para>
- Full details of the WS-AT APIs are provided in <xref linkend="sec-xts-api" />.
- </para>
- </section>
-
- <section>
- <title>Client-Side Handler Configuration</title>
-
- <para>
- XTS does not require the client application to use a specific API to perform invocations on transactional Web
- Services. The client is free to use any appropriate API to send SOAP messages to the server and receive SOAP
- responses. The only requirements imposed on the client are:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- It must forward details of the current transaction to the server when invoking a web service.
- </para>
- </listitem>
- <listitem>
- <para>
- It must process any responses from the server in the context of the correct transaction.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- In order to achieve this, the client must insert details of the current XTS context into the headers of outgoing SOAP
- messages, and extract the context details from the headers of incoming messages and associate the context with the
- current thread. To simplify this process, the XTS module includes handlers which can perform this task
- automatically. These handlers are designed to work with JAX-WS clients.
- </para>
-
- <note>
- <para>
- If you choose to use a different SOAP client/server infrastructure for business service invocations, you must
- provide for header processing. XTS only provides interceptors for or JAX-WS. A JAX-RPC handler is provided only for
- the 1.0 implementation.
- </para>
- </note>
- <!--
- <section> <title>JAX-RPC Client Context Handlers</title> <para> To register the JAX-RPC client-side context
- handler used by the client applications, a handler chain must be included in the definition of the
- <varname>service-ref</varname> in the client's <filename>web.xml</filename> deployment descriptor. Please refer
- to the example application located in <filename>ddrpc/jboss/client-web-app.xml</filename> for an example of such a
- handler. </para> <para> You need to instantiate the
- <classname>com.arjuna.mw.wst11.client.JaxRPCHeaderContextProcessor</classname> class when registering a JAX-RPC
- client context handler. </para> <note> <para> A JAX-RPC client handler is not provided for the 1.1
- implementation. </para> </note> </section>
- -->
- <section>
- <title>JAX-WS Client Context Handlers</title>
- <para>
- In order to register the JAX-WS client-side context handler, the client application uses the APIs provided by the
- <classname>javax.xml.ws.BindingProvider</classname> and <classname>javax.xml.ws.Binding</classname> classes, to
- install a handler chain on the service proxy which is used to invoke the remote endpoint. Refer to the example
- application client implementation located in the
- <filename>src/com/jboss/jbosstm/xts/demo/BasicClient.java</filename> file for an example.
- </para>
- <para>
- You can also specify the handlers by using a configuration file deployed with the application. The file is
- identified by attaching a <systemitem>javax.jws.HandlerChain</systemitem> annotation to the interface class, which
- declares the JAX-WS client API. This interface is normally generated from the web service WSDL port definition.
- </para>
- <para>
- You need to instantiate the <classname>com.arjuna.mw.wst11.client.JaxWSHeaderContextProcessor</classname> class
- when registering a JAX-WS client context handler.
- </para>
- <!--
- <note> <para> The class used in the 1.1 implementation is
- <classname>com.arjuna.mw.wst11.client.JaxWSHeaderContextProcessor</classname>. </para> </note>
- -->
- </section>
- </section>
- </section>
-
- <section>
- <title>Creating Transactional Web Services</title>
-
- <para>
- The two parts to implementing a Web service using XTS are the transaction management and the business logic.
- </para>
- <para>
- The bulk of the transaction management aspects are organized in a clear and easy-to-implement model by means of
- the XTS’s <firstterm>Participant API</firstterm>, provides a structured model for negotiation between the web
- service and the transaction coordinator. It allows the web service to manage its own local transactional data, in
- accordance with the needs of the business logic, while ensuring that its activities are in step with those of the
- client and other services involved in the transaction. Internally, this API uses SOAP to invokes operations on the
- various WS-C, WS-AT and WS-BA services, to drive the transaction to completion.
- </para>
-
- <section>
- <title>Participants</title>
- <para>
- A <firstterm>participant</firstterm> is a software entity which is driven by the transaction manager on behalf of a
- Web service. When a web service wants to participate in a particular transaction, it must enroll a participant to act
- as a proxy for the service in subsequent negotiations with the coordinator. The participant implements an API
- appropriate to the type of transaction it is enrolled in, and the participant model selected when it is enrolled. For
- example, a Durable2PC participant, as part of a WS-Atomic Transaction, implements the Durable2PCParticipant
- interface. The use of participants allows the transactional control management aspects of the Web service to be
- factored into the participant implementation, while staying separate from the the rest of the Web service's business
- logic and private transactional data management.
- </para>
- <para>
- The creation of participants is not trivial, since they ultimately reflect the state of a Web service’s back-end
- processing facilities, an aspect normally associated with an enterprise’s own IT infrastructure. Implementations must
- use one of the following interfaces, depending upon the protocol it will participate within:
- <interfacename>com.arjuna.wst11.Durable2PCParticipant</interfacename>,
- <interfacename>com.arjuna.wst11.Volatile2PCParticipant</interfacename>,
- <interfacename>com.arjuna.wst11.BusinessAgreementWithParticipantCompletionParticipant</interfacename>, or
- <interfacename>com.arjuna.wst11.BusinessAgreementWithCoordinatorCompletionParticipant</interfacename>.
- </para>
- <para>
- A full description of XTS’s participant features is provided in <remark>Fix me</remark>.
- </para>
-<!--
- <note> <para> The 1.1 XTS implementation expects participants to implement the same APIs as the 1.0
- implementation. </para> </note>
--->
- </section>
-
- <section>
- <title>Service-Side Handler Configuration</title>
- <para>
- A transactional Web service must ensure that a service invocation is included in the appropriate transaction. This
- usually only affects the operation of the participants and has no impact on the operation of the rest of the Web
- service. XTS simplifies this task and decouples it from the business logic, in much the same way as for transactional
- clients<remark>Add an xref</remark>. XTS provides a handler which detects and extracts the context details from the
- headers in incoming SOAP headers, and associates the web service thread with the transaction. The handler clears this
- association when dispatching SOAP responses, and writes the context into the outgoing message headers. This is shown
- in <xref linkend="fig-context-handlers-registered-with-soap-server" />.
- </para>
- <para>
- The service side handlers for JAX-WS come in two different versions. The normal handler resumes any transaction
- identified by an incoming context when the service is invoked, and suspends this transaction when the service call
- completes. The alternative handler is used to interpose a local coordinator. The first time an incoming parent
- context is seen, the local coordinator service creates a subordinate transaction, which is resumed before the web
- service is called. The handler ensures that this subordinate transaction is resumed each time the service is invoked
- with the same parent context. When the subordinate transaction completes, the association between the parent
- transaction and its subordinate is cleared.
- </para>
- <note>
- <para>
- The subordinate service side handler is only able to interpose a subordinate coordinator for an Atomic Transaction.
- </para>
- </note>
- <note>
- <para>
- JAX-RPC is provided for the 1.0 implementation only.
- </para>
- </note>
- <!--
- <section>
- <title>JAX-RPC Service Context Handlers</title>
-
- <para> In order to register the JAX-RPC server-side context handler with the deployed Web Services, you must include
- a handler chain in the Web Services deployment descriptor. Please refer to the example application located in the
- <filename>ddrpc/jboss/webservices.xml</filename> deployment descriptor for an example. </para> <para> When
- registering a normal JAX-RPC service context handler, you must instantiate the
- <classname>com.arjuna.mw.wst11.service.JaxRPCHeaderContextProcessor</classname> class. If you need coordinator
- interposition, you need to employ the
- <classname>com.arjuna.mw.wst11.service.JaxRPCSubordinateHeaderContextProcessor</classname> instead. </para> <note>
- <para> A JAX-RPC client handler is not provided for the 1.1 implementation. </para> </note> </section>
- -->
- <section>
- <title>JAX-WS Service Context Handlers</title>
- <para>
- To register the JAX-WS server-side context handler with the deployed Web Services, you must install a handler chain
- on the Server Endpoint Implementation class. The endpoint implementation class annotation, which is the one
- annotated with a <systemitem>javax.jws.WebService</systemitem>, must be supplemented with a
- <systemitem>javax.jws.HandlerChain</systemitem> annotation which identifies a handler configuration file deployed
- with the application. Please refer to the example application configuration file located at
- <filename>dd/jboss/context-handlers.xml</filename> and the endpoint implementation classes located in
- <filename>src/com/jboss/jbosstm/xts/demo/services</filename> for an example.
- </para>
- <para>
- When registering a normal JAX-WS service context handler, you must instantiate the
- <classname>com.arjuna.mw.wst11.service.JaxWSHeaderContextProcessor</classname> class. If you need coordinator
- interposition, employ the <classname>com.arjuna.mw.wst11.service.JaxWSSubordinateHeaderContextProcessor</classname>
- instead.
- </para>
- <!--
- <note> <para> The classes used in the 1.1 implementation are
- <classname>com.arjuna.mw.wst11.service.JaxWSHeaderContextProcessor</classname> and
- <classname>com.arjuna.mw.wst11.service.JaxWSSubordinateHeaderContextProcessor</classname>. </para> </note>
- -->
- <figure id="fig-context-handlers-registered-with-soap-server">
- <title>Context Handlers Registered with the SOAP Server</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/fig-context-handlers-registered-with-soap-server.png" format="PNG"/>
- </imageobject>
- <textobject>
- <para></para>
- </textobject>
- </mediaobject>
- </figure>
-
- </section>
- </section>
-
-<!--
- <section> <title>Implementing the Web Service Business Logic</title> <para> Details about the context management
- that the context processor performs are normally unimportant to the Web service application logic as well as work
- performed by other protocol-specific context handlers. However, back-end systems used by the Web service application
- logic, such as databases, need to track the front-end transaction context, in order to map any operations invoked
- within its scope onto a back-end transaction context. </para> <para> The back-end typically wraps a database driver
- in a decorator pattern which extends the interface of the original driver to hook into the service-side API, so that
- it can access the transaction context details. The general architecture for this pattern is shown in <xref
- linkend="fig-back-end-pattern" />. </para> <figure id="fig-back-end-pattern"> <title>General Pattern for Back-End
- Integration, from the Service Side</title> <mediaobject> <imageobject> <imagedata
- fileref="images/fig-back-end-pattern.png" format="PNG"/> </imageobject> </mediaobject> </figure> <para> The missing
- element in <xref linkend="fig-back-end-pattern" /> is the <systemitem>commit</systemitem> protocol which allows
- back-end work to be made durable or roll back at the end of a transaction. This is covered in the <remark>Add an
- xref</remark> participant chapter, which explores the participant/back-end relation. </para> </section>
--->
- </section>
-
- <section>
- <title>Summary</title>
-
- <para>
- This chapter gives a high-level overview of each of the major software pieces used by the Web Services
- transactions component of JBoss Transaction Service. The Web Services transaction manager provided by JBoss
- Transaction Service is the hub of the architecture and is the only piece of software that user-level software does
- not bind to directly. XTS provides header-processing infrastructure for use with Web Services transactions
- contexts for both client applications and Web Services. XTS provides a simple interface for developing transaction
- participants, along with the necessary document-handling code.
- </para>
- <para>
- This chapter is only an overview, and does not address the more difficult and subtle aspects of programming Web
- Services. For fuller explanations of the components, please continue reading.
- </para>
- </section>
-</chapter>
-
Deleted: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Participant_Crash_Recovery.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/Transactions_XTS_Administration_And_Development_Guide/en-US/Participant_Crash_Recovery.xml 2011-04-12 04:47:52 UTC (rev 36887)
+++ labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Participant_Crash_Recovery.xml 2011-04-12 10:51:00 UTC (rev 36888)
@@ -1,511 +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>Participant Crash Recovery</title>
-
- <indexterm><primary>presumed abort policy</primary></indexterm>
- <indexterm><primary>recovery</primary></indexterm>
- <indexterm><primary>participant recovery</primary></indexterm>
-
- <para>
- A key requirement of a transaction service is to be resilient to a system crash by a host running a participant, as
- well as the host running the transaction coordination services. Crashes which happen before a transaction terminates
- or before a business activity completes are relatively easy to accommodate. The transaction service and participants
- can adopt a <firstterm>presumed abort</firstterm> policy.
- </para>
-
- <procedure>
- <title>Presumed Abort Policy</title>
- <step>
- <para>
- If the coordinator crashes, it can assume that any transaction it does not know about is invalid, and reject a
- participant request which refers to such a transaction.
- </para>
- </step>
- <step>
- <para>
- If the participant crashes, it can forget any provisional changes it has made, and reject any request from the
- coordinator service to prepare a transaction or complete a business activity.
- </para>
- </step>
- </procedure>
-
- <para>
- Crash recovery is more complex if the crash happens during a transaction commit operation, or between completing and
- closing a business activity. The transaction service must ensure as far as possible that participants arrive at a
- consistent outcome for the transaction.
- </para>
- <variablelist>
- <varlistentry>
- <term>WS-AT Transaction</term>
- <listitem>
- <para>
- The transaction needs to commit all provisional changes or roll them all back to the state before the
- transaction started.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>WS-Business Activity Transaction</term>
- <listitem>
- <para>
- All participants need to close the activity or cancel the activity, and run any required compensating
- actions. </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- On the rare occasions where such a consensus cannot be reached, the transaction service must log and report
- transaction failures.
-
- </para>
-
- <para>
- XTS includes support for automatic recovery of WS-AT and WS-BA transactions, if either or both of the coordinator
- and participant hosts crashes. The XTS recovery manager begins execution on coordinator and participant hosts when
- the XTS service restarts. On a coordinator host, the recovery manager detects any WS-AT transactions which have
- prepared but not committed, as well as any WS-BA transactions which have completed but not yet closed. It ensures
- that all their participants are rolled forward in the first case, or closed in the second.
- </para>
- <para>
- On a participant host, the recovery manager detects any prepared WS-AT participants which have not responded to a
- transaction rollback, and any completed WS-BA participants which have not yet responded to an activity cancel
- request, and ensures that the former are rolled back and the latter are compensated. The recovery service also
- allows for recovery of subordinate WS-AT transactions and their participants if a crash occurs on a host where an
- interposed WS-AT coordinator has been employed.
- </para>
- <!-- Community version only <note> <para> Crash recovery is implemented for both the 1.0 and 1.1 implementations of
- the WS-AT and WS-BA protocols. </para> </note>
- -->
- <section>
- <title>WS-AT Recovery</title>
-
- <section>
- <title>WS-AT Coordinator Crash Recovery</title>
- <para>
- The WS-AT coordination service tracks the status of each participant in a transaction as the transaction
- progresses through its two-phase commit. When all participants have been sent a <systemitem>prepare</systemitem>
- message and have responded with a <systemitem>prepared</systemitem> message, the coordinator writes a log record
- storing each participant's details, indicating that the transaction is ready to complete. If the coordinator
- service crashes after this point has been reached, completion of the two-phase commit protocol is still
- guaranteed, by reading the log file after reboot and sending a <systemitem>commit</systemitem> message to each
- participant. Once all participants have responded to the <systemitem>commit</systemitem> with a
- <systemitem>committed</systemitem> message, the coordinator can safely delete the log entry.
- </para>
- <para>
- Since the <systemitem>prepared</systemitem> messages returned by the participants imply that they are ready to
- commit their provisional changes and make them permanent, this type of recovery is safe. Additionally, the
- coordinator does not need to account for any commit messages which may have been sent before the crash, or
- resend messages if it crashes several times. The XTS participant implementation is resilient to redelivery of
- the <systemitem>commit</systemitem> messages. If the participant has implemented the recovery functions
- described in <xref linkend="ws-at-recovery-api" />, the coordinator can guarantee delivery of
- <systemitem>commit</systemitem> messages if both it crashes, and one or more of the participant service hosts
- also crash, at the same time.
- </para>
- <para>
- If the coordination service crashes before the <systemitem>prepare</systemitem> phase completes, the presumed
- abort protocol ensures that participants are rolled back. After system restart, the coordination service has the
- information about about all the transactions which could have entered the <systemitem>commit</systemitem> phase
- before the reboot, since they have entries in the log. It also knows about any active transactions started after
- the reboot. If a participant is waiting for a response, after sending its <systemitem>prepared</systemitem>
- message, it automatically re sends the <systemitem>prepared</systemitem> message at regular intervals. When the
- coordinator detects a transaction which is not active and has no entry in the log file after the reboot, it
- instructs the participant to abort, ensuring that the web service gets a chance to roll back any provisional
- state changes it made on behalf of the transaction.
- </para>
- <para>
- A web service may decide to unilaterally commit or roll back provisional changes associated with a given
- participant, if configured to time out after a specified length of time without a response. In this situation,
- the the web service should record this action and log a message to persistent storage. When the participant
- receives a request to commit or roll back, it should throw an exception if its unilateral decision action does
- not match the requested action. The coordinator detects the exception and logs a message marking the outcome as
- heuristic. It also saves the state of the transaction permanently in the transaction log, to be inspected and
- reconciled by an administrator.
- </para>
-
- </section>
-
- <section>
- <title>WS-AT Participant Crash Recovery</title>
- <para>
- WS-AT participants associated with a transactional web service do not need to be involved in crash recovery if
- the Web service's host machine crashes before the participant is told to prepare. The coordinator will assume
- that the transaction has aborted, and the Web service can discard any information associated with unprepared
- transactions when it reboots.
- </para>
- <para>
- When a participant is told to <systemitem>prepare</systemitem>, the Web service is expected to save to
- persistent storage the transactional state it needs to commit or roll back the transaction. The specific
- information it needs to save is dependent on the implementation and business logic of the Web Service. However,
- the participant must save this state before returning a <systemitem>Prepared</systemitem> vote from the
- <methodname>prepare</methodname> call. If the participant cannot save the required state, or there is some other
- problem servicing the request made by the client, it must return an <systemitem>Aborted</systemitem> vote.
- </para>
- <para>
- The XTS participant services running on a Web Service's host machine cooperate with the Web service
- implementation to facilitate participant crash recovery. These participant services are responsible for calling
- the participant's <methodname>prepare</methodname>, <methodname>commit</methodname>, and
- <systemitem>rollback</systemitem> methods. The XTS implementation tracks the local state of every enlisted
- participant. If the <systemitem>prepare</systemitem> call returns a <systemitem>Prepared</systemitem> vote, the
- XTS implementation ensures that the participant state is logged to the local transaction log before forwarding a
- <systemitem>prepared</systemitem> message to the coordinator.
- </para>
- <para>
- A participant log record contains information identifying the participant, its transaction, and its
- coordinator. This is enough information to allow the rebooted XTS implementation to reinstate the participant as
- active and to continue communication with the coordinator, as though the participant had been enlisted and
- driven to the prepared state. However, a participant instance is still necessary for the commit or rollback
- process to continue.
- </para>
- <para>
- Full recovery requires the log record to contain information needed by the Web service which enlisted the
- participant. This information must allow it to recreate an equivalent participant instance, which can continue
- the <systemitem>commit</systemitem> process to completion, or roll it back if some other Web Service fails to
- <systemitem>prepare</systemitem>. This information might be as simple as a String key which the participant can
- use to locate the data it made persistent before returning its Prepared vote. It may be as complex as a
- serialized object tree containing the original participant instance and other objects created by the Web
- service.
- </para>
- <para>
- If a participant instance implements the relevant interface, the XTS implementation will append this participant
- recovery state to its log record before writing it to persistent storage. In the event of a crash, the
- participant recovery state is retrieved from the log and passed to the Web Service which created it. The Web
- Service uses this state to create a new participant, which the XTS implementation uses to drive the transaction
- to completion. Log records are only deleted after the participant's <methodname>commit</methodname> or
- <methodname>rollback</methodname> method is called.
- </para>
- <warning>
- <para>
- If a crash happens just before or just after a <methodname>commit</methodname> method is called, a
- <methodname>commit</methodname> or <methodname>rollback</methodname> method may be called twice.
- </para>
- </warning>
-
-
- <section id="ws-at-recovery-api">
- <title>WS-AT Participant Crash Recovery APIs</title>
-
-
- <section>
- <title>Saving Participant Recovery State</title>
- <para>
- When a Business Activity participant web service completes its work, it may want to save the information
- which will be required later to close or compensate actions performed during the activity. The XTS
- implementation automatically acquires this information from the participant as part of the completion
- process and writes it to a participant log record. This ensures that the information can be restored and
- used to recreate a copy of the participant even if the web service container crashes between the complete
- and close or compensate operations.
- </para>
- <para>
- For a Participant Completion participant, this information is acquired when the web service invokes the
- <methodname>completed</methodname> method of the <classname>BAParticipantManager</classname> instance
- returned from the call which enlisted the participant. For a Coordinator Completion participant this occurs
- immediately after the call to it's <methodname>completed</methodname> method returns. This assumes that the
- <methodname>completed</methodname> method does not throw an exception or call the participant manager's
- <methodname>cannotComplete</methodname> or <methodname>fail</methodname> method.
- </para>
- <para>
- A participant may signal that it is capable of performing recovery processing, by implementing the
- <interfacename>java.lang.Serializable</interfacename> interface. An alternative is to implement the <xref
- linkend="example-PersistableATParticipant" />.
- </para>
- <example id="example-PersistableATParticipant">
- <title><interfacename>PersistableATParticipant</interfacename>
-Interface</title>
- <programlisting role="JAVA" language="Java"><xi:include href="extras/example-PersistableATParticipant.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
- <para>
- If a participant implements the <interfacename>Serializable</interfacename> interface, the XTS participant
- services implementation uses the serialization API to create a version of the participant which can be
- appended to the participant log entry. If it implements the
- <interfacename>PersistableATParticipant</interfacename> interface, the XTS participant services
- implementation call the <methodname>getRecoveryState</methodname> method to obtain the state to be appended
- to the participant log entry.
- </para>
- <para>
- If neither of these APIs is implemented, the XTS implementation logs a warning message and proceeds without
- saving any recovery state. In the event of a crash on the host machine for the Web service during commit,
- the transaction cannot be recovered and a heuristic outcome may occur. This outcome is logged on the host
- running the coordinator services.
- </para>
- </section>
-
- <section>
- <title>Recovering Participants at Reboot</title>
- <para>
- A Web service must register with the XTS implementation when it is deployed, and unregister when it is
- undeployed, in order to participate in recovery processing. Registration is performed using class
- <classname>XTSATRecoveryManager</classname> defined in package
- <package>org.jboss.jbossts.xts.recovery.participant.at</package>.
- </para>
- <example>
- <title>Registering for Recovery</title>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/example-register-for-recovery.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
-
- <para>
- The Web service must provide an implementation of interface
- <interfacename>XTSBARecoveryModule</interfacename> in package <package>
- org.jboss.jbossts.xts.recovery.participant.ba</package>, as an argument to the
- <methodname>register</methodname> and <methodname>unregister</methodname> calls. This instance identifies
- saved participant recovery records and recreates new, recovered participant instances:
- </para>
- <example>
- <title><interfacename>XTSBARecoveryModule</interfacename>
-Interface</title>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/example-XTSATRecoveryModule.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
-
- <para>
- If a participant's recovery state was saved using serialization, the recovery module's
- <methodname>deserialize</methodname> method is called to recreate the participant. Normally, the recovery
- module is required to read, cast, and return an object from the supplied input stream. If a participant's
- recovery state was saved using the <interfacename>PersistableATParticipant</interfacename> interface, the
- recovery module's <methodname>recreate</methodname> method is called to recreate the participant from the
- byte array it provided when the state was saved.
- </para>
- <para>
- The XTS implementation cannot identify which participants belong to which recovery modules. A module only
- needs to return a participant instance if the recovery state belongs to the module's Web service. If the
- participant was created by another Web service, the module should return <literal>null</literal>. The
- participant identifier, which is supplied as argument to the <methodname>deserialize</methodname> or
- <methodname>recreate</methodname> method, is the identifier used by the Web service when the original
- participant was enlisted in the transaction. Web Services participating in recovery processing should ensure
- that participant identifiers are unique per service. If a module recognizes that a participant identifier
- belongs to its Web service, but cannot recreate the participant, it should throw an exception. This
- situation might arise if the service cannot associate the participant with any transactional information
- which is specific to the business logic.
- </para>
- <para>
- Even if a module relies on serialization to create the participant recovery state saved by the XTS
- implementation, it still must be registered by the application. The <methodname>deserialization</methodname>
- operation must employ a class loader capable of loading classes specific to the Web service. XTS fulfills
- this requirement by devolving responsibility for the <methodname>deserialize</methodname> operation to the
- recovery module.
- </para>
- </section>
- </section>
- </section>
- </section>
-
-
- <section>
- <title>WS-BA Recovery</title>
-
- <section>
- <title>WS-BA Coordinator Crash Recovery</title>
-
- <para>
- The WS-BA coordination service implementation tracks the status of each participant in an activity as the
- activity progresses through completion and closure. A transition point occurs during closure, once all
- <systemitem>CoordinatorCompletion</systemitem> participants receive a <systemitem>complete</systemitem> message
- and respond with a <systemitem>completed</systemitem> message. At this point, all
- <systemitem>ParticipantCompletion</systemitem> participants should have sent a
- <systemitem>completed</systemitem> message. The coordinator writes a log record storing the details of each
- participant, and indicating that the transaction is ready to close. If the coordinator service crashes after the
- log record is written, the <methodname>close</methodname> operation is still guaranteed to be successful. The
- coordinator checks the log after the system reboots and re sends a <systemitem>close</systemitem> message to all
- participants. After all participants respond to the <systemitem>close</systemitem> with a
- <systemitem>closed</systemitem> message, the coordinator can safely delete the log entry.
- </para>
- <para>
- The coordinator does not need to account for any <systemitem>close</systemitem> messages sent before the crash,
- nor resend messages if it crashes several times. The XTS participant implementation is resilient to redelivery
- of <systemitem>close</systemitem> messages. Assuming that the participant has implemented the recovery functions
- described below, the coordinator can even guarantee delivery of <systemitem>close</systemitem> messages if both
- it, and one or more of the participant service hosts, crash simultaneously.
- </para>
- <para>
- If the coordination service crashes before it has written the log record, it does not need to explicitly
- compensate any completed participants. The <phrase>presumed abort protocol</phrase> ensures that all completed
- participants are eventually sent a <systemitem>compensate</systemitem> message. Recovery must be initiated from
- the participant side.
- </para>
- <para>
- A log record does not need to be written when an activity is being canceled. If a participant does not respond
- to a <systemitem>cancel</systemitem> or <systemitem>compensate</systemitem> request, the coordinator logs a
- warning and continues. The combination of the <phrase>presumed abort protocol</phrase> and participant-led
- recovery ensures that all participants eventually get canceled or compensated, as appropriate, even if the
- participant host crashes.
- </para>
- <para>
- If a completed participant does not detect a response from its coordinator after resending its
- <systemitem>completed</systemitem> response a suitable number of times, it switches to sending
- <systemitem>getstatus</systemitem> messages, to determine whether the coordinator still knows about it. If a
- crash occurs before writing the log record, the coordinator has no record of the participant when the
- coordinator restarts, and the <systemitem>getstatus</systemitem> request returns a fault. The participant
- recovery manager automatically compensates the participant in this situation, just as if the activity had been
- canceled by the client.
- </para>
- <para>
- After a participant crash, the participant recovery manager detects the log entries for each completed
- participant. It sends <systemitem>getstatus</systemitem> messages to each participant's coordinator host, to
- determine whether the activity still exists. If the coordinator has not crashed and the activity is still
- running, the participant switches back to resending <systemitem>completed</systemitem> messages, and waits for a
- <systemitem>close</systemitem> or <systemitem>compensate</systemitem> response. If the coordinator has also
- crashed or the activity has been canceled, the participant is automatically canceled.
- </para>
-
- </section>
-
- <!--
- <section> <title>WS-BA Participant Crash Recovery</title> <para> </para> </section>
- -->
-
- <section>
- <title>WS-BA Participant Crash Recovery APIs</title>
-
- <section>
- <title>Saving Participant Recovery State</title>
- <para>
- A participant may signal that it is capable of performing recovery processing, by implementing the
- <interfacename>java.lang.Serializable</interfacename> interface. An alternative is to implement the <xref
- linkend="example-PersistableBAParticipant" />.
- </para>
- <example id="example-PersistableBAParticipant">
- <title><interfacename>PersistableBAParticipant</interfacename> Interface</title>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/example-PersistableBAParticipant.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
- <para>
- If a participant implements the <interfacename>Serializable</interfacename> interface, the XTS participant
- services implementation uses the serialization API to create a version of the participant which can be
- appended to the participant log entry. If the participant implements the
- <interfacename>PersistableBAParticipant</interfacename>, the XTS participant services implementation call the
- <methodname>getRecoveryState</methodname> method to obtain the state, which is appended to the participant log
- entry.
- </para>
- <para>
- If neither of these APIs is implemented, the XTS implementation logs a warning message and proceeds without
- saving any recovery state. If the Web service's host machine crashes while the activity is being closed, the
- activity cannot be recovered and a heuristic outcome will probably be logged on the coordinator's host
- machine. If the activity is canceled, the participant is not compensated and the coordinator host machine may
- log a heuristic outcome for the activity.
- </para>
- </section>
-
-
- <section>
- <title>Recovering Participants at Reboot</title>
- <para>
- A Web service must register with the XTS implementation when it is deployed, and unregister when it is
- undeployed, so it can take part in recovery processing.
- </para>
- <para>
- Registration is performed using the <classname>XTSBARecoveryManager</classname>, defined in the
- <package>org.jboss.jbossts.xts.recovery.participant.ba</package> package.
- </para>
- <example>
- <title><classname>XTSBARecoveryManager</classname> Class</title>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/example-XTSBARecoveryManager.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
- <para>
- The Web service must provide an implementation of the <classname>XTSBARecoveryModule</classname> in the
- <package> org.jboss.jbossts.xts.recovery.participant.ba</package>, as an argument to the
- <methodname>register</methodname> and <methodname>unregister</methodname> calls. This instance identifies
- saved participant recovery records and recreates new, recovered participant instances:
- </para>
- <example>
- <title><interfacename>XTSBARecoveryModule</interfacename> Interface</title>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/example-XTSBARecoveryModule.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
- <para>
- If a participant's recovery state was saved using serialization, one of the recovery module's
- <methodname>deserialize</methodname> methods is called, so that it can recreate the participant. Which method
- to use depends on whether the saved participant implemented the <classname>ParticipantCompletion</classname>
- protocol or the <classname>CoordinatorCompletion</classname> protocol. Normally, the recovery module reads,
- casts and returns an object from the supplied input stream. If a participant's recovery state was saved using
- the <interfacename>PersistableBAParticipant</interfacename> interface, one of the recovery module's
- <methodname>recreate</methodname> methods is called, so that it can recreate the participant from the byte
- array provided when the state was saved. The method to use depends on which protocol the saved participant
- implemented.
- </para>
- <para>
- The XTS implementation does not track which participants belong to which recovery modules. A module is only
- expected to return a participant instance if it can identify that the recovery state belongs to its Web
- service. If the participant was created by some other Web service, the module should return
- <literal>null</literal>. The participant identifier supplied as an argument to the
- <methodname>deserialize</methodname> or <methodname>recreate</methodname> calls is the identifier used by the
- Web service when the original participant was enlisted in the transaction. Web Services which participate in
- recovery processing should ensure that the participant identifiers they employ are unique per service. If a
- module recognizes a participant identifier as belonging to its Web service, but cannot recreate the
- participant, it throws an exception. This situation might arise if the service cannot associate the
- participant with any transactional information specific to business logic.
- </para>
- <para>
- A module must be registered by the application, even when it relies upon serialization to create the
- participant recovery state saved by the XTS implementation. The <methodname>deserialization</methodname>
- operation must employ a class loader capable of loading Web service-specific classes. The XTS implementation
- achieves this by delegating responsibility for the <methodname>deserialize</methodname> operation to the
- recovery module.
- </para>
- </section>
- <section>
- <title>Securing Web Service State Changes</title>
- <para>
- When a BA participant completes, it is expected to commit changes to the web service state made during the
- activity. The web service usually also needs to persist these changes to a local storage device. This leaves
- open a window where the persisted changes may not be guarded with the necessary compensation information. The
- web service container may crash after the changes to the service state have been written but before the XTS
- implementation is able to acquire the recovery state and write a recovery log record for the participant.
- Participants may close this window by employing a two phase update to the local store used to persist the web
- service state.
- </para>
- <para>
- A participant which needs to persist changes to local web service state should implement interface
- <classname>ConfirmCompletedParticipant</classname> in package <package>com.arjuna.wst11</package>. This
- signals to the XTS implementation that it expects confirmation after a successful write of the participant
- recovery record, allowing it to roll forward provisionally persisted changes to the web service
- state. Delivery of this confirmation can be guaranteed even if the web service container crashes after
- writing the participant log record. Conversely, if a recovery record cannot be written because of a fault or
- a crash prior to writing, the provisional changes can be guaranteed to be rolled back.
- </para>
- <example>
- <title><interfacename>ConfirmCompletedParticipant</interfacename>
-Interface</title>
- <programlisting language="Java" role="JAVA"><xi:include href="extras/example-ConfirmCompletedParticipant.java"
-xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
- <para>
- When the participant is ready to complete, it should prepare its persistent changes by temporarily locking
- access to the relevant state in the local store and writing the changed data to disk, retaining both the old
- and new versions of the service state. For a Participant Completion participant, this prepare operation should
- be done just before calling the participant manager's <methodname>completed</methodname> method. For a
- Coordinator Completion participant, it should be done just before returning from the call to the participant's
- <methodname>completed</methodname> method. After writing the participant log record, the XTS implementation
- calls the participant's <methodname>confirmCompleted</methodname> method, providing value
- <literal>true</literal> as the argument. The participant should respond by installing the provisional state
- changes and releasing any locks. If the log record cannot be written, the XTS implementation calls the
- participant's <methodname>confirmCompleted</methodname> method, providing value <literal>false</literal> as
- the argument. The participant should respond by restoring the original state values and releasing any locks.
- </para>
- <para>
- If a crash occurs before the call to <methodname>confirmCompleted</methodname>, the application's recovery
- module can make sure that the provisional changes to the web service state are rolled forward or rolled back
- as appropriate. The web service must identify all provisional writes to persistent state before it starts
- serving new requests or processing recovered participants. It must reobtain any locks required to ensure that
- the state is not changed by new transactions. When the recovery module recovers a participant from the log,
- its compensation information is available. If the participant still has prepared changes, the recovery code
- must call <methodname>confirmCompleted</methodname>, passing value true. This allows the participant to finish
- the <methodname>complete</methodname> operation. The XTS implementation then forwards a
- <systemitem>completed</systemitem> message to the coordinator, ensuring that the participant is subsequently
- notified either to close or to compensate. At the end of the first recovery scan, the recovery module may find
- some prepared changes on disk which are still unaccounted for. This means that the participant recovery record
- is not available. The recovery module should restore the original state values and release any locks. The XTS
- implementation responds to coordinator requests regarding the participant with an <systemitem>unknown
- participant</systemitem> fault, forcing the activity as a whole to be rolled back.
- </para>
- </section>
-
-
- </section>
-
- </section>
-
-
-</chapter>
-
Deleted: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Participants.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/Transactions_XTS_Administration_And_Development_Guide/en-US/Participants.xml 2011-04-12 04:47:52 UTC (rev 36887)
+++ labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Participants.xml 2011-04-12 10:51:00 UTC (rev 36888)
@@ -1,556 +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>Participants</title>
-
- <indexterm><primary>participants</primary></indexterm>
- <indexterm><primary>atomic transactions</primary><secondary>atomicity</secondary></indexterm>
- <indexterm><primary>Durable2PCParticipant</primary></indexterm>
- <indexterm><primary>Volatile2PCParticipant</primary></indexterm>
- <indexterm><primary>BusinessAgreementWithParticipantCompletion</primary></indexterm>
- <indexterm><primary>BusinessAgreementWithCoordinatorCompletion</primary></indexterm>
- <indexterm><primary>BAParticipantManager</primary></indexterm>
- <indexterm><primary>implementation</primary></indexterm>
- <indexterm><primary>deployment</primary></indexterm>
-
-
- <section>
- <title>Overview</title>
- <para>
- The <firstterm>participant</firstterm> is the entity that performs the work pertaining to transaction management
- on behalf of the business services involved in an application. The Web service (in the example code, a theater
- booking system) contains some business logic to reserve a seat and inquire about availability, but it needs to be
- supported by something that maintains information in a durable manner. Typically this is a database, but it could
- be a file system, NVRAM, or other storage mechanism.
- </para>
- <para>
- Although the service may talk to the back-end database directly, it cannot commit or undo any changes, since
- committing and rolling back are ultimately under the control of a transaction. For the transaction to exercise
- this control, it must communicate with the database. In XTS, participant does this communication, as shown in
- <xref linkend="fig-participant-backend-control" />.
- </para>
- <figure id="fig-participant-backend-control">
- <title>Transactions, Participants, and Back-End Transaction Control</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/fig-participant-backend-control.png" format="PNG"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <section>
- <title>Atomic Transaction</title>
- <para>
- All Atomic Transaction participants are instances of the <xref linkend="sect-Durable2PCParticipant" /> or <xref
- linkend="sect-Volatile2PCParticipant" />.
- </para>
-
-
- <section id="sect-Durable2PCParticipant">
- <title>Durable2PCParticipant</title>
- <para>
- A Durable2PCParticipant supports the WS-Atomic Transaction Durable2PC protocol with the signatures listed in
- <xref linkend="list-Durable2PCParticipant-signatures" />, as per the
- <interfacename>com.arjuna.wst11.Durable2Participant</interfacename> interface.
- </para>
- <variablelist id="list-Durable2PCParticipant-signatures">
- <title>Durable2PCParticipant Signatures</title>
- <varlistentry>
- <term><methodname>prepare</methodname></term>
- <listitem>
- <para>
- The participant should perform any work necessary, so that it can either commit or roll back the work
- performed by the Web service under the scope of the transaction. The implementation is free to do
- whatever it needs to in order to fulfill the implicit contract between it and the coordinator.
- </para>
- <para>
- The participant indicates whether it can <systemitem>prepare</systemitem> by returning an instance of
- the <interfacename>com.arjuna.wst11.Vote</interfacename>, with one of three values.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>ReadOnly</literal> indicates that the participant does not need to be informed of the
- transaction outcome, because it did not update any state information.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>Prepared</literal> indicates that the participant is ready to commit or roll back,
- depending on the final transaction outcome. Sufficient state updates have been made persistent to
- accomplish this.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>Aborted</literal> indicates that the participant has aborted and the transaction should
- also attempt to do so.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>commit</methodname></term>
- <listitem>
- <para>
- The participant should make its work permanent. How it accomplishes this depends upon its
- implementation. For instance, in the theater example, the reservation of the ticket is committed. If
- commit processing cannot complete, the participant should throw a
- <systemitem>SystemException</systemitem> error, potentially leading to a heuristic outcome for the
- transaction.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>rollback</methodname></term>
- <listitem>
- <para>
- The participant should undo its work. If rollback processing cannot complete, the participant should
- throw a <systemitem>SystemException</systemitem> error, potentially leading to a heuristic outcome for
- the transaction.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>unknown</methodname></term>
- <listitem>
- <para>
- This method has been deprecated and is slated to be removed from XTS in the future.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>error</methodname></term>
- <listitem>
- <para>
- In rare cases when recovering from a system crash, it may be impossible to complete or roll back a
- previously prepared participant, causing the <methodname>error</methodname> operation to be invoked.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
-
- <section id="sect-Volatile2PCParticipant">
- <title>Volatile2PCParticipant</title>
- <para>
- This participant supports the WS-Atomic Transaction Volatile2PC protocol with the signatures listed in <xref
- linkend="list-Volatile2PCParticipant-signatures" />, as per the
- <interfacename>com.arjuna.wst11.Volatile2Participant</interfacename> interface.
- </para>
- <variablelist id="list-Volatile2PCParticipant-signatures">
- <title>Volatile2PCParticipant Signatures</title>
- <varlistentry>
- <term><methodname>prepare</methodname></term>
- <listitem>
- <para>
- The participant should perform any work necessary to flush any volatile data created by the Web service
- under the scope of the transaction, to the system store. The implementation is free to do whatever it
- needs to in order to fulfill the implicit contract between it and the coordinator.
- </para>
- <para>
- The participant indicates whether it can <systemitem>prepare</systemitem> by returning an instance of
- the <interfacename>com.arjuna.wst11.Vote</interfacename>, with one of three values.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>ReadOnly</literal> indicates that the participant does not need to be informed of the
- transaction outcome, because it did not change any state information during the life of the
- transaction.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>Prepared</literal> indicates that the participant wants to be notified of the final
- transaction outcome via a call to <methodname>commit</methodname> or
- <methodname>rollback</methodname>.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>Aborted</literal> indicates that the participant has aborted and the transaction should
- also attempt to do so.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>commit</term>
- <listitem>
- <para>
- The participant should perform any cleanup activities required, in response to a successful transaction
- commit. These cleanup activities depend upon its implementation. For instance, it may flush cached
- backup copies of data modified during the transaction. In the unlikely event that commit processing
- cannot complete, the participant should throw a <systemitem>SystemException</systemitem> error. This
- will not affect the outcome of the transaction but will cause an error to be logged. This method may not
- be called if a crash occurs during commit processing.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>rollback</term>
- <listitem>
- <para>
- The participant should perform any cleanup activities required, in response to a transaction abort. In
- the unlikely event that rollback processing cannot complete, the participant should throw a
- <systemitem>SystemException</systemitem> error. This will not affect the outcome of the transaction but
- will cause an error to be logged. This method may not be called if a crash occurs during commit
- processing.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>unknown</term>
- <listitem>
- <para>
- This method is deprecated and will be removed in a future release of XTS.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>error</term>
- <listitem>
- <para>
- This method should never be called, since volatile participants are not involved in recovery processing.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </section>
-
-
- </section>
-
-
- <section>
- <title>Business Activity</title>
- <para>
- All Business Activity participants are instances one or the other of the interfaces described in <xref
- linkend="sect-BusinessAgreementWithParticipantCompletion" /> or <xref
- linkend="sect-BusinessAgreementWithCoordinatorCompletion" /> interface.
- </para>
-
-
- <section id="sect-BusinessAgreementWithParticipantCompletion">
- <title>BusinessAgreementWithParticipantCompletion</title>
- <para>
- The <interfacename>BusinessAgreementWithParticipantCompletion</interfacename> interface supports the
- WS-Transactions <systemitem>BusinessAgreementWithParticipantCompletion</systemitem> protocol with the
- signatures listed in <xref linkend="list-BusinessAgreementWithParticipantCompletion" />, as per interface
- <interfacename>com.arjuna.wst11.BusinessAgreementWithParticipantCompletionParticipant</interfacename>.
- </para>
- <variablelist id="list-BusinessAgreementWithParticipantCompletion">
- <title><interfacename>BusinessAgreementWithParticipantCompletion</interfacename> Signatures</title>
- <varlistentry>
- <term><methodname>close</methodname></term>
- <listitem>
- <para>
- The transaction has completed successfully. The participant has previously informed the coordinator that
- it was ready to complete.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>cancel</methodname></term>
- <listitem>
- <para>
- The transaction has canceled, and the participant should undo any work. The participant cannot have
- informed the coordinator that it has completed.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>compensate</methodname></term>
- <listitem>
- <para>
- The transaction has canceled. The participant previously informed the coordinator that it had finished
- work but could compensate later if required, and it is now requested to do so. If compensation cannot be
- performed, the participant should throw a <systemitem>FaultedException</systemitem> error, potentially
- leading to a heuristic outcome for the transaction. If compensation processing cannot complete because
- of a transient condition then the participant should throw a <systemitem>SystemException</systemitem>
- error, in which case the compensation action may be retried or the transaction may finish with a
- heuristic outcome.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>status</methodname></term>
- <listitem>
- <para>
- Return the status of the participant.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>unknown</methodname></term>
- <listitem>
- <para>
- This method is deprecated and will be removed a future XTS release.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>error</term>
- <listitem>
- <para>
- In rare cases when recovering from a system crash, it may be impossible to compensate a
- previously-completed participant. In such cases the <methodname>error</methodname> operation is invoked.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
-
- <section id="sect-BusinessAgreementWithCoordinatorCompletion">
- <title>BusinessAgreementWithCoordinatorCompletion</title>
- <para>
- The BusinessAgreementWithCoordinatorCompletion participant supports the WS-Transactions
- <systemitem>BusinessAgreementWithCoordinatorCompletion</systemitem> protocol with the signatures listed in
- <xref linkend="list-BusinessAgreementWithCoordinatorCompletion-signatures" />, as per the
- <interfacename>com.arjuna.wst11.BusinessAgreementWithCoordinatorCompletionParticipant</interfacename>
- interface.
- </para>
- <variablelist id="list-BusinessAgreementWithCoordinatorCompletion-signatures">
- <title>BusinessAgreementWithCoordinatorCompletion Signatures</title>
- <varlistentry>
- <term><methodname>close</methodname></term>
- <listitem>
- <para>
- The transaction completed successfully. The participant previously informed the coordinator that it was
- ready to complete.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>cancel</methodname></term>
- <listitem>
- <para>
- The transaction canceled, and the participant should undo any work.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>compensate</methodname></term>
- <listitem>
- <para>
- The transaction canceled. The participant previously informed the coordinator that it had finished work
- but could compensate later if required, and it is now requested to do so. In the unlikely event that
- compensation cannot be performed the participant should throw a
- <systemitem>FaultedException</systemitem> error, potentially leading to a heuristic outcome for the
- transaction. If compensation processing cannot complete because of a transient condition, the
- participant should throw a <systemitem>SystemException</systemitem> error, in which case the
- compensation action may be retried or the transaction may finish with a heuristic outcome.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>complete</methodname></term>
- <listitem>
- <!--
- <para> The coordinator is informing the participant that all work it needs to do within the scope of
- this business activity has been received. </para>
- -->
- <para>
- The coordinator is informing the participant all work it needs to do within the scope of this business
- activity has been completed and that it should make permananent any provisional changes it has made.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>status</methodname></term>
- <listitem>
- <para>
- Returns the status of the participant.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>unknown</methodname></term>
- <listitem>
- <para>
- This method is deprecated and will be removed in a future release of XTS.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>error</methodname></term>
- <listitem>
- <para>
- In rare cases when recovering from a system crash, it may be impossible to compensate a previously
- completed participant. In such cases, the <methodname>error</methodname> method is invoked.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
-
- <section>
- <title>BAParticipantManager</title>
- <para>
- In order for the Business Activity protocol to work correctly, the participants must be able to autonomously
- notify the coordinator about changes in their status. Unlike the Atomic Transaction protocol, where all
- interactions between the coordinator and participants are instigated by the coordinator when the transaction
- terminates, the BAParticipantManager interaction pattern requires the participant to be able to talk to the
- coordinator at any time during the lifetime of the business activity.
- </para>
- <para>
- Whenever a participant is registered with a business activity, it receives a handle on the
- coordinator. <!--This handle is an instance of the <interfacename>BAParticipantManager</interfacename>
- interface, located in <interfacename>com.arjuna.wst11.BAParticipantManager</interfacename>,-->This handle is
- an instance of interface com.arjuna.wst11.BAParticipantManager with the methods listed in <xref
- linkend="list-BAParticipantManager" />.
- </para>
- <variablelist id="list-BAParticipantManager">
- <title>BAParticipantManager Methods</title>
- <varlistentry>
- <term><methodname>exit</methodname></term>
- <listitem>
- <para>
- The participant uses the method <methodname>exit</methodname> to inform the coordinator that is has left
- the activity. It will not be informed when and how the business activity terminates. This method may
- only be invoked while the participant is in the <systemitem>active</systemitem> state (or the
- <systemitem>completing</systemitem> state, in the case of a participant registered for the
- <systemitem>ParticipantCompletion</systemitem> protocol). If it is called when the participant is in any
- other state, a <systemitem>WrongStateException</systemitem> error is thrown. An
- <methodname>exit</methodname> does not stop the activity as a whole from subsequently being closed or
- canceled/compensated, but only ensures that the exited participant is no longer involved in completion,
- close or compensation of the activity.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>completed</methodname></term>
- <listitem>
- <para>
- The participant has completed its work, but wishes to continue in the business activity, so that it will
- eventually be informed when, and how, the activity terminates. The participant may later be asked to
- compensate for the work it has done or learn that the activity has been closed.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>fault</methodname></term>
- <listitem>
- <para>
- The participant encountered an error during normal activation and has done whatever it can to compensate
- the activity. The <methodname>fault</methodname> method places the business activity into a mandatory
- <systemitem>cancel-only</systemitem> mode. The faulted participant is no longer involved in completion,
- close or compensation of the activity.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- </section>
-
- </section>
-
-
- <section>
- <title>Participant Creation and Deployment</title>
- <para>
- The participant provides the plumbing that drives the transactional aspects of the service. This section discusses
- the specifics of Participant programming and usage.
- </para>
-
-
- <section>
- <title>Implementing Participants</title>
- <para>
- Implementing a participant is a relatively straightforward task. However, depending on the complexity of the
- transactional infrastructure that the participant needs to manage, the task can vary greatly in complexity and
- scope. Your implementation needs to implement one of the interfaces found under
- <package>com.arjuna.wst11</package>.
- </para>
- <note>
- <!--
- <para> In previous versions of XTS, the interfaces were found in <package>com.arjuna.wst</package>. </para>
- -->
- <para>
- The corresponding participant interfaces used in the 1.0 protocol implementation are located in package
- <code>com.arjuna.wst</code>.
- </para>
- </note>
- </section>
-
-
- <section>
- <title>Deploying Participants</title>
- <!--
- <para> XTS includes transparent message routing functionality, which allows participants to be located on a
- different server than the Transaction Service. The Participant classes are not exposed directly as Web
- Services, but registered with a web service which receives messages from the Transaction Manager and maps them
- to appropriate method invocations on the relevant Participant instance. </para> <para> Transactional Web
- Services typically enroll a new Participant instance of the desired type for each new transaction. You need to
- provide a unique identifier during enrollment. This identifier is used to map transaction protocol messages to
- the appropriate participant instance. Participant method invocations occur outside of a specific transaction
- context. Therefore, if your Participant implementation needs information about the transaction context, then
- you should supply this to the Participant instance, typically as an argument to the constructor
- function. Sample Participant implementations and usage are available as part of the demonstration applications
- included with XTS. </para> <para> You need to deploy the application code which creates and enrolls
- Participants, along with the XTS services and libraries necessary for receiving and processing incoming
- messages from the Transaction Manager. To deploy this code in the Enterprise Application Platform, place the
- XTS service archive (SAR) into the server <filename>deploy/</filename> directory. </para>
-
- -->
- <para>
- Transactional web services and transactional clients are deployed by placing them in the application server
- deploy directory alongside the XTS service archive (SAR). The SAR exports all the client and web service API
- classes needed to manage transactions and enroll and manage participant web services. It provides
- implementations of all the WS-C and WS-T coordination services, not just the coordinator services. In
- particular, it exposes the client and web service participant endpoints which are needed to receive incoming
- messages originating from the coordinator.
- </para>
- <para>
- Normally, a transactional application client and the transaction web service it invokes will be deployed in
- different application servers. As long as the XTS SAR is deployed to each of these containers XTS will
- transparently route coordination messages from clients or web services to their coordinator and vice versa. When
- the the client begins a transaction by default it creates a context using the coordination services in its local
- container. The context holds a reference to the local Registration Service which means that any web services
- enlisted in the transaction enrol with the cooridnation services in the same container."
- </para>
- <para>
- The coordinator does not need to reside in the same container as the client application. By configuring the
- client deployment appropriately it is possible to use the coordinator services co-located with one of the web
- services or even to use services deployed in a separate, dedicated container. See Chapter 8 Stand-Alone
- Coordination for details of how to configure a coordinator located in a different container to the client.
- </para>
- <warning>
- <para>
- In previous releases, XTS applications were deployed using the appropriate XTS and Transaction Manager
- <filename>.jar</filename>, <filename>.war</filename>, and configuration files bundled with the
- application. This deployment method is no longer supported in the &APPSERVER;.
- </para>
- </warning>
- <para>
- During &APPSERVER; startup, you should only deploy a transactional web service or transactional client after the
- XTS services are available. Declare this dependency in a <filename>jboss-beans.xml</filename> file located in
- the <filename>META-INF</filename> directory of the web service or client deployment. <xref
- linkend="example-jboss-beans.xml" /> shows one way of declaring this dependency.
- </para>
- <para>
- After the XTS service starts, it creates an instance of the application class
- <classname>org.my.ServiceBean</classname> by calling its <methodname>start</methodname> method. During
- &APPSERVER; shutdown, XTS stops the same instance by calling its <methodname>stop</methodname> method, prior to
- shutting down the XTS Service.
- </para>
- <example id="example-jboss-beans.xml">
- <title>Example <filename>jboss-beans.xml</filename></title>
- <programlisting language="XML" role="XML"><xi:include href="extras/example-jboss-beans.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
- </section>
- </section>
-</chapter>
-
Deleted: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Protocols_Overview.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/Transactions_XTS_Administration_And_Development_Guide/en-US/Protocols_Overview.xml 2011-04-12 04:47:52 UTC (rev 36887)
+++ labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Protocols_Overview.xml 2011-04-12 10:51:00 UTC (rev 36888)
@@ -1,807 +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>Overview of Protocols Used by XTS</title>
-
- <indexterm><primary>WS-Coordination</primary><secondary>WS-C</secondary></indexterm>
- <indexterm><primary>WS-Atomic Transaction</primary><secondary>WS-AT</secondary></indexterm>
- <indexterm><primary>activation</primary></indexterm>
- <indexterm><primary>registration</primary></indexterm>
- <indexterm><primary>completion</primary></indexterm>
- <indexterm><primary>WS-Business Activity</primary><secondary>WS-BA</secondary></indexterm>
- <indexterm><primary>coordination context</primary></indexterm>
- <indexterm><primary>Activation Coordinator</primary></indexterm>
- <indexterm><primary>Volatile2PC</primary></indexterm>
- <indexterm><primary>Durable2PC</primary></indexterm>
- <indexterm><primary>Two-Phase Commit</primary><secondary>2PC</secondary></indexterm>
- <indexterm><primary>One-Phase Commit</primary><secondary>1PC</secondary></indexterm>
- <indexterm><primary>BusinessAgreementWithParticipantCompletion</primary></indexterm>
- <indexterm><primary>BusinessAgreementWithCoordinatorCompletion</primary></indexterm>
-
- <para>
- This section discusses fundamental concepts associated with the WS-Coordination, WS-Atomic Transaction and
- WS-Business Activity protocols, as defined in each protocol's specification. Foundational information about these
- protocols is important to understanding the remaining material covered in this guide.
- </para>
- <!-- I don't like this but it's in the original so I'll leave it for now. -->
- <note>
- <para>
- If you are familiar with the WS-Coordination, WS-Atomic Transaction, and WS-Business Activity specifications you
- may only need to skim this chapter.
- </para>
- </note>
-
- <section>
- <title>WS-Coordination</title>
- <para>
- In general terms, <firstterm>coordination</firstterm> is the act of one entity,known as the coordinator,
- disseminating information to a number of participants for some domain-specific reason. This reason could be to
- reach consensus on a decision by a distributed transaction protocol, or to guarantee that all participants obtain
- a specific message, such as in a reliable multicast environment. When parties are being coordinated, information,
- known as the <firstterm>coordination context</firstterm>, is propagated to tie together operations which are
- logically part of the same coordinated work or activity. This context information may flow with normal application
- messages, or may be an explicit part of a message exchange. It is specific to the type of coordination being
- performed.
- </para>
- <para>
- The fundamental idea underpinning <firstterm>WS-Coordination (WS-C)</firstterm> is that a coordination
- infrastructure is needed in a Web Services environment. The WS-C specification defines a framework that allows
- different coordination protocols to be plugged in to coordinate work between clients, services, and participants,
- as shown in <xref linkend="fig-ws-c-architecture" />.
- </para>
-
- <figure id="fig-ws-c-architecture">
- <title>WS-C Architecture</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/fig-ws-c-overview.png" format="PNG"/>
- </imageobject>
- <textobject>
- <para>
- The WS-C specification speaks of <firstterm>activities</firstterm>, which are distributed units of work,
- involving one or more parties. These parties may be services, components, or even objects. At this level, an
- activity is minimally specified and is simply created, run, and then completed.
- </para>
- </textobject>
- </mediaobject>
- </figure>
-
- <para>
- Whatever coordination protocol is used, and in whatever domain it is deployed, the same generic requirements are
- present.
- </para>
- <itemizedlist id="list-requirements-for-wsc">
- <title>Generic Requirements for WS-C</title>
- <listitem><para>Instantiation, or activation, of a new coordinator for the specific coordination protocol, for a particular application instance.</para></listitem>
- <listitem><para>Registration of participants with the coordinator, such that they will receive that coordinator’s
- protocol messages during (some part of) the application’s lifetime.</para></listitem>
- <listitem><para>Propagation of contextual information between Web Services that comprise the application.</para></listitem>
- <listitem><para>An entity to drive the coordination protocol through to completion.</para></listitem>
- </itemizedlist>
-
- <para>
- The first three of the points in <xref linkend="list-requirements-for-wsc" /> are the direct responsibility of
- WS-C, while the fourth is the responsibility of a third-party entity. The third-party entity is usually the client
- component of the overall application. These four WS-C roles and their relationships are shown in <xref
- linkend="fig-wsc-four-roles" />.
- </para>
-
- <figure id="fig-wsc-four-roles">
- <title>Four Roles in WS-C</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/fig-wsc-four-roles.png" format="PNG"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <section>
- <title>Activation</title>
-
- <!--
- <para> The WS-C framework exposes an Activation Service which supports the creation of coordinators for specific
- coordination protocols and retrieval of associated contexts. Activation services are invoked asynchronously, and
- so the specification defines the interfaces of the activation service itself and of the invoking service. This
- allows the activation service to call back to deliver the results of the activation, which consist of a context
- that identifies the protocol type and coordinator location. These interfaces are presented in <xref
- linkend="example-wsc-interfaces" />. The code shows that the activation service has a one-way operation that
- expects to receive a <systemitem>CreateCoordinationContext</systemitem> message. The service that sends the
- <systemitem>CreateCoordinationContext</systemitem> message expects to be called back with a
- <systemitem>CreateCoordinationContextResponse message</systemitem>, or to be notified of a problem via an error
- message. </para>
- -->
- <para>
- The WS-C framework exposes an Activation Service which supports the creation of coordinators for specific
- coordination protocols and retrieval of associated contexts. Activation services are invoked synchronously using an
- RPC style exchange. So, the service WSDL defines a single port declaring a
- <methodname>CreateCoordinationContext</methodname> operation. This operation takes an input specfying the details of
- the transaction to be created, including the type of coordination required, timeout, and other relevant
- information. It returns an output containing the details of the newly-created transaction context: the transaction
- identifier, coordination type, and registration service URL.
- </para>
-
- <example id="example-wsc-interfaces">
- <title></title>
- <programlisting role="XML" language="XML"><xi:include href="extras/example-wsc-interfaces.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
-
- <note>
- <!--
- <para> The Activation Coordinator service employs an RPC-style message exchange, so an Activation Requester service
- is not necessary. </para>
- -->
- <para>
- The 1.0 Activation Coordinator service employs an asynchronous message exchange comprised of two one-way messages,
- so an Activation Requester service is also necessary.
- </para>
- </note>
- </section> <!-- <title>Activation</title> -->
-
- <section>
- <title>Registration</title>
- <!--
- <para> The context returned by the activation service includes information which exposes a Registration
- Service. This service allows participants to register to receive protocol messages from the coordinator which is
- associated with the context. Depending upon the coordination protocol, more than one choice of participant
- protocol may be available. Like the activation service, the registration service assumes asynchronous
- communication. Thus, it specifies WSDL for both registration service and registration requester. See <xref
- linkend="example-wsc-registration" /> for more information. </para>
- -->
- <para>
- The context returned by the activation service includes the URL of a Registration Service. When a web service
- receieves a service request accompanied by a transaction context, it contacts the Registration Service to enroll as a
- participant in the transaction. The registration request includes a participant protocol defining the role the web
- service wishes to take in the transaction. Depending upon the coordination protocol, more than one choice of
- participant protocol may be available.
- </para>
- <para>
- Like the activation service, the registration service assumes synchronous communication. Thus, the service WSDL
- exposes a single port declaring a <methodname>Register</methodname> operation. This operation takes an input
- specifying the details of the participant which is to be registered, including the participant protocol type. It
- returns a corresponding output response.
- </para>
- <example id="example-wsc-registration">
- <title>Registration ServiceWSDL Interface</title>
- <programlisting><xi:include href="extras/example-wsc-registration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
- </example>
-
- <para>
- Once a participant is registered with a coordinator through the registration service, it receives coordination
- messages from the coordinator. Typical messages include such things as “prepare to complete” and “complete” messages,
- if a two-phase protocol is used. Where the coordinator’s protocol supports it, participants can also send messages
- back to the coordinator.
- </para>
-
- <note>
- <!--
- <para> The Registration Coordinator employs an RPC-style message exchange, so a Registration Requester service is not
- necessary. </para>
- -->
- <para>
- The 1.0 Registration Coordinator service employs an asynchronous message exchange comprised of two one way
- messages, so a Registration Requester service is also necessary
- </para>
- </note>
- </section> <!-- <title>Registration</title> -->
-
- <section>
- <title>Completion</title>
- <para>
- The role of terminator is generally filled by the client application. At an appropriate point, the client asks the
- coordinator to perform its particular coordination function with any registered participants, to drive the protocol
- through to its completion. After completion, the client application may be informed of an outcome for the
- activity. This outcome may take any form along the spectrum from simple success or failure notification, to complex
- structured data detailing the activity’s status.
- </para>
- </section> <!-- <title>Completion</title> -->
- </section> <!-- <title>WS-Coordination</title> -->
-
- <section>
- <title>WS-Transaction</title>
- <para>
- <firstterm>WS-Transaction (WS-T)</firstterm> comprises the pair of transaction coordination protocols,
- <firstterm>WS-Atomic Transaction (WS-AT)</firstterm> and <firstterm>WS-Business Activity (WS-BA)</firstterm>,
- which utilize the coordination framework provided by <firstterm>WS-Coordination (WS-C)</firstterm>.
- </para>
- <para>
- <firstterm>WS-Transactions</firstterm> was developed to unify existing traditional transaction processing systems,
- allowing them to communicate reliably with one another without changes to the systems' own function.
- </para>
-
- <section>
- <title>WS-Transaction Foundations</title>
- <para>
- WS-Transaction is layered upon the WS-Coordination protocol, as shown in as shown in <xref linkend="wsc-wst-interop"
- />.
- </para>
-
- <figure id="wsc-wst-interop">
- <title>WS-Coordination, WS-Transaction, and WS-Business Activity</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/fig-wsc-wst-interop.png" format="PNG"/>
- </imageobject>
- <textobject>
- <para></para>
- </textobject>
- </mediaobject>
- </figure>
-
- <para>
- WS-C provides a generic framework for specific coordination protocols, like WS-Transaction, used in a modular
- fashion. WS-C provides only context management, allowing contexts to be created and activities to be registered with
- those contexts. WS-Transaction leverages the context management framework provided by WS-C in two ways.
- </para>
- <orderedlist>
- <listitem>
- <para>
- It extends the WS-C context to create a transaction context.
- </para>
- </listitem>
- <listitem>
- <para>
- It augments the activation and registration services with a number of additional services (Completion,
- Volatile2PC, Durable2PC, BusinessAgreementWithParticipantCompletion, and
- BusinessAgreementWithCoordinatorCompletion) and two protocol message sets (one for each of the transaction models
- supported in WS-Transaction), to build a fully-fledged transaction coordinator on top of the WS-C protocol
- infrastructure.
- </para>
- </listitem>
- <listitem>
- <para>
- An important aspect of WS-Transaction that differs from traditional transaction protocols is that a synchronous
- request/response model is not assumed. Sequences of one way messages are used to implement communications between
- the client/participant and the coordination services appropriate to the transaction's coordination and
- participant protocols. This is significant because it means that the client and participant containers must
- deploy XTS service endpoints to receive messages from the coordinator service.
- </para>
- <para>
- This requirement is visible in the details of the <methodname>Register</methodname> and
- <methodname>RegisterResponse</methodname> messages declared in the Registration Service WSDL in <xref
- linkend="example-wsc-registration" />. The <methodname>Register</methodname> message contains the URL of an
- endpoint in the client or web service container. This URL is used when a WS-Transaction coordination service
- wishes to dispatch a message to the clinet or web service. Similarly, the
- <methodname>RegisterResponse</methodname> message contains a URL iendtifying an endpoint for the
- protocol-specific WS-Transaction coordination service for which the client/web service is registered, allowing
- messages to be addressed to the transaction coordinator.
- </para>
- </listitem>
- </orderedlist>
- </section> <!-- <title>WS-Coordination Foundations</title> -->
-
- <section>
- <title>WS-Transaction Architecture</title>
- <!--
- <para> WS-Transaction views the service and participant as distinct roles, making the distinction between a
- transaction-aware service and the participants that act on behalf of the service during a
- transaction. Transactional services deal with business-level protocols, while the participants handle the
- underlying WS-Transaction protocols, as shown <xref linkend="ws-trans-global-view" />. </para>
- -->
-
- <para>
- WS-Transaction distnguishes the transaction-aware web service in its role executing business-logic, from the web
- service acting as a participant in the transaction, communicating with and responding to its transaction
- coordinator. Transaction-aware web services deal with application clients using business-level protocols, while the
- participant handles the underlying WS-Transaction protocols, as shown in <xref linkend="ws-trans-global-view" />.
- </para>
-
- <figure id="ws-trans-global-view">
- <title>WS-Transaction Global View</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/ws-trans-global-view.png" format="PNG"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>
- A transaction-aware web service encapsulates the business logic or work that needs to be conducted within the scope
- of a transaction. This work cannot be confirmed by the application unless the transaction also commits. Thus, control
- is ultimately removed from the application and given to the transaction.
- </para>
- <para>
- The participant is the entity that, under the dictates of the transaction coordinator, controls the outcome of the
- work performed by the transaction-aware Web service. In <xref linkend="ws-trans-global-view" />, each web service is
- shown with one associated participant that manages the transaction protocol messages on behalf of its web
- service. <xref linkend="ws-trans-services-participants" />, however, shows a close-up view of a single web service,
- and a client application with their associated participants.
- </para>
- <figure id="ws-trans-services-participants">
- <title>WS-Transaction Web Services and Participants</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/fig-ws-trans-services-participants.png" format="PNG"/>
- </imageobject>
- </mediaobject>
- </figure>
- <!--
- <para> The transaction-aware Web service and its participant both serve a shared transactional resource, and the
- JAXTX API provides a control relationship between them. In <xref linkend="ws-trans-services-participants" />, the
- database is assumed to be accessed through a transactional JDBC database driver, where SQL statements are sent to
- the database for processing via that driver, but where those statements are tentative and only commit if the
- transaction does. For this to work, the driver/database associates a participant with the transaction. This
- participant informs the database of the transaction outcome. Since all transactional invocations on the Web
- service carry a transaction context, the participant working with the database is able to identify the work that
- the transactional service has done within the scope of a specific transaction, and either commit or roll back the
- work. </para>
- -->
- <para>
- The transaction-aware web service employs a back end database accessed via a JDBC driver, which sends SQL statements
- to the database for processing. However, those statements should only commit if the enclosing web service transaction
- does. For this to work, the web service must employ transaction bridging. Transaction bridging registers a
- participant with the coordinator for the web service transaction and creates a matching XA transaction within which
- it can invoke the driver to make tentative changes to the database. The web service ensures that service requests
- associated with a specific web service transaction are executed in the scope of the corresponding XA transaction,
- grouping changes common to a given transaction while isolating changes belonging to different transactions. The
- participant responds to prepare, commit, or rollback requests associated from the web service transaction coordinator
- by forwarding the same operations to the underlying XA transaction coordinator, ensuring that the local outcome in
- the database corresponds with the global outcome of the web service transaction as a whole.
- </para>
- <para>
- Things are less complex for the client. Through its API, the client application registers a participant with the
- transaction, and uses this participant to control termination of the transaction.
- </para>
- </section> <!-- <title>WS-Transaction Architecture</title> -->
-
- <section>
- <title>WS_Transaction Models</title>
- <para>
- It has been established that traditional transaction models are not appropriate for Web Services. No one specific
- protocol is likely to be sufficient, given the wide range of situations where Web service transactions are likely to
- be used. The WS-Transaction specification proposes two distinct models, where each supports the semantics of a
- particular kind of B2B interaction.
- </para>
-
- <para>
- The following discussion presents the interactions between the client, web service and the transaction coordinator in
- great detail for expository purposes only. Most of this activity happens automatically behind the scenes. The actual
- APIs used to initiate and complete a transaction and to register a participant and drive it through the commit or
- abort process are described in <xref linkend="sec-xts-api" />.
- </para>
-
-
- <section>
- <title>Atomic Transactions</title>
- <para>
- An <firstterm>atomic transaction (AT)</firstterm> is similar to traditional ACID transactions, and is designed to
- support short-duration interactions where ACID semantics are appropriate. <!--Within the scope of an AT, services
- typically enroll transaction-aware resources, such as databases and message queues, indirectly as participants
- under the control of the transaction. When the transaction terminates, the outcome decision of the AT is propagated
- to each enlisted resource via the participant, and the appropriate <systemitem>commit</systemitem> or
- <systemitem>rollback</systemitem> actions are taken by each.-->Within the scope of an AT, web services typically
- employ bridging to allow them to access XA resources, such as databases and message queues, under the control of
- the web service transaction. When the transaction terminates, the participant propagates the outcome decision of
- the AT to the XA resources, and the appropriate commit or rollback actions are taken by each.
- </para>
- <para>
- All services and associated participants are expected to provide ACID semantics, and it is expected that any use of
- atomic transactions occurs in environments and situations where ACID is appropriate. Usually, this environment is a
- trusted domain, over short durations.
- </para>
- <procedure>
- <title>Atomic Transaction Process</title>
- <step>
- <para>
- To begin an atomic transaction, the client application first locates a WS-C Activation Coordinator web service
- that supports WS-Transaction.
- </para>
- </step>
- <step>
- <para>
- The client sends a WS-C <systemitem>CreateCoordinationContext</systemitem> message to the service, specifying
- <ulink url="http://schemas.xmlsoap.org/ws/2004/10/wsat" /> as its coordination type.
- </para>
- </step>
- <step>
- <para>
- The client receives an appropriate WS-Transaction context from the activation service.
- </para>
- </step>
- <step>
- <para>
- The response to the <systemitem>CreateCoordinationContext</systemitem> message, the transaction context, has
- its <systemitem>CoordinationType</systemitem> element set to the WS-Atomic Transaction namespace, <ulink
- url="http://schemas.xmlsoap.org/ws/2004/10/wsat" />. It also contains a reference to the atomic transaction
- coordinator endpoint, the WS-C Registration Service, where participants can be enlisted.
- </para>
- </step>
- <step>
- <para>
- The client normally proceeds to invoke Web Services and complete the transaction, either committing all the
- changes made by the web services, or rolling them back. In order to be able to drive this completion activity,
- the client must register itself as a participant for the <systemitem>Completion</systemitem> protocol, by
- sending a <systemitem>Register</systemitem> message to the Registration Service whose endpoint was returned in
- the Coordination Context.
- </para>
- </step>
- <step>
- <para>
- Once registered for Completion, the client application then interacts with Web Services to accomplish its
- business-level work. With each invocation of a business Web service, the client inserts the transaction context
- into a SOAP header block, such that each invocation is implicitly scoped by the transaction. The toolkits that
- support WS-Atomic Transaction-aware Web Services provide facilities to correlate contexts found in SOAP header
- blocks with back-end operations. This ensures that modifications made by the Web service are done within the
- scope of the same transaction as the client and subject to commit or rollback by the transaction coordinator.
- </para>
- </step>
- <step>
- <para>
- Once all the necessary application-level work is complete, the client can terminate the transaction, with the
- intent of making any changes to the service state permanent. The completion participant instructs the
- coordinator to try to commit or roll back the transaction. When the commit or roll-back operation completes, a
- status is returned to the participant to indicate the outcome of the transaction.
- </para>
- </step>
- </procedure>
-
- <para>
- Although this description of the completion protocol seems straightforward, it hides the fact that in order to
- resolve the transaction to an outcome, several other participant protocols need to be followed.
- </para>
-
- <variablelist>
- <varlistentry>
- <term>Volatile2pc</term>
- <listitem>
- <para>
- The first of these protocols is the optional <firstterm>Volatile2PC</firstterm> (2PC is an abbreviation referring
- to the two-phase commit). The Volatile2PC protocol is the WS-Atomic Transaction equivalent of the synchronization
- protocol discussed earlier. It is typically executed where a Web service needs to flush volatile (cached) state,
- which may be used to improve performance of an application, to a database prior to the transaction
- committing. Once flushed, the data is controlled by a two-phase aware participant.
- </para>
- <para>
- When the completion participant initiates a <systemitem>commit</systemitem> operation, all Volatile2PC
- participants are informed that the transaction is about to complete, via the <systemitem>prepare</systemitem>
- message. The participants can respond with one of three messages: <systemitem>prepared</systemitem>,
- <systemitem>aborted</systemitem>, or <systemitem>readonly</systemitem>. A failure at this stage causes the
- transaction to roll back.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Durable2PC</term>
- <listitem>
- <para>
- The next protocol in the WS-Atomic Transaction is <firstterm>Durable2PC</firstterm>. The Durable2PC protocol is at
- the core of WS-Atomic Transaction. It brings about the necessary consensus between participants in a transaction,
- so the transaction can safely be terminated.
- </para>
- <para>
- The Durable2PC protocol ensures atomicity between participants, and is based on the classic technique of
- <phrase>two-phase commit with presumed abort</phrase>.
- </para>
- <procedure>
- <title>Durable2PC Procedure</title>
- <step>
- <para>
- During the first phase, when the coordinator sends the prepare message, a participant must make durable any
- state changes that occurred during the scope of the transaction, so these changes can either be rolled back or
- committed later. None of the original state information can be lost at this point, since the atomic
- transaction may still roll back. If the participant cannot <systemitem>prepare</systemitem>, it must inform
- the coordinator, by means of the <systemitem>aborted</systemitem> message. The transaction will ultimately
- roll back. If the participant is responsible for a service that did not change any of the transaction's data,,
- it can return the <systemitem>readonly</systemitem> message, causing it to be omitted from the second phase of
- the commit protocol. Otherwise, the <systemitem>prepared</systemitem> message is sent by the participant.
- </para>
- </step>
- <step>
- <para>
- If no failures occur during the first phase, Durable2PC proceeds to the second phase, in which the coordinator
- sends the <systemitem>commit</systemitem> message to participants. Participants then make permanent the
- tentative work done by their associated services, and send a <systemitem>committed</systemitem> message to the
- coordinator. If any failures occur, the coordinator sends the <systemitem>rollback</systemitem> message to all
- participants, causing them to discard tentative work done by their associated services, and delete any state
- information saved to persistent storage at <systemitem>prepare</systemitem>, if they have reached that
- stage. Participants respond to a rollback by sending an <systemitem>aborted</systemitem> message to the
- coordinator.
- </para>
- </step>
- </procedure>
- <note>
- <para>
- The semantics of the WS-Atomic Transaction protocol do not include the one-phase commit optimization. A full
- two-phase commit is always used, even where only a single participant is enlisted.
- </para>
- </note>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>
- <xref linkend="two-pc-participant-state-transitions" /> shows the state transitions of a WS-Atomic Transaction and
- the message exchanges between coordinator and participant. Messages generated by the coordinator are represented by
- solid lines, while the participants' messages use dashed lines.
- </para>
- <figure id="two-pc-participant-state-transitions">
- <title>WS-Atomic Two-Phase Participant State Transitions</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/fig-2pc-participant-state-transitions.png" format="PNG"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>
- Once the Durable2PC protocol completes, the <systemitem>Completion</systemitem> protocol that originally began the
- termination of the transaction can complete, and inform the client application whether the transaction was
- committed or rolled back. Additionally, the Volatile2PC protocol may complete.
- </para>
- <para>
- Like the <systemitem>prepare</systemitem> phase of Volatile2PC, the final phase is optional and can be used to
- inform participants about the transaction's completion, so that they can release resources such as database
- connections.
- </para>
- <para>
- Any registered Volatile2PC participants are invoked after the transaction terminates, and are informed about the
- transaction's completion state by the coordinator. Since the transaction has terminated, any failures of
- participants at this stage are ignored, since they have no impact on outcomes.
- </para>
- <para>
- <xref linkend="fig-at-model" /> illustrates the intricate interweaving of individual protocols comprising the AT as
- a whole.
- </para>
- <figure id="fig-at-model">
- <title></title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/fig-at-model.png" format="PNG"/>
- </imageobject>
- </mediaobject>
- </figure>
- </section> <!-- <title>Atomic Transactions </title> -->
-
-
- <section>
- <title>Business Activities</title>
- <para>
- Most B2B applications require transactional support in order to guarantee consistent outcome and correct
- execution. These applications often involve long-running computations, loosely coupled systems, and components that
- do not share data, location, or administration. It is difficult to incorporate atomic transactions within such
- architectures.
- </para>
- <para>
- For example, an online bookshop may reserve books for an individual for a specific period of time. However, if the
- individual does not purchase the books within that period, they become available again for purchase by other
- customers. Because it is not possible to have an infinite supply of stock, some online shops may seem, from the
- user's perspective, to reserve items for them, while actually allow others to preempt the reservation. A user may
- discover, to his disappointment, that the item is no longer available.
- </para>
- <para>
- A <firstterm>Business Activity (BA)</firstterm> is designed specifically for these kinds of long-duration
- interactions, where it is impossible or impractical to exclusively lock resources.
- </para>
- <procedure>
- <title>BA Process Overview</title>
- <step>
- <para>
- Services are requested to do work.
- </para>
- </step>
- <step>
- <para>
- Where those services have the ability to undo any work, they inform the BA, in case the BA later decides the
- cancel the work. If the BA suffers a failure. it can instruct the service to execute its
- <systemitem>undo</systemitem> behavior.
- </para>
- </step>
- </procedure>
- <para>
- The key to BA is that how services do their work and provide compensation mechanisms is not the responsibility of
- the WS-BA specification. It is delegated to the service provider.
- </para>
- <para>
- The WS-BA defines a protocol for Web Services-based applications to enable existing business processing and
- work-flow systems to wrap their proprietary mechanisms and interoperate across implementations and business
- boundaries.
- </para>
- <para>
- Unlike the WS-AT protocol model, where participants inform the coordinator of their state only when asked, a child
- activity within a BA can specify its outcome to the coordinator directly, without waiting for a request. A
- participant may choose to exit the activity or may notify the coordinator of a failure at any point. This feature
- is useful when tasks fail, since the notification can be used to modify the goals and drive processing forward,
- without the need to wait until the end of the transaction to identify failures. A well-designed Business Activity
- should be proactive.
- </para>
- <para>
- The BA protocols employ a compensation-based transaction model. When a participant in a business activity completes
- its work, it may choose to exit the activity. This choice does not allow any subsequent rollback. Alternatively,
- the participant can complete its activity, signaling to the coordinator that the work it has done can be
- compensated if, at some later point, another participant notifies a failure to the coordinator. In this latter
- case, the coordinator asks each non-exited participant to compensate for the failure, giving them the opportunity
- to execute whatever compensating action they consider appropriate. For instance, participant might credit a bank
- account which it previously debited. If all participants exit or complete without failure, the coordinator notifies
- each completed participant that the activity has been closed.
- </para>
- <para>
- Underpinning all of this are three fundamental assumptions, detailed in <xref linkend="wsba-assumptions" />.
- </para>
- <itemizedlist id="wsba-assumptions">
- <title>Assumptions of WS-BA</title>
- <listitem>
- <para>
- All state transitions are reliably recorded, including application state and coordination metadata (the record
- of sent and received messages).
- </para>
- </listitem>
- <listitem>
- <para>
- All request messages are acknowledged, so that problems are detected as early as possible. This avoids
- executing unnecessary tasks and can also detect a problem earlier when rectifying it is simpler and less
- expensive.
- </para>
- </listitem>
- <listitem>
- <para>
- As with atomic transactions, a <firstterm>response</firstterm> is defined as a separate operation, not as the
- output of the request. Message I/O implementations typically have timeout requirements too short for BA
- responses. If the response is not received after a timeout, it is re-sent, repeatedly, until a response is
- received. The receiver discards all but one identical request received.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- The BA model has two participant protocols: <systemitem>BusinessAgreementWithParticipantCompletion</systemitem> and
- <systemitem>BusinessAgreementWithCoordinatorCompletion</systemitem>. Unlike the AT protocols which are driven from
- the coordinator down to participants, this protocol takes the opposite approach.
- </para>
-
- <variablelist>
- <varlistentry>
- <term>BusinessAgreementWithParticipantCompletion</term>
- <listitem>
- <procedure>
- <step>
- <para>
- A participant is initially created in the Active state.
- </para>
- </step>
- <step>
- <para>
- If it finishes its work and it is no longer needed within the scope of the BA (such as when the activity
- operates on immutable data), the participant can unilaterally decide to exit, sending an
- <systemitem>exited</systemitem> message to the coordinator. However, if the participant finishes and wishes to
- continue in the BA, it must be able to compensate for the work it has performed. In this case, it sends a
- <systemitem>completed</systemitem> message to the coordinator and waits for the coordinator to notify it about
- the final outcome of the BA. This outcome is either a <systemitem>close</systemitem> message, meaning the BA
- has completed successfully, or a <systemitem>compensate</systemitem> message indicating that the participant
- needs to reverse its work.
- </para>
- </step>
- </procedure>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>BusinessAgreementWithCoordinatorCompletion</term>
- <listitem>
- <para>
- The <systemitem>BusinessAgreementWithCoordinatorCompletion</systemitem> differs from the
- <systemitem>BusinessAgreementWithParticipantCompletion</systemitem> protocol in that the participant cannot
- autonomously decide to complete its participation in the BA, even if it can be compensated.
- </para>
- <procedure>
- <step>
- <para>
- Instead, the completion stage is driven by the client which created the BA, which sends a
- <systemitem>completed</systemitem> message to the coordinator.
- </para>
- </step>
- <step>
- <para>
- The coordinator sends a <systemitem>complete</systemitem> message to each participant, indicating that no
- further requests will be sent to the service associated with the participant.
- </para>
- </step>
- <step>
- <para>
- The participant continues on in the same manner as in the BusinessAgreementWithParticipantCompletion protocol.
- </para>
- </step>
- </procedure>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>
- The advantage of the BA model, compared to the AT model, is that is allows the participation of services that
- cannot lock resources for extended periods.
- </para>
- <para>
- While the full ACID semantics are not maintained by a BA, consistency can still be maintained through
- compensation. The task of writing correct compensating actions to preserve overall system consistency is the
- responsibility of the developers of the individual services under control of the BA. Such compensations may use
- backward error recovery, but forward recovery is more common.
- </para>
- <para>
- <xref linkend="fig-bawpc-state-transitions" /> shows the state transitions of a WS-BA
- <systemitem>BusinessAgreementWithParticipantCompletion</systemitem> participant and the message exchanges between
- coordinator and participant. Messages generated by the coordinator are shown with solid lines, while the
- participants' messages are illustrated with dashed lines.
- </para>
- <figure id="fig-bawpc-state-transitions">
- <title></title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/fig-bawpc-state-transitions.png" format="PNG"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>
- <xref linkend="fig-bawcc-state-transitions" /> shows the state transitions of a WS-BA
- <systemitem>BusinessAgreementWithCoordinatorCompletion</systemitem> participant and the message exchanges between
- coordinator and participant. Messages generated by the coordinator are shown with solid lines, while the
- participants' messages are illustrated with dashed lines.
- </para>
- <figure id="fig-bawcc-state-transitions">
- <title></title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/fig-bawcc-state-transitions.png" format="PNG"/>
- </imageobject>
- </mediaobject>
- </figure>
- </section> <!-- <title>Business Activities</title> -->
- </section> <!-- <title>WS-Transaction Models</title> -->
-
- <section>
- <title>Application Messages</title>
- <para>
- <firstterm>Application messages</firstterm> are the requests and responses sent between parties, that constitute the
- work of a business process. Any such messages are considered opaque by XTS, and there is no mandatory message format,
- protocol binding, or encoding style. This means that you are free to use any appropriate Web Services protocol. In
- XTS, the transaction context is propagated within the headers of SOAP messages.
- </para>
-
- <para>
- XTS ships with support for service developers building WS-Transactions-aware services on the
- &APPSERVER;. Interceptors are provided for automatic context handling at both client and service, which
- significantly simplifies development, allowing you to concentrate on writing the business logic without being
- sidetracked by the transactional infrastructure. The interceptors add and remove context elements to application
- messages, without altering the semantics of the messages themselves. Any service which understands what to do with
- a WS-C context can use it. Services which are not aware of WS-C, WS-Atomic Transaction and WS-Business Activity can
- ignore the context. XTS manages contexts without user intervention.
- </para>
-
- <section>
- <title>WS-C, WS-Atomic Transaction, and WS-Business Activity Messages</title>
- <para>
- Although the application or service developer is rarely interested in the messages exchanged by the transactional
- infrastructure, it is useful to understand what kinds of exchanges occur so that the underlying model can be fitted
- in to an overall architecture.
- </para>
- <para>
- WS-Coordination, WS-Atomic Transaction and WS-Business Activity-specific messages are transported using SOAP
- messaging over HTTP. The types of messages that are propagated include instructions to perform standard transaction
- operations like <systemitem>begin</systemitem> and <systemitem>prepare</systemitem>.
- </para>
- <note>
- <para>
- XTS messages do not interfere with messages from the application, an application need not use the same transport
- as the transaction-specific messages. For example, a client application might deliver its application-specific
- messages using SOAP RPC over SMTP, even though the XTS messages are delivered using a different mechanism.
- </para>
- </note>
- </section> <!-- <title>WS-C, WS-Atomic Transaction, and WS-Business Activity Messages</title> -->
- </section> <!-- <title>Application Messages</title> -->
-
- </section>
-
- <section>
- <title>Summary</title>
- <para>
- XTS provides a coordination infrastructure which allows transactions to run between services owned by different
- business, across the Internet. That infrastructure is based on the WS-C, WS-Atomic Transaction and WS-Business
- Activity specifications. It supports two kinds of transactions: atomic transactions and business activities, which
- can be combined in arbitrary ways to map elegantly onto the transactional requirements of the underlying
- problem. The use of the whole infrastructure is simple, because its functionality is exposed through a simple
- transactioning API. XTS provides everything necessary to keep application and transactional aspects of an
- application separate, and to ensure that a system's use of transactions does not interfere with the functional
- aspects of the system itself.
- </para>
- </section> <!-- summary -->
-</chapter>
-
Modified: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Revision_History.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/Transactions_XTS_Administration_And_Development_Guide/en-US/Revision_History.xml 2011-04-12 04:47:52 UTC (rev 36887)
+++ labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Revision_History.xml 2011-04-12 10:51:00 UTC (rev 36888)
@@ -8,12 +8,12 @@
<simpara>
<revhistory>
<revision>
- <revnumber>0</revnumber>
- <date>Mon Jul 12 2010</date>
+ <revnumber>1</revnumber>
+ <date>Tue Apr 12 2010</date>
<author>
- <firstname>Misty</firstname>
- <surname>Stanley-Jones</surname>
- <email>mstanley at redhat.com</email>
+ <firstname>Converter</firstname>
+ <surname>Person</surname>
+ <email>customerservice at redhat.com</email>
</author>
<revdescription>
<simplelist>
Deleted: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Stand_Alone_Coordination.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/Transactions_XTS_Administration_And_Development_Guide/en-US/Stand_Alone_Coordination.xml 2011-04-12 04:47:52 UTC (rev 36887)
+++ labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Stand_Alone_Coordination.xml 2011-04-12 10:51:00 UTC (rev 36888)
@@ -1,192 +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>Stand-Alone Coordination</title>
-
- <indexterm><primary>stand-alone coordination</primary></indexterm>
- <indexterm><primary>activation coordinator</primary></indexterm>
- <indexterm><primary>command-line options</primary></indexterm>
- <indexterm><primary>SAR</primary><secondary>Service Archive</secondary></indexterm>
-
-
- <section>
- <title>Introduction</title>
- <para>
- The XTS service is deployed as a JBoss service archive (SAR). The version of the service archive provided with the
- Transaction Service implements version 1.1 of the WS-C, WS-AT and WS-BA services. You can rebuild the XTS service
- archive to include both the 1.0 and 1.1 implementations and deploy them side by side. See the service archive
- build script for for further details.
- </para>
- <para>
- The release service archive obtains coordination contexts from the Activation Coordinator service running on the
- deployed host. Therefore, WS-AT transactions or WS-BA activities created by a locally-deployed client application
- are supplied with a context which identifies the Registration Service running on the client's machine. Any Web
- Services invoked by the client are coordinated by the Transaction Protocol services running on the client's
- host. This is the case whether the Web Services are running locally or remotely. Such a configuration is called
- <firstterm>local coordination</firstterm>.
- </para>
- <para>
- You can reconfigure this setting globally for all clients, causing context creation requests to be redirected to
- an Activation Coordinator Service running on a remote host. Normally, the rest of the coordination process is
- executed from the remote host. This configuration is called <firstterm>stand-alone coordination</firstterm>.
- </para>
- <itemizedlist>
- <title>Reasons for Choosing a Stand-Alone Coordinator</title>
- <listitem>
- <para>
- Efficiency: if a client application invokes Web Services on a remote &APPSERVER;, coordinating the transaction
- from the remote server might be more efficient, since the protocol-specific messages between the coordinator
- and the participants do not need to travel over the network.
- </para>
- </listitem>
- <listitem>
- <para>
- Reliability: if the coordinator service runs on a dedicated host, there is no danger of failing applications
- or services affecting the coordinator and causing failures for unrelated transactions.
- </para>
- </listitem>
- <listitem>
- <para>
- A third reason might be to use a coordination service provided by a third party vendor.
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>Configuring the Activation Coordinator</title>
-
- <para>
- The XTS service archive used to deploy XTS to the &APPSERVER; includes a bean configuration file,
- <filename>xts-jboss-beans.xml</filename>, in its <filename>META-INF</filename> directory. This file specifies
- configuration values which the &APPSERVER; injects into the beans, and which define the XTS runtime configuration
- when it starts the XTS service. The location of the XTS coordinator is defined by values injected into the
- <classname>WSCEnvironmentBean</classname>. <xref linkend="example-xts-jboss-beans-wsc-environment-bean.xml" />
- shows a fragment of this file which details serveral possible configuration options.
- </para>
- <example id="example-xts-jboss-beans-wsc-environment-bean.xml">
- <title>Example <filename>xts-jboss-beans.xml</filename> configuration settings</title>
- <programlisting language="XML" role="XML"><xi:include href="extras/example-xts-jboss-beans-wsc-environment-bean.xml"
- xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"
- /></programlisting>
- </example>
-
- <para>
- The simplest way to configure a stand-alone coordinator is to provide a complete URL for the remote
- coordinator. The example shows how the bean property with name <varname>coordinatorURL11</varname> would be
- configured with value <literal>http://10.0.1.99:8080/ws-c11/ActivationService</literal>.
- </para>
-
- <para>
- You can also specify the individual elements of the URL using the properties
- <varname>coordinatorScheme11</varname>, <varname>coordinatorAddress11</varname>, and so forth. These values only
- apply when the <varname>coordinatorURL11</varname> is not set. The URL is constructed by combining the specified
- values with default values for any missing elements. This is particularly useful for two specific use cases.
- </para>
- <orderedlist>
- <listitem>
- <para>
- The first case is where the client is expected to use an XTS coordinator deployed in another &APPSERVER;. If,
- for example, this &APPSERVER; is bound to address <literal>10.0.1.99</literal>, setting property
- <varname>coordinatorAddress11</varname> to <literal>10.0.1.99</literal> is normally all that is required to
- configure the coordinator URL to idenitfy the remote &APPSERVER;'s coordination service. If the Web service on
- the remote &APPSERVER; were reset to<literal>9090</literal> then it would also be necessary to set property
- <varname>coordinatorPort11</varname> to this value.
- </para>
- </listitem>
- <listitem>
- <para>
- The second common use case is where communications between client and coordinator, and between participant and
- coordinator, must use secure connections. If property <varname>coordinatorScheme11</varname> is set to value
- <literal>https</literal>, the client's request to begin a transaction is sent to the coordinator service over
- a secure https connection. The XTS coordinator and participant services will ensure that all subsequent
- communications between coordinator and client or coordinator and web services also employ secure https
- connections. Note that this requires configuring the trust stores in the &APPSERVER; running the client,
- coordinator and participant web services with appropriate trust certificates.
- </para>
- </listitem>
- </orderedlist>
- <para>
- If none of the above properties is specified, the coordinator URL uses the <literal>http</literal> scheme. The
- coordinator address and port are obtained from the host address and port configured for the JBoss Web
- service. These default to <literal>localhost</literal> and <literal>8080</literal>, respectively. The URL path
- takes the value shown in <xref linkend="example-xts-jboss-beans-wsc-environment-bean.xml" />.
- </para>
- <para>
- You can configure the bean properties defined above by setting System properties on the Java command line. This is
- useful in pre-deployment testing. So, for example, command line option
- <option>-Dorg.jboss.jbossts.xts11.coordinator.address=10.0.1.99</option> resets property
- <varname>coordinatorAddress11</varname>. System properties do not override property values configured in the
- configuration file. The following table identifies the System properties which can be configured.
- </para>
-
- <note>
- <para>
- The property names have been abbreviated in order to fit into the table. They should each start with prefix
- <literal>org.jboss.jbossts.xts11.coordinator</literal>.
- </para>
- </note>
-
-
- <table id="list-option-priority">
- <title>Command-Line Options Passed with the <parameter>-D</parameter> Parameter, Ordered by Priority</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry><para>Category</para></entry>
- <entry><para>Property</para></entry>
- <entry><para>Format</para></entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><para>Absolute URL</para></entry>
- <entry><para><varname>...coordinatorURL</varname></para></entry>
- <entry><para><ulink url="http://coord.host:coord.port/ws-c11/ActivationService" /></para></entry>
- </row>
- <row>
- <entry><para>Coordinator Scheme, Host, Port, and Path</para></entry>
- <entry>
- <para><varname>...coordinator.scheme</varname></para>
- <para><varname>...coordinator.address</varname></para>
- <para><varname>...coordinator.port</varname></para>
- <para><varname>...coordinator.path</varname></para>
- </entry>
- <entry>
- <para><literal>http</literal></para>
- <para><replaceable>server.bind.address</replaceable></para>
- <para><replaceable>jboss.web.bind.port</replaceable></para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <!-- Community version only <section> <title>Build-Time Default Coordinator Configuration</title> <para> You can reset
- the default coordinator host name and port used by the XTS service archive by defining the properties
- coordinator.hostname and coordinator.port on the build command-line when building the service archive. See the
- service archive build script in the sar directory of the XTS source code for further details. </para> <para> You
- can also redefine the default absolute URL employed by the XTS service by modifying the values specified in the
- WSTX configuration files included in the service archive. The 1.0 specification URL is defined in the
- <filename>wstx.xml</filename> file, and the 1.1 specification URL is defined in the
- <filename>wstx11.xml</filename> file. You can redefine the values either by editing the service archive supplied
- in the <filename>sar</filename> directory of the XTS install tree, or by modifying the source files located in
- the <filename>config</filename> directory of the XTS source tree. </para>
- -->
- <!--
- <section> <title>The XTS Service Archive</title> <para> The XTS <firstterm>service archive (SAR)</firstterm> must
- be deployed on hosts running client applications and participant Web Services, as well as on the stand-alone
- coordinator host. Clients and participants need access to the libraries deployed with XTS. These libraries are
- bundled into the SAR. However, clients and participants also need the ability to receive transaction management
- messages dispatched from the coordinator host. The XTS SAR provides implementations of client-side and
- participant-side listeners for this purpose. Although these services can be deployed separately from the
- coordinator-side service listeners and implementation, they are all bundled into a single SAR for simplicity.
- </para> </section>
- -->
-</chapter>
-
Added: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Transactions_Overview_Guide.ent
===================================================================
--- labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Transactions_Overview_Guide.ent (rev 0)
+++ labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Transactions_Overview_Guide.ent 2011-04-12 10:51:00 UTC (rev 36888)
@@ -0,0 +1,7 @@
+<!ENTITY PRODUCT "JBoss Transactions">
+<!ENTITY BOOKID "Transactions_Overview_Guide">
+<!ENTITY VERSION "4.15">
+<!ENTITY YEAR "2011">
+<!ENTITY HOLDER "JBoss.org">
+<!ENTITY APPSERVER "JBoss Application Server">
+<!-- <!ENTITY APPSERVER "Enterprise Application Platform Server"> -->
Added: 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 (rev 0)
+++ labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Transactions_Overview_Guide.xml 2011-04-12 10:51:00 UTC (rev 36888)
@@ -0,0 +1,15 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "Transactions_Overview_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<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/Transactions_XTS_Administration_And_Development_Guide.ent
===================================================================
--- labs/jbosstm/trunk/XTS/docs/Transactions_XTS_Administration_And_Development_Guide/en-US/Transactions_XTS_Administration_And_Development_Guide.ent 2011-04-12 04:47:52 UTC (rev 36887)
+++ labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Transactions_XTS_Administration_And_Development_Guide.ent 2011-04-12 10:51:00 UTC (rev 36888)
@@ -1,7 +0,0 @@
-<!ENTITY PRODUCT "JBoss Transactions">
-<!ENTITY BOOKID "XTS_Development_Guide">
-<!ENTITY VERSION "4.13">
-<!ENTITY YEAR "2010">
-<!ENTITY HOLDER "JBoss.org">
-<!ENTITY APPSERVER "JBoss Application Server">
-<!-- <!ENTITY APPSERVER "Enterprise Application Platform Server"> -->
Deleted: labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Transactions_XTS_Administration_And_Development_Guide.xml
===================================================================
--- labs/jbosstm/trunk/XTS/docs/Transactions_XTS_Administration_And_Development_Guide/en-US/Transactions_XTS_Administration_And_Development_Guide.xml 2011-04-12 04:47:52 UTC (rev 36887)
+++ labs/jbosstm/trunk/docs/transactions_overview_guide/en-US/Transactions_XTS_Administration_And_Development_Guide.xml 2011-04-12 10:51:00 UTC (rev 36888)
@@ -1,23 +0,0 @@
-<?xml version='1.0' encoding='utf-8' ?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "Transactions_XTS_Administration_And_Development_Guide.ent">
-%BOOK_ENTITIES;
-]>
-<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="About_This_Guide.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Introduction.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="Protocols_Overview.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Getting_Started.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Participants.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="XTS_API.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Stand_Alone_Coordination.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Participant_Crash_Recovery.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/publican-maven.cfg
===================================================================
--- labs/jbosstm/trunk/XTS/docs/Transactions_XTS_Administration_And_Development_Guide/publican-maven.cfg 2011-04-12 04:47:52 UTC (rev 36887)
+++ labs/jbosstm/trunk/docs/transactions_overview_guide/publican-maven.cfg 2011-04-12 10:51:00 UTC (rev 36888)
@@ -1,7 +0,0 @@
-# Config::Simple 4.59
-# Wed Sep 1 15:11:59 2010
-
-xml_lang: en-US
-type: Book
-brand: jboss-community
-tmp_dir: target/publican/Transactions_XTS_Administration_And_Development_Guide
Modified: labs/jbosstm/trunk/docs/transactions_overview_guide/publican.cfg
===================================================================
--- labs/jbosstm/trunk/XTS/docs/Transactions_XTS_Administration_And_Development_Guide/publican.cfg 2011-04-12 04:47:52 UTC (rev 36887)
+++ labs/jbosstm/trunk/docs/transactions_overview_guide/publican.cfg 2011-04-12 10:51:00 UTC (rev 36888)
@@ -4,5 +4,6 @@
xml_lang: en-US
type: Book
brand: jboss-community
-tmp_dir: ../build/Transactions_XTS_Administration_And_Development_Guide
+docname: Transactions Overview Guide
+tmp_dir: target/publican
More information about the jboss-svn-commits
mailing list