9 Using Web Services Atomic Transactions

Using the @Transactional Annotation in Your JWS File

To enable Web services atomic transactions, specify the @weblogic.wsee.wstx.wsat.Transactional annotation on the Web service endpoint implementation class or method.

Please note the following:

• If you specify the @Transactional annotation at the Web service class level, the settings apply to all two-way methods defined by the service endpoint interface. You can override the flow type value at the method level; however, the version must be consistent across the entire transaction.

• You cannot explicitly specify the @Transactional annotation on a Web method that is also annotated with @Oneway.

• Web services atomic transactions cannot be used with the client-side asynchronous programming model.

The format for specifying the @Transactional annotation is as follows:

@Transactional(
     version=Transactional.Version.[WSAT10|WSAT11|WSAT12|DEFAULT],
     value=Transactional.TransactionFowType.[MANDATORY|SUPPORTS|NEVER]
)

For more information about the version and flow type configuration options, see Table 9-2.

The following sections provide examples of using the @Transactional annotation at the Web service implementation class and method levels, and with the EJB @TransactionAttribute annotation.

• Example: Using @Transactional Annotation on a Web Service Class

• Example: Using @Transactional Annotation on a Web Service Method

• Example: Using the @Transactional and the EJB @TransactionAttribute Annotations Together

package examples.webservices.jaxws.wsat.simple.service;
. . . 
import weblogic.jws.Policy;
import javax.transaction.UserTransaction;
. . .
import javax.jws.WebService;
import weblogic.wsee.wstx.wsat.Transactional;
import weblogic.wsee.wstx.wsat.Transactional.Version;
import weblogic.wsee.wstx.wsat.Transactional.TransactionFlowType;
 
/**
 * This JWS file forms the basis of a WebLogic WS-Atomic Transaction Web Service with the 
 * operations: createAccount, deleteAccount, transferMonet, listAccount
 *
 */
 
@WebService(serviceName = "WsatBankTransferService", targetNamespace = "http://tempuri.org/",
            portName = "WSHttpBindingIService")
@Transactional(value=Transactional.TransactionFlowType.MANDATORY,
               version=weblogic.wsee.wstx.wsat.Transactional.Version.WSAT10)
public class WsatBankTransferService {
 
    public String createAccount(String acctNo, String amount) throws java.lang.Exception{
        Context ctx = null;
        UserTransaction tx = null;
        try {
            ctx = new InitialContext();
            tx = (UserTransaction)ctx.lookup("javax.transaction.UserTransaction");
            try {
                DataSource dataSource = (DataSource)ctx.lookup("examples-demoXA-2");
                String sql = "insert into wsat_acct_remote (acctno, amount) values (" + acctNo +
                           ", " + amount + ")";
                int insCount = dataSource.getConnection().prepareStatement(sql).executeUpdate();
                if (insCount != 1)
            throw new java.lang.Exception("insert fail at remote.");
                return ":acctno=" + acctNo + " amount=" + amount + " creating. ";
            } catch (SQLException e) {
              System.out.println("**** Exception caught *****");
               e.printStackTrace();
               throw new SQLException("SQL Exception during createAccount() at remote.");
        }
        } catch (java.lang.Exception e) {
          System.out.println("**** Exception caught *****");
          e.printStackTrace();
          throw new java.lang.Exception(e);
        }
    }
    public String deleteAccount(String acctNo) throws java.lang.Exception{
      ...
    }
    public String transferMoney(String acctNo, String amount, String direction) throws
       java.lang.Exception{
      ...
    }
    public String listAccount() throws java.lang.Exception{
      ...
    }
}

package examples.webservices.jaxws.wsat.simple.service;
. . . 
import weblogic.jws.Policy;
import javax.transaction.UserTransaction;
. . .
import javax.jws.WebService;
import weblogic.wsee.wstx.wsat.Transactional;
import weblogic.wsee.wstx.wsat.Transactional.Version;
import weblogic.wsee.wstx.wsat.Transactional.TransactionFlowType;
 
/**
 * This JWS file forms the basis of a WebLogic WS-Atomic Transaction Web Service with the 
 * operations: createAccount, deleteAccount, transferMonet, listAccount
 *
 */
 
@WebService(serviceName = "WsatBankTransferService", targetNamespace = "http://tempuri.org/",
            portName = "WSHttpBindingIService")
