[jboss-cvs] JBossAS SVN: r76278 - projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Sun Jul 27 22:35:53 EDT 2008
Author: irooskov at redhat.com
Date: 2008-07-27 22:35:53 -0400 (Sun, 27 Jul 2008)
New Revision: 76278
Modified:
projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Appendix.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/Introduction.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/Preface.xml
projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Revision_History.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/Transactions_Overview.xml
projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Transactions_Web_Services_Programmers_Guide.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:
updated book with make clean_ids
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Appendix.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Appendix.xml 2008-07-28 02:06:20 UTC (rev 76277)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Appendix.xml 2008-07-28 02:35:53 UTC (rev 76278)
@@ -2,9 +2,9 @@
<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
-<appendix id="Transactions_Web_Services_Programmers_Guide-Revision_History">
+<appendix id="appe-Transactions_Web_Services_Programmers_Guide-Revision_History">
<appendixinfo>
- <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
</appendixinfo>
<title>Revision History</title>
<para>
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-07-28 02:06:20 UTC (rev 76277)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Book_Info.xml 2008-07-28 02:35:53 UTC (rev 76278)
@@ -2,27 +2,28 @@
<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
-<bookinfo id="Transactions_Web_Services_Programmers_Guide-Product_Name_and_Version">
+<bookinfo id="book-Transactions_Web_Services_Programmers_Guide-Transactions_Web_Services_Programmers_Guide">
<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 Programming for Transaction Web Services</para></abstract>
+ <abstract>
+ <para>This book is about Programming for Transaction Web Services</para></abstract>
<corpauthor>
<inlinemediaobject>
<imageobject>
- <imagedata format='SVG' fileref="Common_Content/images/title_logo.svg" />
+ <imagedata fileref="Common_Content/images/title_logo.svg" format="SVG" />
</imageobject>
- <textobject><phrase>Logo</phrase></textobject>
+ <textobject>
+ <phrase>Logo</phrase>
+ </textobject>
</inlinemediaobject>
</corpauthor>
<copyright>
<year>&YEAR;</year>
<holder>&HOLDER;</holder>
</copyright>
- <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+ <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
</bookinfo>
-
-
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-07-28 02:06:20 UTC (rev 76277)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Getting_Started.xml 2008-07-28 02:35:53 UTC (rev 76278)
@@ -2,18 +2,18 @@
<!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-Getting_Started">
+<chapter id="chap-Transactions_Web_Services_Programmers_Guide-Getting_Started">
<title>Getting Started</title>
<para>
</para>
- <section id="Transactions_Web_Services_Programmers_Guide-Getting_Started-Creating_and_deploying_participants">
+ <section id="sect-Transactions_Web_Services_Programmers_Guide-Getting_Started-Creating_and_deploying_participants">
<title>Creating and deploying participants</title>
<para>
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-Getting_Started-Creating_Client_Applications">
+ <section id="sect-Transactions_Web_Services_Programmers_Guide-Getting_Started-Creating_Client_Applications">
<title>Creating Client Applications</title>
<para>
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.
@@ -26,35 +26,37 @@
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>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-Creating_Client_Applications-JAX_RPC_Context_Handlers">
<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.
+ 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.
+ 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>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-Creating_Client_Applications-webMethods_Context_Handlers">
<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>.
+ 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.
+ 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">
+
+ <section id="sect-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">
+
+ <section id="sect-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.
+ 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.
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Introduction.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Introduction.xml 2008-07-28 02:06:20 UTC (rev 76277)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Introduction.xml 2008-07-28 02:35:53 UTC (rev 76278)
@@ -2,11 +2,11 @@
<!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-Introduction">
+<chapter id="chap-Transactions_Web_Services_Programmers_Guide-Introduction">
<title>Introduction</title>
<para>
</para>
- <section id="Transactions_Web_Services_Programmers_Guide-introduction-JBossTS_Web_Services_transactions_overview">
+ <section id="sect-Transactions_Web_Services_Programmers_Guide-Introduction-JBossTS_Web_Services_transactions_overview">
<title>JBossTS Web Services transactions overview</title>
<para>
The XML transaction service component of JBossTS (shorthand referred to as XTS) supports the coordination of private and public Web services in a business transaction. Therefore, to understand XTS, you must be familiar with Web services, and also understand a little about transactions. This chapter introduces XTS and provides a brief overview of the technologies that form the Web services standard. Additionally, this chapter explores some of the fundamentals of transactioning technology and how it can be applied to Web services. Much of the content presented in this chapter is detailed throughout this guide; however, only overview information about Web services is provided. If you are new to creating Web services, please see consult your Web services platform documentation.
@@ -15,7 +15,7 @@
JBossTS provides as the XTS component a transaction solution for Web services. Using XTS, business partners can coordinate complex business transactions in a controlled and reliable manner. The JBossTS Web Services API supports a transactional coordination model based on the WS-C, WS-Atomic Transaction and WS-Business Activity specifications. WS-C is a generic coordination framework developed by IBM, Microsoft and BEA, WS-Atomic Transaction and WS-Business Activity are transaction protocols that utilize this framework.
</para>
<para>
- Web services are modular, reusable software components that are created by exposing business functionality through a Web service interface. Web services communicate directly with other Web services using standards-based technologies such as SOAP and HTTP. These standards-based communication technologies allow Web services to be accessed by customers, suppliers, and trading partners, independent of hardware operation system or programming environment. The result is a vastly improved collaboration environment as compared to today's EDI and business-to-business (B2B) solutions—an environment where businesses can expose their current and future business applications as Web services that can be easily discovered and accessed by external partners.
+ Web services are modular, reusable software components that are created by exposing business functionality through a Web service interface. Web services communicate directly with other Web services using standards-based technologies such as SOAP and HTTP. These standards-based communication technologies allow Web services to be accessed by customers, suppliers, and trading partners, independent of hardware operation system or programming environment. The result is a vastly improved collaboration environment as compared to today's EDI and business-to-business (B2B) solutions—an environment where businesses can expose their current and future business applications as Web services that can be easily discovered and accessed by external partners.
</para>
<para>
Web services, by themselves, are not fault tolerant. In fact, some of the reasons that make it an attractive development solution are also the same reasons that service-based applications may have drawbacks:
@@ -35,7 +35,7 @@
<para>
Applications that have high dependability requirements, must find a method of minimizing the effects of errors that may occur when an application consumes Web services. One method of safeguarding against such failures is to interact with an application’s Web services within the context of a transaction. A transaction is simply a unit of work which is completed entirely, or in the case of failures is reversed to some agreed consistent state – normally to appear as if the work had never occurred in the first place. With XTS, transactions can span multiple Web services which mean that work performed across multiple enterprises can be managed with transactional support.
</para>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-JBossTS_Web_Services_transactions_overview-Managing_Service_Based_Processes">
<title>Managing Service-Based Processes</title>
<para>
XTS allows you to create transactions that drive complex business processes spanning multiple Web services. Current Web services standards do not address the requirements for a high-level coordination of services since in today’s Web services applications, which use single request/receive interactions, coordination is typically not a problem. However, for applications that engage multiple services among multiple business partners, coordinating and controlling the resulting interactions is essential. This becomes even more apparent when you realize that you generally have little in the way of formal guarantees when interacting with third-party Web services.
@@ -55,7 +55,7 @@
<para>
This simple example describes the situations where XTS excels at supporting business processes across multiple enterprises. This example is further refined throughout this guide, and appears as a standard demonstrator (including source code) with the XTS distribution.
</para>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-JBossTS_Web_Services_transactions_overview-Servlets">
<title>Servlets</title>
<para>
The WS-C, WS-Atomic Transaction and WS-Business Activity protocols are based on one-way interactions of entities rather than traditional synchronous request/response RPC style interactions. Entities (for example, transaction participants) invoke operations on other entities (for example, the transaction coordinator) in order to return responses to requests. What this means is that the programming model is based on peer-to-peer relationships, with the result that all services, whether they are participants, coordinators or clients, must have an active component that allows them to receive unsolicited messages.
@@ -64,7 +64,7 @@
<para>
In the current implementation of XTS, the active component is achieved through the use of Java servlet technology. Each endpoint that can be communicated with via SOAP/XML is represented as a servlet (and published within JNDI). Fortunately for the developer, this use of servlets occurs transparently. The only drawback is that (currently) clients must reside within a domain capable of hosting servlets, i.e., an application server. It is our intention that future versions of XTS will provide configurable deployment options, allowing servlets where required, but not mandating them.
</para>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-JBossTS_Web_Services_transactions_overview-SOAP">
<title>SOAP</title>
<para>
SOAP has emerged as the de-facto message format for XML-based communication in the Web services arena. It is a lightweight protocol that allows the user to define the content of a message and to provide hints as to how recipients should process that message.
@@ -73,12 +73,13 @@
<para>
SOAP messages can be divided into two main categories: Remote Procedure Call (RPC) and Document Exchange (DE). The primary difference between the two categories is that the SOAP specification defines encoding rules and conventions for RPC. The document exchange model allows the exchange of arbitrary XML documents - a key ingredient of B2B document exchange. XTS is based on the loosely coupled document-exchange style, yet it can support transactions spanning Web service that use either document-exchange or RPC.
</para>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-JBossTS_Web_Services_transactions_overview-Web_Services_Description_Language_WSDL">
<title>Web Services Description Language (WSDL)</title>
<para>
WSDL is an XML-based language used to define Web service interfaces. An application that consumes a Web service parses the service’s WSDL document to discover the location of the service, the operations that the service supports, the protocol bindings the service supports (SOAP, HTTP, etc), and how to access them (for each operation, WSDL describes the format that the client must follow).
</para>
</formalpara>
</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-07-28 02:06:20 UTC (rev 76277)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Participants.xml 2008-07-28 02:35:53 UTC (rev 76278)
@@ -2,32 +2,32 @@
<!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-Participants">
+<chapter id="chap-Transactions_Web_Services_Programmers_Guide-Test">
<title>Test</title>
<para>
This is a test paragraph
</para>
- <section id="Transactions_Web_Services_Programmers_Guide-Participants-The_Participant:_an_Overview">
+ <section id="sect-Transactions_Web_Services_Programmers_Guide-Test-The_Participant_an_Overview">
<title>The Participant: an Overview</title>
<para>
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"/>
+ <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>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-The_Participant_an_Overview-Atomic_Transaction">
<title>Atomic Transaction</title>
<para>
All Atomic Transaction participants are instances of one of the following interfaces.
</para>
</formalpara>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-The_Participant_an_Overview-Durable2PCParticipant">
<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:
@@ -65,7 +65,7 @@
</para>
</listitem>
</itemizedlist>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-The_Participant_an_Overview-Volatile2PCParticipant">
<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:
@@ -103,13 +103,13 @@
</para>
</listitem>
</itemizedlist>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-The_Participant_an_Overview-Business_Activity">
<title>Business Activity</title>
<para>
All Business Activity participants are instances of the following interfaces.
</para>
</formalpara>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-The_Participant_an_Overview-BusinessAgreementWithParticipantCompletion">
<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:
@@ -147,7 +147,7 @@
</para>
</listitem>
</itemizedlist>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-The_Participant_an_Overview-BusinessAgreementWithCoordinatorCompletion">
<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:
@@ -190,7 +190,7 @@
</para>
</listitem>
</itemizedlist>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-The_Participant_an_Overview-BAParticipantManager">
<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.
@@ -218,18 +218,18 @@
</itemizedlist>
</section>
- <section id="Transactions_Web_Services_Programmers_Guide-Participants-Participant_Creation_and_Deployment">
+ <section id="sect-Transactions_Web_Services_Programmers_Guide-Test-Participant_Creation_and_Deployment">
<title>Participant Creation and Deployment</title>
<para>
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>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-Participant_Creation_and_Deployment-Implementing_Participants">
<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.
+ 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>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-Participant_Creation_and_Deployment-Deploying_Participants">
<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.
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Preface.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Preface.xml 2008-07-28 02:06:20 UTC (rev 76277)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Preface.xml 2008-07-28 02:35:53 UTC (rev 76278)
@@ -2,14 +2,11 @@
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
-<preface id="Transactions_Web_Services_Programmers_Guide-Preface">
+<preface id="pref-Transactions_Web_Services_Programmers_Guide-Preface">
<title>Preface</title>
<para>
</para>
- <xi:include href="Common_Content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude">
- <xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude">
- <xi:include href="Common_Content/Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- </xi:fallback>
- </xi:include>
+ <xi:include href="Common_Content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+ <xi:include href="Common_Content/Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</preface>
+
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Revision_History.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Revision_History.xml 2008-07-28 02:06:20 UTC (rev 76277)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Revision_History.xml 2008-07-28 02:35:53 UTC (rev 76278)
@@ -18,3 +18,4 @@
</revdescription>
</revision>
</revhistory>
+
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-07-28 02:06:20 UTC (rev 76277)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Stand-alone_Coordinator.xml 2008-07-28 02:35:53 UTC (rev 76278)
@@ -2,15 +2,16 @@
<!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-Stand-alone_Coordinator">
+<chapter id="chap-Transactions_Web_Services_Programmers_Guide-Stand_alone_Coordinator">
<title>Stand-alone Coordinator</title>
<para>
</para>
- <section id="Transactions_Web_Services_Programmers_Guide-Stand-alone_Coordinator-Introduction">
+ <section id="sect-Transactions_Web_Services_Programmers_Guide-Stand_alone_Coordinator-Introduction">
<title>Introduction</title>
<para>
For configuring a stand-alone Web Services transaction coordinator, see the relevant chapter in the System Administrator’s Guide.
</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-07-28 02:06:20 UTC (rev 76277)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/The_XTS_API.xml 2008-07-28 02:35:53 UTC (rev 76278)
@@ -2,23 +2,23 @@
<!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-The_XTS_API">
+<chapter id="chap-Transactions_Web_Services_Programmers_Guide-The_XTS_API">
<title>The XTS API</title>
<para>
</para>
- <section id="Transactions_Web_Services_Programmers_Guide-The_XTS_API-Introduction">
+ <section id="sect-Transactions_Web_Services_Programmers_Guide-The_XTS_API-Introduction">
<title>Introduction</title>
<para>
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-The_XTS_API-API_for_the_Atomic_Transaction_protocol">
+ <section id="sect-Transactions_Web_Services_Programmers_Guide-The_XTS_API-API_for_the_Atomic_Transaction_protocol">
<title>API for the Atomic Transaction protocol</title>
<para>
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>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-API_for_the_Atomic_Transaction_protocol-Vote">
<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>:
@@ -66,13 +66,13 @@
}
}
</screen>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-API_for_the_Atomic_Transaction_protocol-The_transaction_context">
<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>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-API_for_the_Atomic_Transaction_protocol-TxContext">
<title>TxContext</title>
<para>
<code>com.arjuna.mw.wst.TxContext</code> is an opaque representation of a transaction context.
@@ -90,7 +90,7 @@
</para>
</listitem>
</itemizedlist>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-API_for_the_Atomic_Transaction_protocol-UserTransaction">
<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.
@@ -105,13 +105,13 @@
<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>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-API_for_the_Atomic_Transaction_protocol-UserTransactionFactory">
<title>UserTransactionFactory</title>
<para>
UserTransactions are obtained from a <code>UserTransactionFactory</code>.
</para>
</formalpara>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-API_for_the_Atomic_Transaction_protocol-TransactionManager">
<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.
@@ -141,18 +141,19 @@
</para>
</listitem>
</itemizedlist>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-API_for_the_Atomic_Transaction_protocol-TransactionFactory">
<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">
+
+ <section id="sect-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>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-API_for_the_Business_Activity_protocol-UserBusinessActivity">
<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.
@@ -170,13 +171,13 @@
<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>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-API_for_the_Business_Activity_protocol-UserBusinessActivityFactory">
<title>UserBusinessActivityFactory</title>
<para>
UserBusinessActivities are obtained from a <code>UserBusinessActivityFactory</code>.
</para>
</formalpara>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-API_for_the_Business_Activity_protocol-BusinessActivityManager">
<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.
@@ -206,7 +207,7 @@
</para>
</listitem>
</itemizedlist>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-API_for_the_Business_Activity_protocol-BusinessActivityManagerFactory">
<title>BusinessActivityManagerFactory</title>
<para>
BusinessActivityManagers are obtained from a <code>BusinessActivityManagerFactory</code>.
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-07-28 02:06:20 UTC (rev 76277)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Transactional_Web_Services.xml 2008-07-28 02:35:53 UTC (rev 76278)
@@ -2,18 +2,18 @@
<!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-Transactional_Web_Services">
+<chapter id="chap-Transactions_Web_Services_Programmers_Guide-Transactional_Web_Services">
<title>Transactional Web Services</title>
<para>
</para>
- <section id="Transactions_Web_Services_Programmers_Guide-Transactional_Web_Services-Introduction">
+ <section id="sect-Transactions_Web_Services_Programmers_Guide-Transactional_Web_Services-Introduction">
<title>Introduction</title>
<para>
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-Transactional_Web_Services-A_Transactional_Web_Service">
+ <section id="sect-Transactions_Web_Services_Programmers_Guide-Transactional_Web_Services-A_Transactional_Web_Service">
<title>A Transactional Web Service</title>
<para>
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.
@@ -23,7 +23,7 @@
</para>
<mediaobject>
<imageobject>
- <imagedata fileref="images/Context_Handlers.png" format="PNG"/>
+ <imagedata fileref="images/Context_Handlers.png" format="PNG" />
</imageobject>
<caption>Context Handlers Registered with the SOAP Server</caption>
</mediaobject>
@@ -32,7 +32,7 @@
</para>
<mediaobject>
<imageobject>
- <imagedata fileref="images/Back-End_Integration.png" format="PNG"/>
+ <imagedata fileref="images/Back-End_Integration.png" format="PNG" />
</imageobject>
<caption>General Pattern for Back-End Integration, Service Side</caption>
</mediaobject>
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Transactions_Overview.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Transactions_Overview.xml 2008-07-28 02:06:20 UTC (rev 76277)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Transactions_Overview.xml 2008-07-28 02:35:53 UTC (rev 76278)
@@ -2,7 +2,7 @@
<!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-Transactions_Overview">
+<chapter id="chap-Transactions_Web_Services_Programmers_Guide-Transactions_Overview">
<title>Transactions Overview</title>
<para>
Transactions have emerged as the dominant paradigm for coordinating interactions between parties in a distributed system, and in particular to manage applications that require concurrent access to shared data. Much of the JBossTS Web Service API is based on contemporary transaction APIs whose familiarity will enhance developer productivity and lessen the learning curve. While the following section provides the essential information that you should know before starting to use XTS for building transactional Web Services, it should not be treated as a definitive reference to all transactional technology.
@@ -37,11 +37,11 @@
</itemizedlist>
<mediaobject>
<imageobject>
- <imagedata fileref="images/Web_Services.png" format="PNG"/>
+ <imagedata fileref="images/Web_Services.png" format="PNG" />
</imageobject>
<caption>Web Services and XTS</caption>
</mediaobject>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-Transactions_Overview-The_Coordinator">
<title>The Coordinator</title>
<para>
Associated with every transaction is a coordinator, which is responsible for governing the outcome of the transaction. The coordinator may be implemented as a separate service or may be co-located with the user for improved performance. Each coordinator is created by the transaction manager service, which is in effect a factory for those coordinators.
@@ -53,7 +53,7 @@
<para>
A transaction manager is typically responsible for managing coordinators for many transactions. The initiator of the transaction (for example, the client) communicates with a transaction manager and asks it to start a new transaction and associate a coordinator with the transaction. Once created, the context can be propagated to Web services in order for them to associate their work with the transaction.
</para>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-Transactions_Overview-The_Transaction_Context">
<title>The Transaction Context</title>
<para>
In order for a transaction to span a number of services, certain information has to be shared between those services in order to propagate information about the transaction. This information is known as the Context. Using XTS, the context is automatically propagated and processed by transaction-aware components of an application. Though XTS removes most of the work associated with propagating contexts, it is still instructive to understand what information is captured in a context:
@@ -73,14 +73,14 @@
</itemizedlist>
<mediaobject>
<imageobject>
- <imagedata fileref="images/Context_Flow.png" format="PNG"/>
+ <imagedata fileref="images/Context_Flow.png" format="PNG" />
</imageobject>
<caption>Web Services and Context Flow</caption>
</mediaobject>
<para>
As shown in Figure 2, whenever an application message is sent, the XTS Client API automatically creates a context and embeds it into the message. Similarly, any transaction-aware services are able to extract that context using the XTS service-side infrastructure and use it to perform work within the context of a particular transaction – even though that transaction was initiated elsewhere on the Web! The value of this approach is that the business logic contained within the client application and services are not peppered with transaction-processing code.
</para>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-Transactions_Overview-ACID_Transactions">
<title>ACID Transactions</title>
<para>
Traditionally, transaction processing systems support ACID properties. ACID is an acronym for Atomic, Consistent, Isolated, and Durable. A unit of work has traditionally been considered transactional only if the ACID properties are maintained:
@@ -108,7 +108,7 @@
</para>
</listitem>
</itemizedlist>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-Transactions_Overview-Two_Phase_Commit">
<title>Two-Phase Commit</title>
<para>
The classical two-phase commit approach is the bedrock of JBossTS (and more generally of Web Services transactions). Two-phase commit provides coordination of parties that are involved in a transaction. In general, the flow of a two-phase commit transaction is as follows:
@@ -143,7 +143,7 @@
</itemizedlist>
<mediaobject>
<imageobject>
- <imagedata fileref="images/Commit_Protocol.png" format="PNG"/>
+ <imagedata fileref="images/Commit_Protocol.png" format="PNG" />
</imageobject>
<caption>The Two-Phase Commit Protocol</caption>
</mediaobject>
@@ -152,7 +152,7 @@
During two-phase commit transactions, coordinators and resources keep track of activity in non-volatile data stores so that they can recover in the case of a failure.
</para>
</note>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-Transactions_Overview-The_synchronization_protocol">
<title>The synchronization protocol</title>
<para>
As well as the two-phase commit protocol, traditional transaction processing systems employ an additional protocol, often referred to as the synchronization protocol. If you recall the original ACID properties, then you’ll remember that Durability is important in the case where state changes have to be available despite failures. What this means is that applications interact with a persistence store of some kind (e.g., a database) and this can impose a significant overhead – disk access is orders of magnitude slower than access to main computer memory.
@@ -189,7 +189,7 @@
<para>
Unlike the two-phase commit protocol, the synchronization protocol does not have the same failure requirements. For example, Synchronization participants don’t need to make sure they can recover in the event of failures; this is because any failure before the two-phase commit protocol completes means the transaction will roll back, and failures after it has completed can’t affect the data the Synchronization participants were managing.
</para>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-Transactions_Overview-Optimizations_to_the_protocol">
<title>Optimizations to the protocol</title>
<para>
There are several variants to the standard two-phase commit protocol that are worth knowing about because they can have an impact on performance and failure recovery. We shall briefly describe those that are the most common variants on the protocol:
@@ -212,7 +212,7 @@
</para>
</listitem>
</itemizedlist>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-Transactions_Overview-Non_atomic_transactions_and_heuristic_outcomes">
<title>Non-atomic transactions and heuristic outcomes</title>
<para>
In order to guarantee atomicity, the two-phase commit protocol is necessarily blocking. What this means is that as a result of failures, participants may remain blocked for an indefinite period of time even if failure recovery mechanisms exist. Some applications and participants simply cannot tolerate this blocking.
@@ -252,7 +252,7 @@
<para>
Heuristic decisions should be used with care and only in exceptional circumstances since there is the possibility that the decision will differ from that determined by the transaction service and will thus lead to a loss of integrity in the system. Having to perform resolution of heuristics is something you should try to avoid, either by working with services/participants that don’t cause heuristics, or by using a transaction service that provides assistance in the resolution process.
</para>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-Transactions_Overview-A_New_Transaction_Protocol">
<title>A New Transaction Protocol</title>
<para>
Many component technologies offer mechanisms for coordinating ACID transactions based on two-phase commit semantics (i.e., CORBA/OTS, JTS/JTA, MTS/MSDTC). ACID transactions are not suitable for all Web services transactions since:
@@ -270,7 +270,7 @@
</para>
</listitem>
</itemizedlist>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-Transactions_Overview-Adressing_the_Problems_of_Transactioning_in_Loosely_Coupled_Systems">
<title>Adressing the Problems of Transactioning in Loosely Coupled Systems</title>
<para>
Though extended transaction models which relax the ACID properties have been proposed over the years, to implement these concepts for the Web services architecture WS-T provides a new transaction protocol. XTS is designed to accommodate four underlying requirements inherent in any loosely coupled architecture like Web services:
Modified: projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Transactions_Web_Services_Programmers_Guide.xml
===================================================================
--- projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Transactions_Web_Services_Programmers_Guide.xml 2008-07-28 02:06:20 UTC (rev 76277)
+++ projects/docs/enterprise/4.3/Transactions/Transactions_Web_Services_Programmers_Guide/en-US/Transactions_Web_Services_Programmers_Guide.xml 2008-07-28 02:35:53 UTC (rev 76278)
@@ -3,16 +3,16 @@
]>
<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="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="WS-C_WS-Atomic_Transaction_and_WS-Business_Activity_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="Transactional_Web_Services.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="Stand-alone_Coordinator.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="The_XTS_API.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Appendix.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+ <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+ <xi:include href="Introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+ <xi:include href="Transactions_Overview.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+ <xi:include href="WS-C_WS-Atomic_Transaction_and_WS-Business_Activity_Overview.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+ <xi:include href="Getting_Started.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+ <xi:include href="Transactional_Web_Services.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+ <xi:include href="Participants.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+ <xi:include href="Stand-alone_Coordinator.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+ <xi:include href="The_XTS_API.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+ <xi:include href="Appendix.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
</book>
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-07-28 02:06:20 UTC (rev 76277)
+++ 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-07-28 02:35:53 UTC (rev 76278)
@@ -2,11 +2,11 @@
<!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-WS-C_WS-Atomic_Transaction_and_WS-Business_Activity_Overview">
+<chapter id="chap-Transactions_Web_Services_Programmers_Guide-WS_C_WS_Atomic_Transaction_and_WS_Business_Activity_Overview">
<title>WS-C, WS-Atomic Transaction and WS-Business Activity Overview</title>
<para>
</para>
- <section id="Transactions_Web_Services_Programmers_Guide-WS-C_WS-Atomic_Transaction_and_WS-Business_Activity_Overview-Introduction">
+ <section id="sect-Transactions_Web_Services_Programmers_Guide-WS_C_WS_Atomic_Transaction_and_WS_Business_Activity_Overview-Introduction">
<title>Introduction</title>
<para>
This section provides fundamental concepts associated with WS-C, WS-Atomic Transaction and WS-Business Activity. All of these concepts are defined in the WS-C, WS-Atomic Transaction and WS-Business Activity specifications. WS-C, WS-Atomic Transaction and WS-Business Activity principles are discussed throughout this guide.
@@ -18,7 +18,7 @@
</note>
</section>
- <section id="Transactions_Web_Services_Programmers_Guide-WS-C_WS-Atomic_Transaction_and_WS-Business_Activity_Overview-WS-Coordination">
+ <section id="sect-Transactions_Web_Services_Programmers_Guide-WS_C_WS_Atomic_Transaction_and_WS_Business_Activity_Overview-WS_Coordination">
<title>WS-Coordination</title>
<para>
In general terms, coordination 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 in order to reach consensus on a decision like in a distributed transaction protocol, or simply to guarantee that all participants obtain a specific message, as occurs in a reliable multicast environment. When parties are being coordinated, information known as the coordination context 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 and is specific to the type of coordination being performed.
@@ -31,7 +31,7 @@
</para>
<mediaobject>
<imageobject>
- <imagedata fileref="images/WS-C_Architecture.png" format="PNG"/>
+ <imagedata fileref="images/WS-C_Architecture.png" format="PNG" />
</imageobject>
<caption>WS-C architecture</caption>
</mediaobject>
@@ -65,16 +65,16 @@
</para>
<mediaobject>
<imageobject>
- <imagedata fileref="images/WS-C_Infrastructure.png" format="PNG"/>
+ <imagedata fileref="images/WS-C_Infrastructure.png" format="PNG" />
</imageobject>
<caption>WS-C infrastructure</caption>
</mediaobject>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-WS_Coordination-Activation">
<title>Activation</title>
<para>
The WS-Coordination framework exposes an Activation Service which supports the creation of coordinators for specific protocols and their associated contexts. The process of invoking an activation service is done asynchronously, and so the specification defines both the interface of the activation service itself, and that of the invoking service, so that the activation service can call back to deliver the results of the activation – namely a context that identifies the protocol type and coordinator location. These interfaces are presented in Figure 6, where the activation service has a one-way operation that expects to receive a <code>CreateCoordinationContext</code> message and correspondingly the service that sent the <code>CreateCoordinationContext</code> message expects to be called back with a <code>CreateCoordinationContextResponse</code> message, or informed of a problem via an <code>Error</code> message.
</para>
- </formalpara>
+ </formalpara>
<screen>
<!-- Activation Service portType Declaration -->
<wsdl:portType name="ActivationCoordinatorPortType">
@@ -96,7 +96,7 @@
</wsdl:operation>
</wsdl:portType>\
</screen>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-WS_Coordination-Registration">
<title>Registration</title>
<para>
Once a coordinator has been instantiated and a corresponding context created by the activation service, a Registration Service is created and exposed. This service allows participants to register to receive protocol messages associated with a particular coordinator. Like the activation service, the registration service assumes asynchronous communication and so specifies WSDL for both registration service and registration requester, as shown below.
@@ -123,19 +123,20 @@
<para>
When a participant is registered with a coordinator through the registration service, it receives messages that the coordinator sends (for example, “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>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-WS_Coordination-Completion">
<title>Completion</title>
<para>
The role of terminator is generally played by the client application, which at an appropriate point will ask the coordinator to perform its particular coordination function with any registered participants – to drive the protocol through to its completion. On completion, the client application may be informed of an outcome for the activity which may vary from simple succeeded/failed notification through to complex structured data detailing the activity’s status.
</para>
</formalpara>
</section>
- <section id="Transactions_Web_Services_Programmers_Guide-WS-C_WS-Atomic_Transaction_and_WS-Business_Activity_Overview-WS-Transaction">
+
+ <section id="sect-Transactions_Web_Services_Programmers_Guide-WS_C_WS_Atomic_Transaction_and_WS_Business_Activity_Overview-WS_Transaction">
<title>WS-Transaction</title>
<para>
In the past, making traditional transaction systems talk to one another was a holy grail that was rarely achieved. With the advent of Web services, there is an opportunity to leverage an unparalleled interoperability technology to splice together existing transaction processing systems that already form the backbone of enterprise level applications.
</para>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-WS_Transaction-WS_Coordination_Foundations">
<title>WS-Coordination Foundations</title>
<para>
An important aspect of WS-Transaction that differentiates it from traditional transaction protocols is that a synchronous request/response model is not assumed. This model derives from the fact that WS-Transaction is, as shown in the figure below, layered upon the WS-Coordination protocol whose own communication patterns are asynchronous by default.
@@ -143,14 +144,14 @@
</formalpara>
<mediaobject>
<imageobject>
- <imagedata fileref="images/WS-Coordination_Foundations.png" format="PNG"/>
+ <imagedata fileref="images/WS-Coordination_Foundations.png" format="PNG" />
</imageobject>
<caption>WS-Coordination WS-Atomic Transaction and WS-Business Activity</caption>
</mediaobject>
<para>
Web Services Coordination provides a generic framework for specific coordination protocols, like WS-Transaction, to be plugged in. Recall that WS-Coordination provides only context management – it allows contexts to be created and activities to be registered with those contexts. WS-Transaction leverages the context management framework provided by WS-Coordination in two ways. Firstly it extends the WS-Coordination context to create a transaction context. Secondly, it augments the activation and registration services with a number of additional services (Completion, CompletionWithAck, PhaseZero, 2PC, OutcomeNotification, BusinessAgreement, and BusinessAgreementWithComplete) 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 the WS-Coordination protocol infrastructure.
</para>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-WS_Transaction-WS_Transaction_Architecture">
<title>WS-Transaction Architecture</title>
<para>
WS-Transaction supports the notion of 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 above.
@@ -158,19 +159,19 @@
</formalpara>
<mediaobject>
<imageobject>
- <imagedata fileref="images/WS-Transaction_Global_View.png" format="PNG"/>
+ <imagedata fileref="images/WS-Transaction_Global_View.png" format="PNG" />
</imageobject>
<caption>WS-Transaction Global View</caption>
</mediaobject>
<para>
- A transaction-aware service encapsulates the business logic or work that is required to be conducted within the scope of a transaction. This work cannot be confirmed by the application unless the transaction also commits and so control is ultimately removed from the application and placed into the transaction’s domain.
+ A transaction-aware service encapsulates the business logic or work that is required to be conducted within the scope of a transaction. This work cannot be confirmed by the application unless the transaction also commits and so control is ultimately removed from the application and placed into the transaction’s domain.
</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 the figure above each service is shown with one associated participant that manages the transaction protocol messages on behalf of its service, while in the figure below, there is a close-up view of a single service, and a client application with their associated participants.
+ 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 the figure above each service is shown with one associated participant that manages the transaction protocol messages on behalf of its service, while in the figure below, there is a close-up view of a single service, and a client application with their associated participants.
</para>
<mediaobject>
<imageobject>
- <imagedata fileref="images/Transactional_Service_and_Participant.png" format="PNG"/>
+ <imagedata fileref="images/Transactional_Service_and_Participant.png" format="PNG" />
</imageobject>
<caption>Transactional Service and Participant</caption>
</mediaobject>
@@ -180,7 +181,7 @@
<para>
At the client end, things are less complex. Through its API, the client application registers a participant with the transaction through which it controls transaction termination.
</para>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-WS_Transaction-WS_Transaction_Models">
<title>WS-Transaction Models</title>
<para>
Given that traditional transaction models are not appropriate for Web services, the following question must be posed, “what type of model or protocol is appropriate?” The answer to that question is that that no one specific protocol is likely to be sufficient, given the wide range of situations that Web service transactions are likely to be deployed within. Hence the WS-Transaction specification proposes two distinct models, where each supports the semantics of a particular kind of B2B interaction. The following sections shall discuss these two WS-Transaction models.
@@ -191,7 +192,7 @@
As with WS-Coordination, the two WS-Transaction models are extensible allowing implementations to tailor the protocols as they see fit (for example, to suit their deployment environments).
</para>
</note>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-WS_Transaction-Atomic_Transactions_AT">
<title>Atomic Transactions (AT)</title>
<para>
An atomic transaction or AT is similar to traditional ACID transactions and intended 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 then propagated to each enlisted resource via the participant, and the appropriate commit or rollback actions are taken by each.
@@ -207,10 +208,10 @@
After obtaining a transaction context from the coordinator, the client application then proceeds to interact with Web services to accomplish its business-level work. With each invocation on 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.
</para>
<para>
- Once all the necessary application level work has been completed, the client can terminate the transaction, with the intent of making any changes to the service state permanent. To do this, the client application first registers its own participant for the Completion protocol. Once registered, the participant can instruct the coordinator either to try to commit or rollback the transaction. When the commit or rollback operation has completed, a status is returned to the participant to indicate the outcome of the transaction.
+ Once all the necessary application level work has been completed, the client can terminate the transaction, with the intent of making any changes to the service state permanent. To do this, the client application first registers its own participant for the Completion protocol. Once registered, the participant can instruct the coordinator either to try to commit or rollback the transaction. When the commit or rollback operation has completed, a status is returned to the participant to indicate the outcome of the transaction.
</para>
<para>
- While the completion protocol is straightforward, they hide the fact that in order to resolve to an outcome that several other protocols need to be executed.
+ While the completion protocol is straightforward, they hide the fact that in order to resolve to an outcome that several other protocols need to be executed.
</para>
<para>
The first of these protocols is the optional Volatile2PC. The Volatile2PC protocol is the WS-Atomic Transaction equivalent of the synchronization protocol we discussed earlier. It is typically executed where a Web service needs to flush volatile (cached) state, which may be being used to improve performance of an application, to a database prior to the transaction committing. Once flushed, the data will then be controlled by a two-phase aware participant.
@@ -231,11 +232,15 @@
If a transaction involves only a single participant, WS-Atomic Transaction supports a one-phase commit optimization. Since there is only one participant, its decisions implicitly reach consensus, and so the coordinator need not drive the transaction through both phases. In the optimized case, the participant will simply be told to commit and the transaction coordinator need not record information about the decision since the outcome of the transaction is solely down to that single participant.
</para>
<para>
- The figure below<footnote><para>Redrawn from the WS-Atomic Transaction specification.</para></footnote> shows the state transitions of a WS-Atomic Transaction and the message exchanges between coordinator and participant; the coordinator generated messages are shown in the solid line, whereas the participant messages are shown by dashed lines.
+ The figure below<footnote>
+ <para>
+ Redrawn from the WS-Atomic Transaction specification.
+ </para>
+ </footnote> shows the state transitions of a WS-Atomic Transaction and the message exchanges between coordinator and participant; the coordinator generated messages are shown in the solid line, whereas the participant messages are shown by dashed lines.
</para>
<mediaobject>
<imageobject>
- <imagedata fileref="images/Commit_State_Transitions.png" format="PNG"/>
+ <imagedata fileref="images/Commit_State_Transitions.png" format="PNG" />
</imageobject>
<caption>Two-Phase Commit State Transitions</caption>
</mediaobject>
@@ -253,18 +258,18 @@
</para>
<mediaobject>
<imageobject>
- <imagedata fileref="images/AT_Model.png" format="PNG"/>
+ <imagedata fileref="images/AT_Model.png" format="PNG" />
</imageobject>
<caption>The AT Model</caption>
</mediaobject>
- <formalpara>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-WS_Transaction-Business_Activities_BA">
<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.
+ 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.
@@ -313,7 +318,7 @@
<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>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-WS_Transaction-Application_Messages">
<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.
@@ -324,7 +329,7 @@
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>
+ <formalpara id="form-Transactions_Web_Services_Programmers_Guide-WS_Transaction-WS_C_WS_Atomic_Transaction_and_WS_Business_Activity_Messages">
<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.
@@ -339,11 +344,13 @@
</para>
</note>
</section>
- <section id="Transactions_Web_Services_Programmers_Guide-WS-C_WS-Atomic_Transaction_and_WS-Business_Activity_Overview-Summary">
+
+ <section id="sect-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