Web Service Transactions

This chapter describes the concept of a web service transaction and how to configure it.

1. Overview

Transaction is a fundamental concept behind the implementation of reliable distributed applications. This mechanism ensures that all transaction participants receive the same result.

In essence, a transaction is characterized by the ACID properties.

Type Description

Atomicity

All or nothing. All updates complete successfully or they all fail.

Consistency

Only valid data are applied to the database.

Isolated

Transaction result must not affect other concurrent transactions until the transaction has been committed.

Durability

After the transaction has been committed, the updates can be recovered even in case of a system failure.

To control the operation and result of an application, a web service environment needs to provide the same coordinated behavior that is provided by the traditional transaction mechanism. It also requires a functionality that coordinates the processing of results from multiple services which requires a more flexible type of transaction.

The following are the transaction specifications supported by JEUS 9 web services.

  • WS-Coordination

  • WS-AtomicTransaction

These transaction specifications provide a WSDL definition for such coordinated behavior.

2. Server Configurations

A web service transaction for a server application is defined in a WSDL or Java class.

2.1. Configuring from WSDL

To create a web service transaction in WSDL, define a web service policy in the WSDL document and use it to create a web service through the wsimport tool.

To define a web service transaction in a WSDL file according to the web service policy, set the PolicyAssertion property as in the following.

<wsat200410:ATAssertion xmlns:ns1="http://schemas.xmlsoap.org/ws/2002/12/policy" />

The following WSDL file defines a web service transaction.

Configuring a Web Service Transaction in WSDL: <AddNumbers.wsdl>
<?xml version="1.0" encoding="UTF-8"?>
<definitions name="AddNumbersService" targetNamespace="http://server.fromwsdl/"
    xmlns:tns="http://server.fromwsdl/" xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/
    oasis-200401-wss-wssecurity-utility-1.0.xsd"
    xmlns:wsp="http://www.w3.org/ns/ws-policy"
    xmlns:wsp1_2="http://schemas.xmlsoap.org/ws/2004/09/policy"
    xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <wsp:Policy xmlns:wsat200410="http://schemas.xmlsoap.org/ws/2004/10/wsat"
        wsu:Id="AddNumbersPortBinding_addNumbers_WSAT_Policy" wsp:Name="">
        <wsat200410:ATAssertion
            xmlns:ns1="http://schemas.xmlsoap.org/ws/2002/12/policy"
            wsp:Optional="true" ns1:Optional="true" />
    </wsp:Policy>
    <types>...</types>
    <message>...</message>
    <portType>...</portType>

    <binding name="AddNumbersPortBinding" type="tns:AddNumbers">
       <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document" />
       <operation name="addNumbers">
        <wsp:PolicyReference URI="#AddNumbersPortBinding_addNumbers_WSAT_Policy" />
         <soap:operation soapAction="addNumbers" />
         <input>
           <wsp:PolicyReference URI="#AddNumbersPortBinding_addNumbers_WSAT_Policy" />
             <soap:body use="literal" />
         </input>
         <output>
           <wsp:PolicyReference URI="#AddNumbersPortBinding_addNumbers_WSAT_Policy" />
             <soap:body use="literal" />
         </output>
       </operation>
    </binding>
    <service>...</service>
<definitions>

2.2. Configuring from Java Class

To configure a web service transaction in a java class, add the following annotation in the web service endpoint implementation class.

@com.sun.xml.ws.api.tx.at.Transactional(version=com.sun.xml.ws.api.tx.at.Transactional.Version.WSAT10)

The following is an example of defining a web service transaction in a java class.

Configuring a Web Service Transaction in a Java Class: <AddnumbersImpl.java>
@WebService
@com.sun.xml.ws.api.tx.at.Transactional(
       version=com.sun.xml.ws.api.tx.at.Transactional.Version.WSAT10)
public class AddNumbersImpl {
    ...
}

3. Client Configurations

There are no additional settings for web service transaction on the client side. The client applications that invoke the web service automatically provides a web service transaction environment at runtime by remotely reading the web service transaction policy from the WSDL.

4. Coordinator Service

To use a web service transaction, a coordinator service that tunes the transaction activities between participants must be deployed. A coordinator service is required for both server and client applications. Only one coordinator service must be deployed when a web service and a web service client are running on the same server.

The 'wstx-services.ear' file for coordinator service is in the following path.

JEUS_HOME/lib/systemapps

5. Web Service Transaction Example

Web service transaction implementation using a Java class is the same as the implementation of other basic JEUS 9 web services, except that it requires adding the @com.sun.xml.ws.api.tx.at.Transactional annotation.

Java Transaction API (JTA) is used to implement a web service transaction on a web service client.

Web Service Transaction: <AddNumbersClient.jsp>
InitialContext  ctx = new InitialContext();
UserTransaction utx = (UserTransaction) ctx.lookup("java:comp/UserTransaction");

AddNumbersImplService service = new AddNumbersImplService();
AddNumbersImpl port = service.getAddNumbersImplPort();

utx.begin();

int result = port.addNumbers(number1, number2);

utx.commit();