public class WsatBankTransferService {
 
@Transactional(value=Transactional.TransactionFlowType.MANDATORY,
               version=weblogic.wsee.wstx.wsat.Transactional.Version.WSAT10)
    public String createAccount(String acctNo, String amount) throws java.lang.Exception{
        Context ctx = null;
        UserTransaction tx = null;
        try {
            ctx = new InitialContext();
            tx = (UserTransaction)ctx.lookup("javax.transaction.UserTransaction");
            try {
                DataSource dataSource = (DataSource)ctx.lookup("examples-demoXA-2");
                String sql = "insert into wsat_acct_remote (acctno, amount) values (" + acctNo +
                           ", " + amount + ")";
                int insCount = dataSource.getConnection().prepareStatement(sql).executeUpdate();
                if (insCount != 1)
            throw new java.lang.Exception("insert fail at remote.");
                return ":acctno=" + acctNo + " amount=" + amount + " creating. ";
            } catch (SQLException e) {
              System.out.println("**** Exception caught *****");
               e.printStackTrace();
               throw new SQLException("SQL Exception during createAccount() at remote.");
        }
        } catch (java.lang.Exception e) {
          System.out.println("**** Exception caught *****");
          e.printStackTrace();
          throw new java.lang.Exception(e);
        }
    }
    public String deleteAccount(String acctNo) throws java.lang.Exception{
      ...
    }
    public String transferMoney(String acctNo, String amount, String direction) throws
       java.lang.Exception{
      ...
    }
    public String listAccount() throws java.lang.Exception{
      ...
    }
}

package examples.webservices.jaxws.wsat.simple.service;
. . . 
import weblogic.jws.Policy;
import javax.transaction.UserTransaction;
. . .
import javax.jws.WebService;
import javax.ejb.TransactionAttribute;
import javax.ejb.TransactionAttributeType;
import weblogic.wsee.wstx.wsat.Transactional;
import weblogic.wsee.wstx.wsat.Transactional.Version;
import weblogic.wsee.wstx.wsat.Transactional.TransactionFlowType;
 
/**
 * This JWS file forms the basis of a WebLogic WS-Atomic Transaction Web Service with the 
 * operations: createAccount, deleteAccount, transferMonet, listAccount
 *
 */
 
@WebService(serviceName = "WsatBankTransferService", targetNamespace = "http://tempuri.org/",
            portName = "WSHttpBindingIService")
@Transactional(value=Transactional.TransactionFlowType.MANDATORY,
               version=weblogic.wsee.wstx.wsat.Transactional.Version.WSAT10)
