Making web services enterprise-ready

Using the WS-Atomic Transaction protocol and WebSphere Application Server

This article describes how you can make your web services enterprise-ready using the WS-Atomic Transaction (WS-AT) protocols in conjunction with IBM® WebSphere® Application Server's unparalleled transaction, high availability, and failover support. Beginning with a close look at the protocol itself and the WebSphere Application Server specifics (when running a web services client or the web services provider), the article will depict the optimizations that are being used when both client and service provider use WebSphere Application Server as the runtime platform, and show you how to setup a high-availabilty, scalable, production-ready environment on which to run your WS-AT enabled web services. This content is part of the IBM WebSphere Developer Technical Journal.


Konstantin Luttenberger (, IT Specialist, IBM

Konstantin LuttenbergerKonstantin Luttenberger has worked with IBM Software Services for WebSphere (ISSW) Germany since 2006. He supported different customers in implementing Web Services and in setting up highly available and scalable infrastructures using WebSphere technologies.

Oliver Rebmann (, Senior IT Specialist, IBM China

Author photoOliver Rebmann is a member of IBM Software Services for WebSphere (ISSW) Germany. As Senior IT Specialist for WebSphere Application Server, he acts as Trusted Advisor for many large-scale German customers regarding development and operational issues of distributed transactional applications.

09 May 2012


Transactions have long been used in business applications to ensure data consistency during complex parallel user operations. Online transactional processing applications have become quite popular, and with the rising popularity of the Internet and the growing always-online mentality, the mass of users and parallelism of interactions have increased steadily.

A transaction is a set of data manipulations following the well-known ACID principle:

  • Atomicity: "all or nothing," either the transaction as a whole succeeds or fails.
  • Consistency: data before and after the transaction must be in a consistent state.
  • Isolation: parallel transactions act isolated from each other; it appears as though they are running sequentially.
  • Durability: data state after a successful transaction is persistent; survives a crash.

Apart from beginning a transaction, there are only two operations available to control the outcome of a transaction:

  • Commit to finish the transaction successfully and persist the outcome.
  • Rollback to discard all data manipulations performed since the transaction began.

There is an important distinction between local and global transactions. Local transactions, often more precisely called resource-manager local transactions (RMLT), are transactions with which an application interacts with only one resource (for example, one database). The progress of a local transaction can be handled by the single resource manager itself.

In contrast, a global transaction is established when an application interacts with multiple resources in one transaction (for example, a database and a messaging system, or two databases).

A global transaction needs a neutral instance managing the outcome of the overall transaction using a common language (protocol) all participating resources can understand. This neutral instance is called the transaction manager the common protocol used in Java® applications follows the Distributed Transaction Processing: The XA Specification protocol (see Resources).

Apart from involving multiple resource managers in one transaction, it is also possible to involve other transaction managers (residing in different processes or on different systems) in one transaction context. This is called distributed transaction processing. The original transaction manager involved in this context often is called the root transaction manager, whereas the other transaction managers are called subordinates or participants.

WebSphere Application Server provides a high-volume built-in transaction manager that adheres to the ACID criteria and implements the XA protocol. Furthermore, the WebSphere Application Server transaction manager allows for distributed transactions following a set of standard transactional interoperability protocols:

  • Internet Inter ORB protocol (IIOP)
  • EIS using JCA (Inbound only)
  • WS-AT.

WS-AT is a specification that extends the reach of traditional transaction behavior to the web services world. Its sibling in the WS-Transaction area (see Resources) is WS-Business Activity (WS-BA), which defines compensation mechanisms for atomic business activities. Both specifications are part of the WS-Transaction (WS-Tx) group. The focus of this article is WS-AT.

The WS-AT specification is built primarily on two other web service specifications:

  • WS-Addressing introduces the concept of an endpoint reference that describes an endpoint (and how to pass additional information to this endpoint).
  • WS-Coordination introduces the concept of a coordinator you can use to activate or create (CreateCoordinationContext) contexts and register (Register) participants using these contexts. Aside from the activation and registration functionality, the specification sketches a third main building block, a protocol service that provides a common extension point for the definition of new concrete protocols (such as WS-AT).

Figure 1 depicts the basic concepts and message/protocol flows and the relations between the specifications.

Figure 1. WS-AT initial message flow
Figure 1. WS-AT initial message flow

WS-AT is primarily a protocol extension of WS-Coordination that defines one main rule for the activation/registration process:

  • If a context is already present on the web service request -> register as subordinate to the root coordinator.
  • If no context is present on the web service request -> create a new context and become the root coordinator.

Apart from this extension or clarification regarding the activation and registration process, the main part of the WS-AT specification defines the actual protocols being used to bring transactionality to the web services world. These protocols deal with the communication flows between the coordinator and the application, as well as with the communication flows between root coordinator and subordinate/participant coordinators.

For this purpose, WS-AT defines these protocols:

  • Completion: initiate commit/rollback processing.
  • Two-phase commit (2PC): perform commit/rollback processing
    • Volatile 2 PC: coordinators managing volatile resources, such as caches.
    • Durable 2 PC: coordinators managing durable resources, such as databases.

Figure 2 shows these protocols in action.

Figure 2. WS-AT protocol overview
Figure 2. WS-AT protocol overview

The Completion protocol defines the interface between the initiating application and the root coordinator, whereas the 2PC protocols describe the message flows between the root coordinator and its subordinates starting when completion is triggered. As the name implies, the 2PC protocol in WS-AT consist of two phases:

  1. In the prepare phase, every subordinate needs to agree that it is ready to commit/abort, depending on the completion direction. The subordinates managing volatile resources (registered for the Volatile 2 PC protocol) are queried first. These subordinates do not participate in phase two. Apart from agreeing, a subordinate can also answer with Read-Only, which means there were no data modifications on the subordinate during the transaction.
  2. In the commit phase, every subordinate that is not volatile and that has not answered with the Read-Only optimization, is being sent the commit message by the root coordinator.

The root coordinator informs the application of the outcome using the WS-AT Completion protocol.

WS-AT and WebSphere Application Server really are a perfect match. WS-AT in WebSphere Application Server is implemented using the proven transaction manager underneath, which has provided global and distributed transaction support for mission critical applications for years. In addition to the raw transactional functionality you automatically benefit from all availability and administration features the WebSphere Application Server transaction manager provides, such as peer transaction recovery. Furthermore, running your WS-AT enabled application in WebSphere Application Server gives you the capability of developing composite transactional applications consisting of web services combined with traditional Java workload; for example, you might implement a web service that calls a remote EJB and another web service within the same transaction.

Later, you will get a closer look at how WS-AT and WebSphere Application Server work together under the covers from a web service client perspective, as well as from a web service provider perspective. We’ll dive into the WS-AT communication flows when WebSphere Application Server is being used as either the client or server runtime environment, and explain the optimizations that are in-place when you use WebSphere Application Server as both client and server runtime platform.

The remainder of this article is presented in three main sections. We’ll begin with the web service client perspective, where an application running on WebSphere Application Server takes the role of the web service client and therefore initiates and manages the distributed transaction. After that, we’ll work from the perspective where the web service provider is running on WebSphere Application Server and takes part in a transaction that is initiated by another system (for example, another application server). Finally, we’ll look at the optimizations, which apply when the web service client and the web service provider, which are running on (different) WebSphere Application Server instances, are introduced.

Web service client

As defined by the WS-Coordination specification (see Resources), the first step in the WS-AT protocol is to retrieve a coordination context for further communication. Because WS-AT is all about transactions, it makes sense that in WebSphere Application Server the coordination context is retrieved from the transaction service. The example in Listing 1 shows the web service request sent by a web service client application running on WebSphere Application Server.

Listing 1. SOAP request with coordination context
<soapenv:Envelope xmlns:soapenv="">
    <wscoor:CoordinationContext soapenv:mustUnderstand="1"
        <wsa:Address xmlns:wsa="">
        <wsa:ReferenceParameters xmlns:wsa="">
          <websphere-wsat:instanceID xmlns:websphere-
         <wsaucf:RoutingInformation xmlns:wsaucf="">
    <ns2:op1 xmlns:ns2="">

You can see that the coordination context mainly transports information about the registration service, which is used by the participant (in this case the web service provider) to register for the distributed transaction. It is important to understand that all data needed by WebSphere Application Server to handle the transaction is propagated to the web service provider by the ReferenceParameters element, which, besides some routing information, contains the key information about the created transaction, such as the txID.

One question that comes to mind when thinking about WebSphere Application Server as a WS-AT web service client might be: How can WebSphere Application Server be configured to initiate the transaction and transport the information in the SOAP request headers?

To answer this question, imagine a web service client application that inserts something into a database table and then calls the web service using the JAX-WS standard. In order to perform the database call and the web service call inside a single transaction, you have to create such a transaction. This can be accomplished using the javax.transaction.UserTransaction object if your client application is implemented by a servlet or an EJB using bean managed transactions (BMT). The code in Listing 2 shows such a situation. (This scenario will be used throughout the rest of this section.) If you are dealing with EJBs using container managed transactions (CMT), the transaction handling can be controlled in a declarative manner.

Listing 2. Pseudocode transaction begin
javax.transaction.UserTransaction userTransaction = 
        (javax.transaction.UserTransaction) ctx.lookup("java:comp/UserTransaction");


// call database
// call WebService

if(everthyingOk) {
} else {

Here is what happens under the covers:

  1. Starting a user transaction by calling UserTransaction.begin() tells the WebSphere Application Server transaction service to create a transaction.
  2. When creating the connection to the database and executing the insert statement, the transaction service checks if these calls to the database should take part in the transaction started in step 1. The decision depends on the XA capability of the database driver. If the driver is supporting XA transactions, the database is registered as a resource in the transaction and therefore takes part in the XA 2PC protocol.
  3. When calling the web service, the WS-Policy standard kicks in to tell the application by configuration that the service call should take part in the transaction using WS-AT. How this so-called policy set has to be configured, is described below. According to this policy set, all needed information for the coordination context is retrieved from the transaction service and other container services.
  4. The web service request is sent to the configured service endpoint, and the service provider exchanges information with the WebSphere Application Server running the web service client according to WS-Coordination. Figure 3 illustrates this communication.
    Figure 3. Transaction registration during web service request
    Figure 3. Transaction registration during web service request
  5. The client code decides to commit (UserTransaction.commit()) or rollback (UserTransaction.rollback()) the transaction. Depending on this decision, the database is told to prepare or rollback its transaction, respectively, in the first phase of the XA 2PC protocol. The Web Service provider is informed to perform the first phase of the WS-AT 2PC protocol by sending the Prepare or to stop the processing by sending the Rollback request to the participant service. Under the covers, this is also mapped to XA transaction code.
  6. The second phase of the 2PC protocol is only entered if the transaction is to be committed, from step 5. The transaction manager calculates the transaction’s global outcome by evaluating the votes of the resources (participant service and database). The participant's response could either be the Prepared or the Aborted message.
  7. All resources are informed about the transaction’s overall outcome. If the participant is in prepared state, the commit or the abort message will be sent to it. Figure 4 illustrates steps 5-7.
    Figure 4. Possible outcomes of 2PC protocol
    Figure 4. Possible outcomes of 2PC protocol

To configure the transaction service:

  1. Start WebSphere Application Server. From the integration console, navigate to Server > Server Types > WebSphere application servers > server1 > Container Services > Transaction Service (Figure 5).
    Figure 5. Transaction service settings
    Figure 5. Transaction service settings

In addition to configuring the transaction service the following steps need to be performed to enable the policy set for the service client:

  1. In the integration console, navigate to Services > Policy Sets > Application policy sets.
  2. Click the New button. Enter a name (for example,WsatWebServicePolicySet) and add WS-Transaction in the policies section. Click OK and save the changes.
  3. Navigate to the WS-Transaction settings on the newly created policy set. Check the WS-Atomic Transaction Mandatory box (Figure 6) and save the changes.
    Figure 6. Create and attach a WS-AT policy set
    Figure 6. Create and attach a WS-AT policy set
  4. Restart the WebSphere Application Server instance.
  5. Navigate to Services > Service Clients. Click on your web service client. Select the checkbox in front of your service client. Click the Attach Client Policy Set button to add your WS-AT policy set.

Web service provider

This section addresses the situation where the service provider participating in the WS-AT protocol is running on WebSphere Application Server and the request (containing an existing WS-AT context) is sent from another system. Throughout this section, the web service provider application will be referred to as WsatWebService and the web service client application as WsatWebServiceClient.

In order that the service provider is aware of its participation and subordination in the WS-AT protocol, an equivalent policy set to the one created earlier (Figure 6) is needed. Therefore, the configuration steps remain mostly the same with the following exception: After installing the WsatWebService application on WebSphere Application Server, navigate to Services > Service Providers in the integration console, rather than Services > Service Clients, to assign the policy set. Depending on the calling system, the setting Enable transaction coordination authorization might have to be disabled for the WebSphere Application Server instance running the WsatWebService application (see Figure 5).

Suppose the application WsatWebService inserts a line into a database whose driver has to be XA capable. For simplicity reasons, only the "good case" is described here, where the distributed transaction ends with a commit. WsatWebServiceClient is responsible for creating the web service request, including the creation and retrieval of a coordination context. The WS-AT root coordination service running on the foreign system exchanges the WS-AT protocol messages with its participants.

At first sight, the resulting message exchange seems quite complex because it utilizes many different web service standards. The complete communication can be separated into two main sections:

  • The first section is the sequence of messages for exchanging the needed information to establish a valid channel to exchange the WS-AT messages using WS-Coordination. This section starts with the web service request and ends with its response. Someone might think that the web service response is sent at the end of the whole communication, and so there would be no second section. This is a common mistake. The transaction does not end with the web service response, even if the service answers with a service fault. In the latter case, no further WS-AT protocol messages are sent from the system coordinating the transaction. It is implicitly assumed that the service provider's transaction has been rolled back if it answers with a fault and so the distributed transaction has to be rolled back overall.
  • The second section during message exchange contains the "real" protocol messages defined in the WS-AT specification, such as prepare, commit, or rollback.

Let's see how the communication looks in reality:

  1. The WsatWebServiceClient application creates the web service request. In this example, a transaction identifier is integrated into the WS-Coordination Context SOAP header. The most interesting element of this header is the RegistrationService element, which contains a WSA endpoint reference (Listing 3).

    Listing 3. WS-Coordination registration service element

    	<wsa:Address xmlns:wsa="">
    	<wsa:ReferenceParameters xmlns:wsa="">
    		<dw:taId xmlns:dw="">

    The wsa:Address attribute tells the web service provider where it can register for the WS-AT protocol. The reference parameters consist only of one element, in this case dw:taId, which includes the transaction identifier mentioned above. This element represents some sort of correlation information of the foreign system.

Nested transactions

Be aware that you are not permitted to open a transaction using userTransaction.begin() in the service provider code. WebSphere Application Server has already started a transaction at this point due to the WS-Transaction policy set, and WebSphere Application Server does not support nested transactions.

  1. The web service provider running on WebSphere Application Server creates a transaction under the covers and sends this along with some other information to the address received in the first step. The relevant parts of this message are shown in Listing 4.

    Listing 4. WS-AT transaction information exchange in WebSphere Application Server

        <dw:taId wsa:IsReferenceParameter="true" 
        <Register xmlns="">

    The originating reference parameter dw:taId sent in step 1 is sent back for correlation as a SOAP header element. The SOAP body contains the address information about the WS-AT protocol service of WebSphere Application Server as a participant in the distributed transaction. The root coordinating system now has all the information needed to be able to exchange WS-AT protocol messages with its subordinate (WebSphere Application Server).
  2. In order to inform the participant about its successful registration, a RegisterResponse message is sent back as the response to the address specified in wsa:ReplyTo of step 2. This message contains mainly the address information of the coordinator protocol service in the SOAP body. At this point, all needed address information has been exchanged between root and subordinate coordinator so that the real protocol would be able to start.
  3. The service provider constructs the web service response and sends it, but WebSphere Application Server does not commit the transaction because the real protocol messages are still to come (from the root coordinator).
  4. Because only the "good case" is described here, the WsatWebServiceClient application decides to complete the transaction (using WS-AT Completion protocol). This triggers the root coordinator on WsatWebServiceClient’s side to send a WS-AT prepare request (phase one of the 2PC protocol) to the subordinate coordinator on the WsatWebService side with address information taken from step 2. The relevant parts of this message are shown in Listing 5.

    Listing 5. WS-AT prepare request


    WS-AT protocol messages are one-way messages, so they contain the wsa:ReplyTo and wsa:FaultTo elements to establish some sort of asynchronous communication pattern. The ReplyTo element is not really needed here because it contains the same information as the CoordinatorProtocol element in step 3.

Indoubt transactions

Suppose that the root coordinator has decided to commit the transaction but didn't receive the Committed acknowledgment of all participants. It is therefore not known if the participant received the message to commit, if its local resources are still in-flight, or if only the Committed message was lost on the way back from the subordinate to the root coordinator. WebSphere Application Server provides runtime tooling (via the Integrated Solution Console) to resolve such situations.

  1. The subordinate participant decides if the resources managed by the service provider can be committed or not. Depending on this decision, either the Prepared or the Aborted WS-AT message is sent to the root coordination protocol service.
  2. The root coordinator calculates the overall transaction outcome depending on all participants’ replies to the prepare request. In the "good case" discussed here, a commit message will be issued to all participants.
  3. All participants must acknowledge that they received the commit message by sending a Committed message back to the root coordinator.

Optimizations when both client and provider are running on WebSphere Application Server

Let’s now look at the situation where all participating systems in the WS-AT protocol are running on WebSphere Application Server instances, specifically how WebSphere Application Server optimizes the WS-Coordination communications to gain the needed information for protocol message exchange.

Assume that the web service client application WsatWebServiceClient is installed on one WebSphere Application Server instance and the service provider WsatWebService is on another WebSphere Application Server instance. The configuration regarding the policy set is the same for both applications, as described earlier. For this scenario, it is assumed that Enable transaction coordination authorization is enabled on both WebSphere Application Server instances.

One drawback of the WS-Coordination communication is the number of messages needed only to exchange protocol service endpoints on the root coordinator's and subordinate coordinator’s sides. WebSphere Application Server optimizes this message exchange significantly by providing all information in the web service response inside a SOAP header element, without calling the registration service endpoint provided in the web service request.

What enables WebSphere Application Server to do so? It is pretty simple: because of the reference parameters in the wscoord:CoordinationContext element of the web service request, WebSphere Application Server detects that the system that created this information must have been another WebSphere Application Server instance. Therefore, it also knows how the coordination protocol service endpoint must look like, derived from the registration service endpoint and other routing information. Therefore, the participant knows the protocol service endpoint. In a specific SOAP header, which can be seen in Listing 6, the information about the participant protocol service is sent back in the web service response.

Listing 6. WebSphere Application Server specific header in service response
      	   <wsa:Address xmlns:wsa="">

This optimization avoids one message exchange for the registration process. But where is the security information that is required when activating the Enable transaction coordination authorization option on the transaction service? This information is transported in the protocol messages. WebSphere Application Server uses the LTPA token in such a case, and therefore the LTPA keys that are used to generate an LTPA token must be the same on both WebSphere Application Server instances (see Resources).

High availability considerations

Let’s take a brief look at how to make WS-AT enabled applications production-ready in WebSphere Application Server from an operational perspective with regard to high availability and failover aspects.

As mentioned earlier, WS-AT uses WS-Coordination to exchange unique identifiers using contexts. Furthermore, WS-Addressing EndpointReferences are utilized to provide "contact addresses" between the communicating partners. As you have seen earlier, an EndpointReference mainly consists of:

  • wsa:Address: a URI
  • wsa:ReferenceParameters: additional information needed by the communication partner.

WebSphere Application Server leverages this information to exchange data about high availability and failover capabilities of target services.

Figure 7. Typical WebSphere Application Server high availabilty and failover configuration for WS-AT
Figure 7. Typical WebSphere Application Server high availabilty and failover configuration for WS-AT

The first step in providing a high-available transactional web service solution in WebSphere Application Server is to install the web service to a WebSphere Application Server (AppServer) cluster consisting of multiple AppServers residing on different nodes accessed by means of a unique virtual host name. This virtual host name is used in the URI-field (wsa:Address) of the EndpointReference.

The logical virtual host name is usually physically mapped to some IP spraying device in front of WebSphere Application Server (for example, a load balancer). The high availability of such devices is often handled by using a hot standby device as secondary, performing regular heartbeats to detect failure of the primary.

The IP sprayer delegates the incoming requests to a couple of active-active web servers running the WebSphere Application Server Plugin to determine the WebSphere Application Server target AppServers.

To allow for transaction affinity for WS-AT in WebSphere Application Server – that is, to delegate all (subsequent) requests belonging to one transaction to the same target AppServer – it is mandatory to use a WebSphere Proxy Server in front of the actual application server cluster. This proxy can be administered using the integration console of your WebSphere Application Server Network Deployment installation. The WebSphere Proxy Server interprets the information sent in the SOAP headers (especially wscoor:Identifier and wsa:ReferenceParameters) using a special WebSphere Application Server WS-Tx/AT workload management plugin. Therefore, it knows which server the request needs to be directed to. Furthermore, if this target server is down it will re-route the request to another available server in the application server cluster.

To allow this other server to recover transactions of its peer in case of failure, it is necessary to configure peer transaction recovery for the application server cluster (see Resources for details; you need a shared file system supporting lease-based locking for peer transaction recovery configuration).

To make the whole story work, you need to configure the virtual Host name as an "intermediary" in the WebSphere Application Server transaction service setting configuration (Figure 5) of the target application servers (External WS Transaction HTTP(S) URL prefix entry field).

There are several different ways to setup a high availability environment, depending on your needs. For example:

  • If you do not need or want transaction affinity, you can drop the WebSphere Proxy Servers.
  • If you are just serving web services (that is, no static HTTP resources), you can drop the web servers.

Hopefully, this gives you some ideas on what a production setup might look like in your own situation when using WS-AT and WebSphere Application Server to provide enterprise-production-ready web services.


This article showed how you can make your web services enterprise-ready making use of WS-Atomic Transaction (WS-AT) protocols in conjunction with WebSphere Application Server's unparalleled transaction, high availability, and failover support. Although you will want to investigate further aspects not covered here before you consider moving into production (such as security considerations), you hopefully gained some insight into what it takes to build, configure, and operate WS-AT enabled web services in WebSphere Application Server.


The authors thank Ian Robinson, Jon Hawkes and Jay Stidder for their comments and contributions to the article.


Code sample1205_luttenberger_attachment.zip3.4 MB



Get products and technologies


developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into WebSphere on developerWorks

ArticleTitle=Making web services enterprise-ready