[jboss-cvs] JBossAS SVN: r74441 - in projects/docs/enterprise/4.3/Transactions: Transactions_Failure_Recovery_Guide/en-US and 4 other directories.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Wed Jun 11 20:22:38 EDT 2008
Author: irooskov at redhat.com
Date: 2008-06-11 20:22:38 -0400 (Wed, 11 Jun 2008)
New Revision: 74441
Modified:
projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Book_Info.xml
projects/docs/enterprise/4.3/Transactions/Transactions_Failure_Recovery_Guide/en-US/Book_Info.xml
projects/docs/enterprise/4.3/Transactions/Transactions_Installation_Guide/en-US/Book_Info.xml
projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Administration_Guide/en-US/Book_Info.xml
projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Book_Info.xml
projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Book_Info.xml
projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Getting_Started.xml
projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Participants.xml
projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Stand-alone_Coordinator.xml
projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/The_XTS_API.xml
projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Transactional_Web_Services.xml
projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/WS-C_WS-Atomic_Transaction_and_WS-Business_Activity_Overview.xml
Log:
finished docbook xml converstion of Web Services Programmers Guide for Transactions and updated Book_Info files for all books to reflect correct book and platform information
Modified: projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Book_Info.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Book_Info.xml 2008-06-12 00:15:27 UTC (rev 74440)
+++ projects/docs/enterprise/4.3/Transactions/Programmers_Guide/en-US/Book_Info.xml 2008-06-12 00:22:38 UTC (rev 74441)
@@ -4,7 +4,7 @@
<bookinfo>
<title>JBoss TS Programmers Guide</title>
- <subtitle>JBoss Enterprise SOA Platform</subtitle>
+ <subtitle>JBoss Enterprise Application Platform</subtitle>
<issuenum>4.3</issuenum>
<productnumber>1</productnumber>
<abstract>
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_Failure_Recovery_Guide/en-US/Book_Info.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_Failure_Recovery_Guide/en-US/Book_Info.xml 2008-06-12 00:15:27 UTC (rev 74440)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_Failure_Recovery_Guide/en-US/Book_Info.xml 2008-06-12 00:22:38 UTC (rev 74441)
@@ -3,8 +3,8 @@
]>
<bookinfo id="book-Transactions_Failure_Recovery_Guide-Product_Name_and_Version">
- <title>Product Name and Version</title>
- <subtitle>Transactions Failure Recovery Guide</subtitle>
+ <title>Transactions Failure Recovery Guide</title>
+ <subtitle>JBoss Enterprise Application Platform</subtitle>
<issuenum>0.1</issuenum>
<productnumber>0</productnumber>
<abstract>
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_Installation_Guide/en-US/Book_Info.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_Installation_Guide/en-US/Book_Info.xml 2008-06-12 00:15:27 UTC (rev 74440)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_Installation_Guide/en-US/Book_Info.xml 2008-06-12 00:22:38 UTC (rev 74441)
@@ -3,8 +3,8 @@
]>
<bookinfo id="Transactions_Installation_Guide-Product_Name_and_Version">
- <title>Product Name and Version</title>
- <subtitle>Transactions Installation Guide</subtitle>
+ <title>Transactions Installation Guide</title>
+ <subtitle>JBoss Enterprise Application Platform</subtitle>
<issuenum>0.1</issuenum>
<productnumber>0</productnumber>
<abstract><para>This book is about installing the JBoss Transactions Arjuna Core</para></abstract>
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Administration_Guide/en-US/Book_Info.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Administration_Guide/en-US/Book_Info.xml 2008-06-12 00:15:27 UTC (rev 74440)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Administration_Guide/en-US/Book_Info.xml 2008-06-12 00:22:38 UTC (rev 74441)
@@ -3,8 +3,8 @@
]>
<bookinfo id="Transactions_JTA_Administration_Guide-Product_Name_and_Version">
- <title>Product Name and Version</title>
- <subtitle>Transactions JTA Administration Guide</subtitle>
+ <title>Transactions JTA Administration Guide</title>
+ <subtitle>JBoss Enterprise Application Platform</subtitle>
<issuenum>0.1</issuenum>
<productnumber>0</productnumber>
<abstract><para>This book is about the administration of Arjuna TA</para></abstract>
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Book_Info.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Book_Info.xml 2008-06-12 00:15:27 UTC (rev 74440)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_JTA_Programmers_Guide/en-US/Book_Info.xml 2008-06-12 00:22:38 UTC (rev 74441)
@@ -3,8 +3,8 @@
]>
<bookinfo id="Transactions_JTA_Programmers_Guide-Product_Name_and_Version">
- <title>Product Name and Version</title>
- <subtitle>Transactions JTA Programmers Guide</subtitle>
+ <title>Transactions JTA Programmers Guide</title>
+ <subtitle>JBoss Enterprise Application Platform</subtitle>
<issuenum>0.1</issuenum>
<productnumber>0</productnumber>
<abstract><para>This book is about the Transactions JTA from the view of the programmer</para></abstract>
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Book_Info.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Book_Info.xml 2008-06-12 00:15:27 UTC (rev 74440)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Book_Info.xml 2008-06-12 00:22:38 UTC (rev 74441)
@@ -3,11 +3,11 @@
]>
<bookinfo id="Transactions_Web_Services_Programmers_Guide-Product_Name_and_Version">
- <title>Product Name and Version</title>
- <subtitle>Transactions Web Services Programmers Guide</subtitle>
+ <title>Transactions Web Services Programmers Guide</title>
+ <subtitle>JBoss Enterprise Application Platform</subtitle>
<issuenum>0.1</issuenum>
<productnumber>0</productnumber>
- <abstract><para>This book is about... (Be brief; this para is used for the RPM spec file)</para></abstract>
+ <abstract><para>This book is about Programming for Transaction Web Services</para></abstract>
<corpauthor>
<inlinemediaobject>
<imageobject>
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Getting_Started.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Getting_Started.xml 2008-06-12 00:15:27 UTC (rev 74440)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Getting_Started.xml 2008-06-12 00:22:38 UTC (rev 74441)
@@ -2,24 +2,64 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
-<chapter id="Transactions_Web_Services_Programmers_Guide-Test">
- <title>Test</title>
+<chapter id="Transactions_Web_Services_Programmers_Guide-Getting_Started">
+ <title>Getting Started</title>
<para>
- This is a test paragraph
</para>
- <section id="Transactions_Web_Services_Programmers_Guide-Test-Section_1_Test">
- <title>Section 1 Test</title>
+ <section id="Transactions_Web_Services_Programmers_Guide-Getting_Started-Creating_and_deploying_participants">
+ <title>Creating and deploying participants</title>
<para>
- Test of a section
+ A participant is a software entity which is driven by the transaction manager on behalf of a Web service. The creation of participants is non-trivial since they ultimately reflect the state of a Web service’s back-end processing facilities which is a function of an enterprise’s own IT infrastructure. The most that can be said about the implementation of a participant without getting into detail about the back-end systems it represents, or the details of the underlying transaction protocol is that implementations must implement one of the following interfaces, depending upon the protocol it will participate within: <code>com.arjuna.wst.Durable2PCParticipant</code>, <code>com.arjuna.wst.Volatile2PCParticipant</code>, or, <code>com.arjuna.wst.BusinessAgreementWithParticipantCompletionParticipant</code>, <code>com.arjuna.wst.BusinessAgreementWithCoordinatorCompletionParticipant</code>.
</para>
</section>
- <section id="Transactions_Web_Services_Programmers_Guide-Test-Section_2_Test">
- <title>Section 2 Test</title>
+ <section id="Transactions_Web_Services_Programmers_Guide-Getting_Started-Creating_Client_Applications">
+ <title>Creating Client Applications</title>
<para>
- Test of a section
+ There are two aspects to a client application using XTS. The first is the transaction declaration aspects and the second is the business logic that the client application performs. The transaction declaration aspects are taken care of automatically with XTS’s client API. This API provides simple transaction directives like begin, commit, and rollback which the client application can use to initialize, manage, and terminate transactions. Under the covers, this API invokes (via SOAP) operations on the transaction manager.
</para>
+ <para>
+ When the client application performs invocations on business logic Web services, then XTS does not dictate an API for that purpose. However, there is a requirement that whatever API is chosen, the XTS context be inserted onto outgoing messages, and extracted and associated with the current thread for incoming messages. To make the user’s life easier, the XTS software comes complete with three sets of “filters” which can perform the task automatically. These filters are designed to work with JAX-RPC and webMethods client libraries.
+ </para>
+ <note>
+ <para>
+ If the user chooses to use a different SOAP client infrastructure, then the onus to perform client-side header processing rests with them. XTS does not provide client-side infrastructure for anything other than JAX-RPC or webMethods for this release.
+ </para>
+ </note>
+ <formalpara>
+ <title>JAX-RPC Context Handlers</title>
+ <para>
+ In order to register the JAX-RPC server-side context handler with the deployed web services, a handler chain must be included in the web services deployment descriptor. Please refer to the demo application <filename>jboss/webservices.xml</filename> deployment descriptor for an example of how this can be achieved.
+ </para>
+ </formalpara>
+ <para>
+ In order 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 service-ref in the client web.xml deployment descriptor. Please refer to the demo application <filename>jboss/client-web-app.xml</filename> for an example of how this can be achieved.
+ </para>
+ <formalpara>
+ <title>webMethods Context Handlers</title>
+ <para>
+ In order to register the webMethods server-side context handler with the deployed web services, the inbound and outbound interceptors must be configured in the web services deployment descriptor. An example of how this can be configured can be found in the demo application, for example, the <filename>RestaurantServiceAT.xml</filename>.
+ </para>
+ </formalpara>
+ <para>
+ In order to register the webMethods client-side context handler, the inbound and outbound interceptors must be configured in the <filename>glue-config.xml</filename> deployment descriptor. Please refer to the soap interceptor section of the demo application glue-config.xml for an example of how this can be achieved.
+ </para>
</section>
+ <section id="Transactions_Web_Services_Programmers_Guide-Getting_Started-Hints_and_tips">
+ <title>Hints and tips</title>
+ <para>
+ If you want to create multiple JBoss deploys on the same machine, then you may wish to look at <ulink url="http://www.yorku.ca/dkha/jboss/docs/MultipleInstances.htm"><emphasis>Setting up multiple instances</emphasis></ulink> for information on what is required.
+ </para>
+ </section>
+ <section id="Transactions_Web_Services_Programmers_Guide-Getting_Started-Summary">
+ <title>Summary</title>
+ <para>
+ This chapter has provided a high-level overview of how to use each of the major software pieces of the Web Services transactions component of JBossTS. The Web Services transaction manager provided by JBossTS is the hub of the architecture and is the only piece of software that users’ software does not bind to directly. XTS provides header processing infrastructure for dealing with Web Services transactions contexts for both users’ client applications and Web services. For developing transaction participants, XTS provides a simple interface plus the necessary document handling code.
+ </para>
+ <para>
+ This chapter is meant as an overview only, and is unlikely to answer questions on more difficult and subtle aspects. For fuller explanations of the components, please refer to the appropriate chapter elsewhere in this document.
+ </para>
+ </section>
</chapter>
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Participants.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Participants.xml 2008-06-12 00:15:27 UTC (rev 74440)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Participants.xml 2008-06-12 00:22:38 UTC (rev 74441)
@@ -2,23 +2,247 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
-<chapter id="Transactions_Web_Services_Programmers_Guide-Test">
+<chapter id="Transactions_Web_Services_Programmers_Guide-Participants">
<title>Test</title>
<para>
This is a test paragraph
</para>
- <section id="Transactions_Web_Services_Programmers_Guide-Test-Section_1_Test">
- <title>Section 1 Test</title>
+ <section id="Transactions_Web_Services_Programmers_Guide-Participants-The_Participant:_an_Overview">
+ <title>The Participant: an Overview</title>
<para>
- Test of a section
+ The participant is the entity that performs the work pertaining to transaction management on behalf of the business services involved in an application. The Web service (for example, a theatre booking system) contains some business logic for reserving a seat, enquiring availability etc, but it will need to be supported by something that maintains information in a durable manner. Typically this will be a database, but it could be a file system, NVRAM, etc. Now, although the service may talk to the back-end database directly, it cannot commit or undo any changes it (the services) makes, since these are ultimately under the control of the transaction that scoped the work. In order for the transaction to be able to exercise this control, it must have some contact with the database. In XTS this is accomplished by the participant, and the role played by the participant between the transaction and back-end transaction processing infrastructure is shown in the following figure.
</para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/Transaction_Control.png" format="PNG"/>
+ </imageobject>
+ <caption>Transactions, Participants, and Back-End Transaction Control</caption>
+ </mediaobject>
+ <para>
+ Each participant in XTS is related to either the Atomic Transaction or Business Activity protocols. In the following sections we’ll consider both protocols and their respective participants.
+ </para>
+ <formalpara>
+ <title>Atomic Transaction</title>
+ <para>
+ All Atomic Transaction participants are instances of one of the following interfaces.
+ </para>
+ </formalpara>
+ <formalpara>
+ <title>Durable2PCParticipant</title>
+ <para>
+ This participant supports the WS-Atomic Transaction Durable2PC protocol with the following signatures, as per the <interfacename>com.arjuna.wst.Durable2Participant</interfacename> interface:
+ </para>
+ </formalpara>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>prepare</emphasis>: the participant should perform any work necessary to allow it to either commit or rollback 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. The participant is expected to indicate whether it can prepare or not by returning an instance of the <code>com.arjuna.wst.Vote</code>. Values are: <code>ReadOnly</code>, indicating the participant does not need to be informed of the transaction outcome as no state updates were made; Prepared, indicating the participant is prepared to commit or rollback depending on the final transaction outcome, and it has made sufficient state updates persistent to accomplish this; and Aborted, indicating the participant has aborted and the transaction should also attempt to do so.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>commit</emphasis>: the participant should make permanent the work that it controls. What it does will depend upon its implementation, for example, commit the reservation of the theatre ticket. The participant will then return an indication of whether or not it succeeded.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>rollback</emphasis>: the participant should undo the work that it controls. The participant will then return an indication of whether or not it succeeded.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>commitOnePhase</emphasis>: if there is only a single TwoPCParticipant registered with the transaction, then the coordinator can optimize the protocol and simply tell the participant to commit: there is no need for a preparatory phase since consensus is implicit.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>unknown</emphasis>: during recovery the participant can inquire as to the status of the transaction it was registered with. If that transaction is no longer available (has rolled back) then this operation will be invoked by the coordination service.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>error</emphasis>: during recovery the participant can enquire as to the status of the transaction it was registered with. If an error occurs (for example, the transaction service is unavailable) then this operation will be invoked.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <formalpara>
+ <title>Volatile2PCParticipant</title>
+ <para>
+ This participant supports the WS-Atomic Transaction Volatile2PC protocol with the following signatures, as per the <interfacename>com.arjuna.wst.Volatile2Participant</interfacename> interface:
+ </para>
+ </formalpara>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>prepare</emphasis>: the participant should perform any work necessary to allow it to either commit or rollback 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. The participant is expected to indicate whether it can prepare or not by returning an instance of the com.arjuna.wst.Vote. Values are: ReadOnly, indicating the participant does not need to be informed of the transaction outcome as no state updates were made; Prepared, indicating the participant is prepared to commit or rollback depending on the final transaction outcome, and it has made sufficient state updates persistent to accomplish this; and Aborted, indicating the participant has aborted and the transaction should also attempt to do so.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>commit</emphasis>: the participant should make permanent the work that it controls. What it does will depend upon its implementation, for example, commit the reservation of the theatre ticket. The participant will then return an indication of whether or not it succeeded.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>rollback</emphasis>: the participant should undo the work that it controls. The participant will then return an indication of whether or not it succeeded.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>commitOnePhase</emphasis>: if there is only a single TwoPCParticipant registered with the transaction, then the coordinator can optimize the protocol and simply tell the participant to commit: there is no need for a preparatory phase since consensus is implicit.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>unknown</emphasis>: during recovery the participant can inquire as to the status of the transaction it was registered with. If that transaction is no longer available (has rolled back) then this operation will be invoked by the coordination service.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>error</emphasis>: during recovery the participant can enquire as to the status of the transaction it was registered with. If an error occurs (for example, the transaction service is unavailable) then this operation will be invoked.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <formalpara>
+ <title>Business Activity</title>
+ <para>
+ All Business Activity participants are instances of the following interfaces.
+ </para>
+ </formalpara>
+ <formalpara>
+ <title>BusinessAgreementWithParticipantCompletion</title>
+ <para>
+ This participant supports the WS-T <code>BusinessAgreementWithParticipantCompletion</code> protocol with the following signatures, as per the <interfacename>com.arjuna.wst.BusinessAgreementWithParticipantCompletionParticipant</interfacename> interface:
+ </para>
+ </formalpara>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>close</emphasis>: the transaction has completed successfully. The participant previously informed the coordinator that it was ready to complete.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>cancel</emphasis>: the transaction has canceled, and the participant should undo any work. The participant cannot have informed the coordinator that it has completed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>compensate</emphasis>: the transaction has canceled. The participant previously informed the coordinator that it had finished work but could compensate later if required, so it is now requested to do so.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>status</emphasis>: return the status of the participant.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>unknown</emphasis>: if the participant inquires as to the status of the transaction it was registered with and that transaction is no longer available (has rolled back) then this operation will be invoked by the coordination service.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>error</emphasis>: if the participant enquired as to the status of the transaction it was registered with and an error occurs (for example, the transaction service is unavailable) then this operation will be invoked.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <formalpara>
+ <title>BusinessAgreementWithCoordinatorCompletion</title>
+ <para>
+ This participant supports the WS-T <code>BusinessAgreementWithCoordinatorCompletion</code> protocol with the following signatures, as per the <interfacename>com.arjuna.wst.BusinessAgreementWithCoordinatorCompletionParticipant</interfacename> interface:
+ </para>
+ </formalpara>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>close</emphasis>: the transaction has completed successfully. The participant previously informed the coordinator that it was ready to complete.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>cancel</emphasis>: the transaction has canceled, and the participant should undo any work.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>compensate</emphasis>: the transaction has canceled. The participant previously informed the coordinator that it had finished work but could compensate later if required, so it is now requested to do so.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>complete</emphasis>: the coordinator is informing the participant that all work it needs to do within the scope of this business activity has been received.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>status</emphasis>: return the status of the participant.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>unknown</emphasis>: if the participant inquires as to the status of the transaction it was registered with and that transaction is no longer available (has rolled back) then this operation will be invoked by the coordination service.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>error</emphasis>: if the participant enquired as to the status of the transaction it was registered with and an error occurs (for example, the transaction service is unavailable) then this operation will be invoked.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <formalpara>
+ <title>BAParticipantManager</title>
+ <para>
+ In order for the Business Activity protocol to work correctly, the participants must be able to autonomously signal the coordinator that they have left the activity (exited) or are ready to complete and (if necessary) compensate (completed). Unlike the Atomic Transaction protocol, where all interactions between the coordinator and participants are instigated by the coordinator when the transaction terminates, this interaction pattern requires the participant to be able to talk to the coordinator at any time during the lifetime of the business activity.
+ </para>
+ </formalpara>
+ <para>
+ As such, 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 <code>com.arjuna.wst.BAParticipantManager</code>, with the following methods:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>exit</emphasis>: the participant has exited the business activity. The participant uses this to inform the coordinator that is has left the activity. It will not be informed when (and how) the business activity terminates.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>completed</emphasis>: the participant has completed it works, but wishes to continue in the business activity, so that it will eventually be told when (and how) the activity terminates. The participant may later be asked to compensate for the work it has done.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>fault</emphasis>: the participant encountered an error during normal activation and has compensated. This places the business activity into a mandatory cancel-only mode.
+ </para>
+ </listitem>
+ </itemizedlist>
</section>
- <section id="Transactions_Web_Services_Programmers_Guide-Test-Section_2_Test">
- <title>Section 2 Test</title>
+ <section id="Transactions_Web_Services_Programmers_Guide-Participants-Participant_Creation_and_Deployment">
+ <title>Participant Creation and Deployment</title>
<para>
- Test of a section
+ As has been shown, the participant provides the plumbing that drives the transactional aspects of the service. This section discusses the specifics of Participant programming and usage.
</para>
+ <formalpara>
+ <title>Implementing Participants</title>
+ <para>
+ Implementing a participant is, in theory, a relatively straightforward task, though depending on the complexity of the transactional infrastructure that the participant is to manage, the actual size and complexity of a participant will vary. The participant interfaces can be found under <code>com.arjuna.wst</code>. Your implementation must implement one of these interfaces.
+ </para>
+ </formalpara>
+ <formalpara>
+ <title>Deploying Participants</title>
+ <para>
+ In order to allow Participants to be located remote from the Transaction Manager, XTS includes transparent message routing functionality. The Participant classes are not exposed directly as web services, but rather registered with a web service which receives messages from the Transaction Manager and maps them to appropriate method invocations on the relevant Participant instance. Transactional web services will typically enroll a new Participant instance of the desired type for each new transaction. A unique identifier must be provided at enrollment time and will be used to map transaction protocol messages to the appropriate participant instance. Note that Participant method invocations do not occur in a specific transaction context. Therefore, if your Participant implementation requires knowledge of the transaction context (for example, to look up state information in a persistent store) then you should provide this to the Participant instance, typically as an argume!
nt to the constructor function. Sample Participant implementations and usage can be found in the demonstration application included with XTS.
+ </para>
+ </formalpara>
+ <para>
+ Any application code which creates and enrolls Participants must be deployed along with the parts of XTS necessary for receiving and processing incoming messages from the Transaction Manager. This typically means including the appropriate XTS .jar, .wsr and .war files in your application. If you are deploying your application only a server which does not already contain a Transaction Manger installation, you will also need to deploy the XTS configuration files.
+ </para>
+ <note>
+ <para>
+ In early access releases of the XTS product, the Transaction Manager and participant management functions are not provided as separable components. Configuration and deployment of the participant infrastructure is therefore as in the Transaction Manger section above. More flexible deployment of the XTS components will be available in the final release.
+ </para>
+ </note>
</section>
</chapter>
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Stand-alone_Coordinator.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Stand-alone_Coordinator.xml 2008-06-12 00:15:27 UTC (rev 74440)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Stand-alone_Coordinator.xml 2008-06-12 00:22:38 UTC (rev 74441)
@@ -2,24 +2,15 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
-<chapter id="Transactions_Web_Services_Programmers_Guide-Test">
- <title>Test</title>
+<chapter id="Transactions_Web_Services_Programmers_Guide-Stand-alone_Coordinator">
+ <title>Stand-alone Coordinator</title>
<para>
- This is a test paragraph
</para>
- <section id="Transactions_Web_Services_Programmers_Guide-Test-Section_1_Test">
- <title>Section 1 Test</title>
+ <section id="Transactions_Web_Services_Programmers_Guide-Stand-alone_Coordinator-Introduction">
+ <title>Introduction</title>
<para>
- Test of a section
+ For configuring a stand-alone Web Services transaction coordinator, see the relevant chapter in the System Administrator’s Guide.
</para>
</section>
-
- <section id="Transactions_Web_Services_Programmers_Guide-Test-Section_2_Test">
- <title>Section 2 Test</title>
- <para>
- Test of a section
- </para>
- </section>
-
</chapter>
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/The_XTS_API.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/The_XTS_API.xml 2008-06-12 00:15:27 UTC (rev 74440)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/The_XTS_API.xml 2008-06-12 00:22:38 UTC (rev 74441)
@@ -2,24 +2,217 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
-<chapter id="Transactions_Web_Services_Programmers_Guide-Test">
- <title>Test</title>
+<chapter id="Transactions_Web_Services_Programmers_Guide-The_XTS_API">
+ <title>The XTS API</title>
<para>
- This is a test paragraph
</para>
- <section id="Transactions_Web_Services_Programmers_Guide-Test-Section_1_Test">
- <title>Section 1 Test</title>
+ <section id="Transactions_Web_Services_Programmers_Guide-The_XTS_API-Introduction">
+ <title>Introduction</title>
<para>
- Test of a section
+ This chapter shows how to use the XTS API. This is of use both at the client-side where applications consume transactional Web services, and at the service/participant side where transactions need to be coordinated with back-end systems.
</para>
</section>
- <section id="Transactions_Web_Services_Programmers_Guide-Test-Section_2_Test">
- <title>Section 2 Test</title>
+ <section id="Transactions_Web_Services_Programmers_Guide-The_XTS_API-API_for_the_Atomic_Transaction_protocol">
+ <title>API for the Atomic Transaction protocol</title>
<para>
- Test of a section
+ The following classes and interfaces are located within the <package>com.arjuna.wst or com.arjuna.mw.wst</package> packages and sub-packages.
</para>
+ <formalpara>
+ <title>Vote</title>
+ <para>
+ During the two-phase commit protocol, a participant will be asked to vote on whether or not it can prepare to confirm the work that it controls. It must return one of the following subtypes of <code>com.arjuna.wst.Vote</code>:
+ </para>
+ </formalpara>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>Prepared</emphasis>: the participant indicates that it can prepare if asked to by the coordinator. It will not have committed at this stage however, since it does not know what the final outcome will be.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>Aborted</emphasis>: the participant indicates that it cannot prepare and has in fact rolled back. The participant should not expect to get a second phase message.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>ReadOnly</emphasis>: the participant indicates that the work it controls has not made any changes to state that require it to be informed of the final outcome of the transaction. Essentially the participant is resigning from the transaction.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Thus a possible implementation of a 2PC participant’s prepare method may resemble the following:
+ </para>
+<screen>
+public Vote prepare () throws WrongStateException, SystemException
+{
+ // Some participant logic here
+
+ if(/* some condition based on the outcome of the business logic */)
+ {
+ // Vote to confirm
+ return new com.arjuna.wst.Prepared();
+ }
+ else if(/*some other condition based on the outcome of the business logic*/)
+ {
+ // Resign
+ return new com.arjuna.wst.ReadOnly();
+ }
+ else
+ {
+ // Vote to cancel
+ return new com.arjuna.wst.Aborted();
+ }
+}
+</screen>
+ <formalpara>
+ <title>The transaction context</title>
+ <para>
+ A transaction is typically represented by some unique identifier and a reference to the coordinator which manages the transaction, for example, a URL. XTS allows transactions to be nested such that a transaction hierarchy (tree) may be formed. Thus, a transaction context may be a set of transactions, with the top-most transaction the root parent (superior).
+ </para>
+ </formalpara>
+ <formalpara>
+ <title>TxContext</title>
+ <para>
+ <code>com.arjuna.mw.wst.TxContext</code> is an opaque representation of a transaction context.
+ </para>
+ </formalpara>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>valid</emphasis>: this indicates whether or not the contents are valid.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>equals</emphasis>: can be used to compare two instances.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <formalpara>
+ <title>UserTransaction</title>
+ <para>
+ The <classname>com.arjuna.wst.UserTransaction</classname> is the class that most users (for example, clients and services) will see. This isolates them from the underlying protocol-specific aspects of the XTS implementation. Importantly, a UserTransaction does not represent a specific transaction, but rather is responsible for providing access to an implicit per-thread transaction context; it is similar to the UserTransaction in the JTA specification. Therefore, all of the UserTransaction methods implicitly act on the current thread of control.
+ </para>
+ </formalpara>
+ <para>
+ A new transaction is begun and associated with the invoking thread by using the begin method. If there is already a transaction associated with the thread then the <code>WrongStateException</code> exception is thrown. Upon success, this operation associates the newly created transaction with the current thread.
+ </para>
+ <para>
+ The transaction is committed by the commit method. This will execute the Volatile2PC and Durable2PC protocols prior to returning. If there is no transaction associated with the invoking thread then <code>UnknownTransactionException</code> is thrown. If the transaction ultimately rolls back then the <code>TransactionRolledBackException</code> is thrown. When complete, this operation disassociates the transaction from the current thread such that it becomes associated with no transaction.
+ </para>
+ <para>
+ The <code>rollback</code> operation will terminate the transaction and return normally if it succeeded, while throwing an appropriate exception if it didn’t. If there is no transaction associated with the invoking thread then <code>UnknownTransactionException</code> is thrown.
+ </para>
+ <formalpara>
+ <title>UserTransactionFactory</title>
+ <para>
+ UserTransactions are obtained from a <code>UserTransactionFactory</code>.
+ </para>
+ </formalpara>
+ <formalpara>
+ <title>TransactionManager</title>
+ <para>
+ The <interfacename>TransactionManager</interfacename> interface represents the service/container/participant’s (service-side users) typical way in which to interact with the underlying transaction service implementation. As with <interfacename>UserTransaction</interfacename> a <interfacename>TransactionManager</interfacename> does not represent a specific transaction, but rather is responsible for providing access to an implicit per-thread transaction context.
+ </para>
+ </formalpara>
+ <para>
+ A thread of control may require periods of non-transactionality so that it may perform work that is not associated with a specific transaction. In order to do this it is necessary to disassociate the thread from any transactions. The suspend method accomplishes this, returning a <code>TxContext</code> instance, which is a handle on the transaction. The thread is then no longer associated with any transaction.
+ </para>
+ <para>
+ The <methodname>resume</methodname> method can be used to (re-)associate a thread with a transaction(s) via its <code>TxContext</code>. Prior to association, the thread is disassociated with any transaction(s) with which it may be currently associated. If the <code>TxContext</code> is null, then the thread is associated with no transaction. The <code>UnknownTransactionException</code> exception is thrown if the transaction that the <code>TxContext</code> refers to is invalid in the scope of the invoking thread.
+ </para>
+ <para>
+ The <methodname>currentTransaction</methodname> method returns the <code>TxContext</code> for the current transaction, or null if there is none. Unlike suspend, this method does not disassociate the current thread from the transaction(s). This can be used to enable multiple threads to execute within the scope of the same transaction.
+ </para>
+ <para>
+ In order to register and resign participants with a transaction, the container or participant must use:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>enlistForVolatileTwoPhase</emphasis>: enlist the specified participant with current transaction such that it will participate in the Volatile2PC protocol; a unique identifier for the participant is also required. If there is no transaction associated with the invoking thread then the <code>UnknownTransactionException</code> exception is thrown. If the coordinator already has a participant enrolled with the same identifier, then <code>AlreadyRegisteredException</code> will be thrown. If the transaction is not in a state where participants can be enrolled (for example, it is terminating) then <code>WrongStateException</code> will be thrown.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>enlistForDurableTwoPhase</emphasis>: enlist the specified participant with current transaction such that it will participate in the 2PC protocol; a unique identifier for the participant is also required. If there is no transaction associated with the invoking thread then the <code>UnknownTransactionException</code> exception is thrown. If the coordinator already has a participant enrolled with the same identifier, then <code>AlreadyRegisteredException</code> will be thrown. If the transaction is not in a state where participants can be enrolled (for example, it is terminating) then <code>WrongStateException</code> will be thrown.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <formalpara>
+ <title>TransactionFactory</title>
+ <para>
+ TransactionManagers are obtained from a <code>TransactionFactory</code>.
+ </para>
+ </formalpara>
</section>
+ <section id="Transactions_Web_Services_Programmers_Guide-The_XTS_API-API_for_the_Business_Activity_protocol">
+ <title>API for the Business Activity protocol</title>
+ <para>
+ </para>
+ <formalpara>
+ <title>UserBusinessActivity</title>
+ <para>
+ The <classname>com.arjuna.wst.UserBusinessActivity</classname> is the class that most users (for example, clients and services) will see. This isolates them from the underlying protocol-specific aspects of the XTS implementation. Importantly, a <code>UserBusinessActivity</code> does not represent a specific business activity, but rather is responsible for providing access to an implicit per-thread activity. Therefore, all of the <code>UserBusinessActivity</code> methods implicitly act on the current thread of control.
+ </para>
+ </formalpara>
+ <para>
+ A new business activity is begun and associated with the invoking thread by using the begin method. If there is already an activity associated with the thread then the <code>WrongStateException</code> exception is thrown. Upon success, this operation associates the newly created activity with the current thread.
+ </para>
+ <para>
+ The business activity is completed successfully by the close method. This will execute the <code>BusinessAgreementWithParticipantCompletion</code> protocol prior to returning. If there is no activity associated with the invoking thread then <code>UnknownTransactionException</code> is thrown. If the activity ultimately cancels then the <code>TransactionRolledBackException</code> is thrown. When complete, this operation disassociates the business activity from the current thread such that it becomes associated with no activity.
+ </para>
+ <para>
+ The cancel operation will terminate the business activity and return normally if it succeeded, while throwing an appropriate exception if it didn’t. If there is no activity associated with the invoking thread then <code>UnknownTransactionException</code> is thrown. Any participants that had previously completed will be informed to compensate for their work.
+ </para>
+ <para>
+ Some participants may have registered for the <code>BusinessAgreementWithCoordinatorCompletion</code> protocol, which requires the coordinator or application to inform them when all work that they need to do within the scope of a business activity has been performed. The application should therefore use the complete method to inform these participants.
+ </para>
+ <formalpara>
+ <title>UserBusinessActivityFactory</title>
+ <para>
+ UserBusinessActivities are obtained from a <code>UserBusinessActivityFactory</code>.
+ </para>
+ </formalpara>
+ <formalpara>
+ <title>BusinessActivityManager</title>
+ <para>
+ The <interfacename>BusinessActivityManager</interfacename> interface represents the service/container/participant’s (service-side users) typical way in which to interact with the underlying business activity service implementation. As with <interfacename>UserBusinessActivity</interfacename> a <interfacename>BusinessActivityManager</interfacename> does not represent a specific activity, but rather is responsible for providing access to an implicit per-thread activity.
+ </para>
+ </formalpara>
+ <para>
+ A thread of control may require periods of non-transactionality so that it may perform work that is not associated with a specific activity. In order to do this it is necessary to disassociate the thread from any business activities. The suspend method accomplishes this, returning a <code>TxContext</code> instance, which is a handle on the activity. The thread is then no longer associated with any activity.
+ </para>
+ <para>
+ The <methodname>resume</methodname> method can be used to (re-)associate a thread with an activity (or activities) via its TxContext. Prior to association, the thread is disassociated with any activity with which it may be currently associated. If the <code>TxContext</code> is null, then the thread is associated with no activity. The <code>UnknownTransactionException</code> exception is thrown if the business activity that the TxContext refers to is invalid in the scope of the invoking thread.
+ </para>
+ <para>
+ The <methodname>currentTransaction</methodname> method returns the <code>TxContext</code> for the current business activity, or null if there is none. Unlike suspend, this method does not disassociate the current thread from the activity. This can be used to enable multiple threads to execute within the scope of the same business activity.
+ </para>
+ <para>
+ In order to register and resign participants with a business activity, the container or participant must use:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>enlistForBusinessAgreementWithParticipantCompletion</emphasis>: enlist the specified participant with current business activity such that it will participate in the <code>BusinessAgreementWithParticipantCompletion</code> protocol; a unique identifier for the participant is also required. If there is no business activity associated with the invoking thread then the <code>UnknownTransactionException</code> exception is thrown. If the coordinator already has a participant enrolled with the same identifier, then <code>AlreadyRegisteredException</code> will be thrown. If the activity is not in a state where participants can be enrolled (for example, it is terminating) then <code>WrongStateException</code> will be thrown.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>enlistForBusinessAgreementWithCoordinatorCompletion</emphasis>: enlist the specified participant with current activity such that it will participate in the <code>BusinessAgreementWithCoordinatorCompletion</code> protocol; a unique identifier for the participant is also required. If there is no business activity associated with the invoking thread then the <code>UnknownTransactionException</code> exception is thrown. If the coordinator already has a participant enrolled with the same identifier, then <code>AlreadyRegisteredException</code> will be thrown. If the activity is not in a state where participants can be enrolled (for example, it is terminating) then <code>WrongStateException</code> will be thrown.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <formalpara>
+ <title>BusinessActivityManagerFactory</title>
+ <para>
+ BusinessActivityManagers are obtained from a <code>BusinessActivityManagerFactory</code>.
+ </para>
+ </formalpara>
+ </section>
</chapter>
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Transactional_Web_Services.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Transactional_Web_Services.xml 2008-06-12 00:15:27 UTC (rev 74440)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Transactional_Web_Services.xml 2008-06-12 00:22:38 UTC (rev 74441)
@@ -2,23 +2,43 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
-<chapter id="Transactions_Web_Services_Programmers_Guide-Test">
- <title>Test</title>
+<chapter id="Transactions_Web_Services_Programmers_Guide-Transactional_Web_Services">
+ <title>Transactional Web Services</title>
<para>
- This is a test paragraph
</para>
- <section id="Transactions_Web_Services_Programmers_Guide-Test-Section_1_Test">
- <title>Section 1 Test</title>
+ <section id="Transactions_Web_Services_Programmers_Guide-Transactional_Web_Services-Introduction">
+ <title>Introduction</title>
<para>
- Test of a section
+ This chapter describes how to provide transactional support for new and existing Web services using the service-side facilities of XTS. It shows how new services can be made transactional with no additional programming, and how existing services can be made WS-T transaction-aware in a non-invasive fashion.
</para>
</section>
- <section id="Transactions_Web_Services_Programmers_Guide-Test-Section_2_Test">
- <title>Section 2 Test</title>
+ <section id="Transactions_Web_Services_Programmers_Guide-Transactional_Web_Services-A_Transactional_Web_Service">
+ <title>A Transactional Web Service</title>
<para>
- Test of a section
+ A Web service is a business-level entity. It encapsulates application logic needed to perform some domain-specific task, or is designed to delegate to a back-end system which executes that logic. Given it is part of application code, such non-functional requirements as transactionality should not impinge on its construction.
</para>
+ <para>
+ To support this notion, XTS provides a suite of components designed to work at the SOAP stack level, which deal with transactional matters on behalf of a Web service without requiring any changes to that service. In XTS two context handling components are registered with the SOAP server and deal with context management on behalf of the service without the service having to worry about context propagation issues itself. This is shown in the following figure.
+ </para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/Context_Handlers.png" format="PNG"/>
+ </imageobject>
+ <caption>Context Handlers Registered with the SOAP Server</caption>
+ </mediaobject>
+ <para>
+ The detail of the context management that the context processor performs is unimportant to the Web service application logic, and is orthogonal to any work performed by any other protocol-specific context handlers too. However back-end systems which the Web service application logic uses (such as databases) are often interested in the front-end transaction context such that any operations invoked within its scope can be mapped onto a back-end transaction context. This is typically achieved at the back-end by wrapping a database driver in a veneer which implements both the interface of the original driver and hooks into the service-side API to access the transaction context details. The general architecture for this pattern is shown in the figure below.
+ </para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/Back-End_Integration.png" format="PNG"/>
+ </imageobject>
+ <caption>General Pattern for Back-End Integration, Service Side</caption>
+ </mediaobject>
+ <para>
+ The missing element from this is the commit protocol which finally allows back-end work to be made durable or not at the end of a transaction. This is covered in the participant chapter where the participant/back-end relation is explored further.
+ </para>
</section>
</chapter>
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/WS-C_WS-Atomic_Transaction_and_WS-Business_Activity_Overview.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/WS-C_WS-Atomic_Transaction_and_WS-Business_Activity_Overview.xml 2008-06-12 00:15:27 UTC (rev 74440)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/WS-C_WS-Atomic_Transaction_and_WS-Business_Activity_Overview.xml 2008-06-12 00:22:38 UTC (rev 74441)
@@ -239,6 +239,111 @@
</imageobject>
<caption>Two-Phase Commit State Transitions</caption>
</mediaobject>
+ <para>
+ Once the 2PC protocol has finished, the Completion 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 prepare phase of Volatile2PC, the final phase is optional and can be used to inform participants when the transaction has completed, typically so that they can release resources (for example, put a database connection back into the pool of connections).
+ </para>
+ <para>
+ Any registered Volatile2PC participants are invoked after the transaction has terminated and are told the state in which the transaction completed (the coordinator sends either the Committed or Aborted message). Since the transaction has terminated, any failures of participants at this stage are ignored –it is essentially a courtesy, and has no bearing on the outcome of the transaction.
+ </para>
+ <para>
+ Finally, after having gone through each of the stages in an AT, it is possible to see the intricate interweaving of individual protocols that goes to make up the AT as a whole in the following figure.
+ </para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/AT_Model.png" format="PNG"/>
+ </imageobject>
+ <caption>The AT Model</caption>
+ </mediaobject>
+ <formalpara>
+ <title>Business Activities (BA)</title>
+ <para>
+ Most business-to-business 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 and it is difficult to incorporate atomic transactions within such architectures. For example, an online bookshop may reserve books for an individual for a specific period of time, but if the individual does not purchase the books within that period they will be “put back onto the shelf” for others to buy. Furthermore, because it is not possible for anyone to have an infinite supply of stock, some online shops may appear to users to reserve items for them, but in fact may allow others to pre-empt that reservation (for instance, the same book may be “reserved” for multiple users concurrently); a user may subsequently find that the item is no longer available, or may have to be reorder!
ed specially for them.
+ </para>
+ </formalpara>
+ <para>
+ A business activity or BA is designed specifically for these kinds of long-duration interactions, where exclusively locking resources is impossible or impractical. In this model services are requested to do work, and where those services have the ability to undo any work, they inform the BA such that if the BA later decides the cancel the work (for instance if the business activity suffers a failure), it can instruct the service to execute its undo behavior. The key point for Business Activities is that how services do their work and provide compensation mechanisms is not the domain of the WS-Business Activity specification, but an implementation decision for the service provider.
+ </para>
+ <para>
+ The WS- Business Activity simply defines a protocol for Web services-based applications to enable existing business processing and workflow systems to wrap their proprietary mechanisms and interoperate across implementations and business boundaries.
+ </para>
+ <para>
+ A business activity may be partitioned into scopes, where a scope is a business task or unit of work using a collection of Web services. Such scopes can be nested to arbitrary degrees, forming parent and child relationships, where a parent scope has the ability to select which child tasks are to be included in the overall outcome protocol for a specific business activity, and so clearly non-atomic outcomes are possible. In a similar manner to traditional nested transactions, if a child task experiences an error, it can be caught by the parent who may be able to compensate and continue processing.
+ </para>
+ <para>
+ When a child task completes it can either leave the business activity or signal to the parent that the work it has done can be compensated later. In the latter case, the compensation task may be called by the parent should it ultimately need to undo the work performed by the child.
+ </para>
+ <para>
+ Unlike the WS-Atomic Transaction protocol model, where participants inform the coordinator of their state only when asked, a task within a business activity can specify its outcome to the parent directly without waiting for a request. This feature is useful when tasks fail such that the notification can be used by business activity exception handler to modify the goals and drive processing forward without having to meekly wait until the end of the transaction to admit to having failed – a well designed Business Activities should be proactive, if it is to perform well.
+ </para>
+ <para>
+ Underpinning all of this are three fundamental assumptions:
+ </para>
+ <itemizedlist>
+ <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 response is defined as a separate operation and not as the output of the request. Message input-output implementations will typically have timeouts that are too short for some business activity responses. If the response is not received after a timeout, it is resent. This is repeated until a response is received. The request receiver discards all but one identical request received.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ As with atomic transactions, the business activity model has multiple protocols: <code>BusinessAgreementWithParticipantCompletion</code> and <code>BusinessAgreementWithCoordinatorCompletion</code>. However, unlike the AT protocol which is driven from the coordinator down to participants, this protocol is driven much more from the participants upwards.
+ </para>
+ <para>
+ Under the <code>BusinessAgreementWithParticipantCompletion</code> protocol, a child activity is initially created in the Active state; if it finishes the work it was created to do and no more participation is required within the scope of the BA (such as when the activity operates on immutable data), then the child can unilaterally send an exited message to the parent. However, if the child task finishes and wishes to continue in the BA then it must be able to compensate for the work it has performed. In this case it sends a completed message to the parent and waits to receive the final outcome of the BA from the parent. This outcome will either be a close message, meaning the BA has completed successfully or a compensate message indicating that the parent activity requires that the child task reverse its work.
+ </para>
+ <para>
+ The <code>BusinessAgreementWithCoordinatorCompletion</code> protocol is identical to the <code>BusinessAgreementWithParticipantCompletion</code> protocol with the exception that the child cannot autonomously decide to end its participation in the business activity, even if it can be compensated. Rather the child task relies upon the parent to inform it when the child has received all requests for it to perform work which the parent does by sending the complete message to the child. The child then acts as it does in the <code>BusinessAgreementWithParticipantCompletion</code> protocol.
+ </para>
+ <para>
+ The crux of the BA model compared to the AT model is that is allows the participation of services that cannot or will not 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, though the task of writing correct compensating actions (and thus overall system consistency) is delegated to the developers of the services under control of the BA. Such compensations may use backward error recovery, but will typically employ forward recovery.
+ </para>
+ <formalpara>
+ <title>Application Messages</title>
+ <para>
+ Application messages are the requests and responses that are 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 so the developer is free to use any appropriate Web services protocol. In XTS, the transaction context is propagated within the headers of SOAP messages.
+ </para>
+ </formalpara>
+ <note>
+ <para>
+ XTS provides out-of-box support for service developers building WS-T-aware services on the JBoss, Weblogic and Glue platforms1. The provision of interceptors for automatic context handling at both client and service significantly simplifies the developer’s workload, allowing the developer to concentrate on writing the business logic without having to worry about the transactional infrastructure getting in the way. The interceptors simply add and remove context elements to application messages without altering the semantics of those messages. Any service which understands what to do with a WS-C context can use it, services which do not understand the context (those services that are not WS-C, WS-Atomic Transaction and WS-Business Activity-aware) may ignore the context; the important point here is that XTS manages contexts without user intervention.
+ </para>
+ </note>
+ <formalpara>
+ <title>WS-C, WS-Atomic Transaction and WS-Business Activity Messages</title>
+ <para>
+ Although the application or service developer rarely sees or is interested in the messages exchanged by the transactional infrastructure (the transaction manager and any participants), it is useful to understand what kinds of exchanges occur so that the underlying model can be fitted in to an overall architecture.
+ </para>
+ </formalpara>
+ <para>
+ In XTS, WS-C, 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 begin, prepare.
+ </para>
+ <note>
+ <para>
+ XTS messages do not interfere in any way, shape, or form, with the application messages, and nor is there any requirement for an application to use the same transport as the transaction-specific messages. For example, it is quite reasonable for a client application to deliver its application-specific messages using SOAP RPC over SMTP even though under the covers the XTS messages are delivered using a different mechanism.
+ </para>
+ </note>
</section>
+ <section id="Transactions_Web_Services_Programmers_Guide-WS-C_WS-Atomic_Transaction_and_WS-Business_Activity_Overview-Summary">
+ <title>Summary</title>
+ <para>
+ XTS provides a coordination infrastructure designed to allow transactions to run between enterprises 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 due to the fact that its functionality is exposed through a simple transactioning API. Furthermore XTS provides all of the necessary plumbing to keep application and transactional aspects of an application separate, and to ensure that the transactionality of a system does not interfere with the functional aspects of the system itself.
+ </para>
+ </section>
</chapter>
More information about the jboss-cvs-commits
mailing list