@TransactionAttribute(TransactionAttributeType.REQUIRED
public class WsatBankTransferService {
. . .
}

Enabling Web Services Atomic Transactions Starting From WSDL

When enabled, Web services atomic transactions are advertised in the WSDL file using a policy assertion.

Table 9-4 summarizes the WS-AtomicTransaction 1.2 policy assertions that correspond to a set of common Web services atomic transaction flow type and EJB Transaction attribute combinations. All other combinations result in a build-time error.

You can use wsdlc Ant task to generate, from an existing WSDL file, a set of artifacts that together provide a partial Java implementation of the Web service described by the WSDL file. The WS-AtomicTransaction policy assertions that are advertised in the WSDL are carried forward and are included in the WSDL file for the new Web service generated by wsdlc.

The wsdlc Ant tasks creates a JWS file that contains a partial (stubbed-out) implementation of the generated JWS interface. You need to modify this file to include your business code. After you have coded the JWS file with your business logic, run the jwsc Ant task to generate a complete Java implementation of the Web service. Use the compiledWsdl attribute of jwsc to specify the JAR file generated by the wsdlc Ant task which contains the JWS interface file and data binding artifacts. By specifying this attribute, the jwsc Ant task does not generate a new WSDL file but instead uses the one in the JAR file. Consequently, when you deploy the Web service and view its WSDL, the deployed WSDL will look just like the one from which you initially started (with the WS-AtomicTransaction policy assertions).

For complete details about using wsdlc to generate a Web service from a WSDL file, see "Developing WebLogic Web Services Starting From a WSDL File: Main Steps" in Getting Started With JAX-WS Web Services for Oracle WebLogic Server.

Using @Transactional Annotation with the @WebServiceRef Annotation

To enable Web services atomic transactions, specify the @weblogic.wsee.wstx.wsat.Transactional annotation on the Web service client at the Web service reference (@WebServiceRef) injection point.

The format for specifying the @Transactional annotation is as follows:

@Transactional(
     version=Transactional.Version.[WSAT10|WSAT11|WSAT12|DEFAULT],
     value=Transactional.TransactionFlowType.[MANDATORY|SUPPORTS|NEVER]
)

For more information about the version and flow type configuration options, see Table 9-2.

The following example illustrates how to annotate the Web service reference injection point. Relevant code is shown in bold. As shown in the example, the active JTA transaction becomes a part of the atomic transaction.

package examples.webservices.jaxws.wsat.simple.client;
. . .
import javax.servlet.*;
import javax.servlet.http.*;
. . .
import java.net.URL;
import javax.xml.namespace.QName;

import javax.transaction.UserTransaction;
import javax.transaction.SystemException;
 
import javax.xml.ws.WebServiceRef;
import weblogic.wsee.wstx.wsat.Transactional;
*/
 
/**
 * This example demonstrates using a WS-Atomic Transaction to create or delete an account,
 * or transfer money via Web service as a single atomic transaction.
 */
 
public class WsatBankTransferServlet extends HttpServlet {
. . . 
        String url = "http://localhost:7001";
        URL wsdlURL = new URL(url + "/WsatBankTransferService/WsatBankTransferService");
. . . 
        DataSource ds = null;
        UserTransaction utx = null;
 
        try {
            ctx = new InitialContext();
            utx = (UserTransaction) ctx.lookup("javax.transaction.UserTransaction");
            utx.setTransactionTimeout(900);
        } catch (java.lang.Exception e) {
            e.printStackTrace();
        }
 
        WsatBankTransferService port = getWebService(wsdlURL);
 
        try {
            utx.begin();
            if (remoteAccountNo.length() > 0) {
                if (action.equals("create")) {
                    result = port.createAccount(remoteAccountNo, amount);
                } else if (action.equals("delete")) {
                    result = port.deleteAccount(remoteAccountNo);
                } else if (action.equals("transfer")) {
                    result = port.transferMoney(remoteAccountNo, amount, direction);
                }
            }
            utx.commit();
            result = "The transaction is committed " + result;
       } catch (java.lang.Exception e) {
           try {
                  e.printStackTrace();   
                  utx.rollback();
                  result = "The transaction is rolled back.    " + e.getMessage();
           } catch(java.lang.Exception ex) {
             e.printStackTrace();
             result = "Exception is caught. Check stack trace.";
           }
      }
      request.setAttribute("result", result);
 . . . 
    @Transactional(value = Transactional.TransactionFlowType.MANDATORY, 
                    version = Transactional.Version.WSAT10)
     @WebServiceRef(wsdlLocation =
          "http://localhost:7001/WsatBankTransferService/WsatBankTransferService?WSDL", value =
          examples.webservices.jaxws.wsat.simple.service.WsatBankTransferService.class)
    WsatBankTransferService_Service service;
    private WsatBankTransferService getWebService() {
          return service.getWSHttpBindingIService();
    }
 
    public String createAccount(String acctNo, String amount) throws java.lang.Exception{
        Context ctx = null;         UserTransaction tx = null;
        try {
            ctx = new InitialContext();
            tx = (UserTransaction)ctx.lookup("javax.transaction.UserTransaction");
            try {
                DataSource dataSource = (DataSource)ctx.lookup("examples-dataSource-demoXAPool");
                String sql = "insert into wsat_acct_local (acctno, amount) values (
                    " + acctNo + ", " + amount + ")";
                int insCount = dataSource.getConnection().prepareStatement(sql).executeUpdate();
                if (insCount != 1)
                    throw new java.lang.Exception("insert fail at local.");
                return ":acctno=" + acctNo + " amount=" + amount + " creating.. ";
            } catch (SQLException e) {
                System.out.println("**** Exception caught *****");
                e.printStackTrace();
               throw new SQLException("SQL Exception during createAccount() at local.");
            }
        } catch (java.lang.Exception e) {
        System.out.println("**** Exception caught *****");
            e.printStackTrace();
        throw new java.lang.Exception(e);
        }
    }
 
    public String deleteAccount(String acctNo) throws java.lang.Exception{
    . . .
    }
    public String transferMoney(String acctNo, String amount, String direction) throws 
         java.lang.Exception{
    . . .
    }
    public String listAccount() throws java.lang.Exception{
    . . .
    }
}

Passing the TransactionalFeature to the Client

To enable Web services atomic transactions on the client of the Web service, you can pass an instance of the weblogic.wsee.wstx.wsat.TransactionalFeature as a parameter when creating the Web service proxy or dispatch, as illustrated in the following example. Relevant code is shown in bold.

package examples.webservices.jaxws.wsat.simple.client;
. . .
import javax.servlet.*;
import javax.servlet.http.*;
. . .
import java.net.URL;
import javax.xml.namespace.QName;

import javax.transaction.UserTransaction;
import javax.transaction.SystemException;
 
import weblogic.wsee.wstx.wsat.TransactionalFeature;
import weblogic.wsee.wstx.wsat.Transactional.Version;
import weblogic.wsee.wstx.wsat.Transactional.TransactionFlowType;
*/
 
/**
 * This example demonstrates using a WS-Atomic Transaction to create or delete an account,
 * or transfer money via Web service as a single atomic transaction.
 */
 
public class WsatBankTransferServlet extends HttpServlet {
. . . 
        String url = "http://localhost:7001";
        URL wsdlURL = new URL(url + "/WsatBankTransferService/WsatBankTransferService");
. . . 
        DataSource ds = null;
        UserTransaction utx = null;
 
        try {
            ctx = new InitialContext();
            utx = (UserTransaction) ctx.lookup("javax.transaction.UserTransaction");
            utx.setTransactionTimeout(900);
        } catch (java.lang.Exception e) {
            e.printStackTrace();
        }
 
        WsatBankTransferService port = getWebService(wsdlURL);
 
        try {
            utx.begin();
            if (remoteAccountNo.length() > 0) {
                if (action.equals("create")) {
                    result = port.createAccount(remoteAccountNo, amount);
                } else if (action.equals("delete")) {
                    result = port.deleteAccount(remoteAccountNo);
                } else if (action.equals("transfer")) {
                    result = port.transferMoney(remoteAccountNo, amount, direction);
                }
            }
            utx.commit();
            result = "The transaction is committed " + result;
       } catch (java.lang.Exception e) {
           try {
                  e.printStackTrace();   
                  utx.rollback();
                  result = "The transaction is rolled back.    " + e.getMessage();
           } catch(java.lang.Exception ex) {
             e.printStackTrace();
             result = "Exception is caught. Check stack trace.";
           }
      }
      request.setAttribute("result", result);
 . . . 
    // Passing the TransactionalFeature to the Client
    private WsatBankTransferService getWebService(URL wsdlURL) {
        TransactionalFeature feature = new TransactionalFeature(); 
        feature.setFlowType(TransactionFlowType.MANDATORY);
        feature.setVersion(Version.WSAT10);
        WsatBankTransferService_Service service = new WsatBankTransferService_Service(wsdlURL, 
              new QName("http://tempuri.org/", "WsatBankTransferService"));
        return service.getWSHttpBindingIService(new javax.xml.ws.soap.AddressingFeature(), 
              feature);
    }
 
    public String createAccount(String acctNo, String amount) throws java.lang.Exception{
        Context ctx = null;         UserTransaction tx = null;
        try {
            ctx = new InitialContext();
            tx = (UserTransaction)ctx.lookup("javax.transaction.UserTransaction");
            try {
                DataSource dataSource = (DataSource)ctx.lookup("examples-dataSource-demoXAPool");
                String sql = "insert into wsat_acct_local (acctno, amount) values (
                    " + acctNo + ", " + amount + ")";
                int insCount = dataSource.getConnection().prepareStatement(sql).executeUpdate();
                if (insCount != 1)
                    throw new java.lang.Exception("insert fail at local.");
                return ":acctno=" + acctNo + " amount=" + amount + " creating.. ";
            } catch (SQLException e) {
                System.out.println("**** Exception caught *****");
                e.printStackTrace();
               throw new SQLException("SQL Exception during createAccount() at local.");
            }
        } catch (java.lang.Exception e) {
        System.out.println("**** Exception caught *****");
            e.printStackTrace();
        throw new java.lang.Exception(e);
        }
    }
 
    public String deleteAccount(String acctNo) throws java.lang.Exception{
    . . .
    }
    public String transferMoney(String acctNo, String amount, String direction) throws 
         java.lang.Exception{
    . . .
    }
    public String listAccount() throws java.lang.Exception{
    . . .
    }
}

Securing Messages Exchanged Between the Coordinator and Participant

Using transport-level security, you can secure messages exchanged between the Web services atomic transaction coordinator and participant by configuring the properties defined in the following table using the WebLogic Server Administration Console. These properties are configured at the domain level. For detailed steps, see "Configure Web services atomic transactions" in the Oracle WebLogic Server Administration Console Help.

Enabling and Configuring Web Services Atomic Transactions

To enable Web services atomic transactions and configure the version and flow type, you can customize the configuration at the endpoint or method level for the Web service or client. For detailed steps, see "Configure Web services atomic transactions" in the Oracle WebLogic Server Administration Console Help.