Version 5
Created by ibek on Apr 26, 2012 5:23 AM. Last modified by ibek on Sep 17, 2012 3:36 AM.

    This article describes using of distributed transactions in RiftSaw 3.

     

     

    Introduction

     

    This support enables to use the distributed transactions when a BPEL process invokes web service operations requiring to be within a distributed transaction.

    To determine that a web service operation requires distributed transaction, we use policy in WSDL.

     

    We have two specifications that we can use.

    The WS-AtomicTransaction specification supports all the ACID properties of transactions.

    The WS-BusinessActivity specification does not support all the ACID properties but enables to have long running processes with distributed transactions because the transaction participants are completed earlier and then they do not block any transaction resources.

     

    We will shortly look at using JBoss Transactions XTS in web services to enlist transaction participants but I recommend to read JBoss Transactions XTS Guides [1] and examples.

    Because the XTS is not in the default configuration of JBoss AS7 we describe how to configure the configuration and BPEL component in SwitchYard to support XTS.

     

    Features

     

    • creating and completing a distributed transaction is automatic
    • supports WS-AtomicTransaction and WS-BusinessActivity specifications
    • creates and propagates a distributed transaction only if an invoked operation requires WS-AT or WS-BA with policy in WSDL
    • when a distributed transaction is not required in any of BPEL processes, the application server doesn't have to run XTS
    • BPEL process can be part of your distributed transaction (not yet possible - it is required to set the handler chain for BPEL process SWITCHYARD-756)
    • supports subordinate transactions (if BPEL process receives SOAP message with transaction context, BPEL engine creates subordinate transaction)

     

    How to Use WS-AtomicTransaction in BPEL

     

    When we have a web service operation supporting WS-AtomicTransaction, it is required to set a policy in WSDL which is used for BPEL process.

     

    WSDL Configuration to Enable WS-AtomicTransaction

     

    To enable creating and propagating distributed transaction in the RiftSaw we have to put policy into WSDL.

    The configuration is same as the WS-AtomicTransaction specification says http://docs.oasis-open.org/ws-tx/wstx-wsat-1.2-spec-os/wstx-wsat-1.2-spec-os.html#_Toc144628429

    Look at the following example of WSDL, the bold parts were added:

     

    ...

    <wsp:Policy wsu:Id="TransactedPolicy" >

        <wsat:ATAssertion wsp:optional="true" />

    </wsp:Policy>

    <wsdl:binding name="AirportServiceSoapBinding" type="tns:AirportService">

        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>

        <wsdl:operation name="order">

          <soap:operation soapAction="" style="document"/>

          <wsp:PolicyReference URI="#TransactedPolicy" wsdl:required="true" />

          <wsdl:input name="order">

            <soap:body use="literal"/>

          </wsdl:input>

          <wsdl:output name="orderResponse">

            <soap:body use="literal"/>

          </wsdl:output>

        </wsdl:operation>

    ...

     

    How to Use WS-BusinessActivity in BPEL

     

    The difference against to WS-AtomicTransaction is that the transaction participants are completed after continous block of BPEL activities.

    It supports to have long running processes because they will not block the transaction resources.

    If BPEL process ends, the transaction is closed and all participants are also informed that the transaction is closed.

    But if the transaction have to be aborted, all the participants who already completed the transaction are compensated, otherwise they are canceled.

    When we have a web service operation supporting WS-BusinessActivity, it is required to set a policy in WSDL which is used for BPEL process.

     

    WSDL Configuration to Enable WS-BusinessActivity

     

    To enable creating and propagating distributed transaction in the RiftSaw we have to put policy into WSDL.

    The configuration is same as the WS-BusinessActivity specification sayshttp://docs.oasis-open.org/ws-tx/wstx-wsba-1.2-spec-os/wstx-wsba-1.2-spec-os.html#_Toc195337371http://docs.oasis-open.org/ws-tx/wstx-wsba-1.2-spec-os/wstx-wsba-1.2-spec-os.html#_Toc195337371

    Only BAAtomicOutcomeAssertion is supported. XTS doesn't support mixed outcome yet. https://issues.jboss.org/browse/JBTM-410

    Look at the following example of WSDL, the bold parts were added:

     

    ...
    <wsp:Policy wsu:Id="BAAtomicPolicy" >
        <wsba:BAAtomicOutcomeAssertion />
    </wsp:Policy>
    <wsdl:binding name="AirportServiceSoapBinding" type="tns:AirportService">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
        <wsdl:operation name="order">
          <soap:operation soapAction="" style="document"/>
          <wsp:PolicyReference URI="#BAAtomicPolicy" wsdl:required="true" />
          <wsdl:input name="order">
            <soap:body use="literal"/>
          </wsdl:input>
          <wsdl:output name="orderResponse">
            <soap:body use="literal"/>
          </wsdl:output>
        </wsdl:operation>
    ...

     

    SwitchYard Configuration

     

    BPEL service or web service reference to be invoked within distributed transaction should contain contextMapper in switchyard.xml configuration. At least the contextMapper has to include coordinationContext SOAP headers.

     

    <sca:reference name="AirportService" multiplicity="0..1" promote="BusinessTravelService/AirportService">
      <sca:interface.wsdl interface="AirportService.wsdl#wsdl.porttype(AirportService)"/>
      <soap:binding.soap>
        <soap:contextMapper includes=".*" soapHeadersType="DOM"/>
        <soap:wsdl>AirportService.wsdl</soap:wsdl>
        <soap:socketAddr>:18001</soap:socketAddr>
      </soap:binding.soap>
    </sca:reference>

     

    How to Abort a Distributed Transaction in BPEL

     

    Distributed transaction is aborted in these cases:

     

    1. BPEL process will throw an exception (expected or unexpected)
    2. Transaction participant in prepare phase of 2PC protocol will decide to abort
    3. BPEL process is terminated

     

    Recovery Support

     

    RiftSaw 3 does not support recovery of business processes yet.

    But the distributed transactions are recovered automatically.

    I recommend to read the XTS Administration and Development Guide, the Chapter 9 [1]

     

    Distributed Transactions in Web Services

     

    To enable support of distributed transactions propagated via transaction context, we have to set handler chain with the annotation @HandlerChain(file = "/context-handlers.xml")

    The context-handlers.xml file should contain one necessary handler chain, the com.arjuna.mw.wst11.service.JaxWSHeaderContextProcessor

     

    Example of context-handlers.xml file located in resources:

     

    <?xml version="1.0" encoding="UTF-8"?>
<handler-chains xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee">
    <handler-chain>
    <handler>
        <handler-name>ContextHandler</handler-name>
        <handler-class>com.arjuna.mw.wst11.service.JaxWSHeaderContextProcessor</handler-class>
    </handler>
    </handler-chain>
</handler-chains>

     

    WS-AtomicTransaction in Web Services

     

    When the handler chain is set, we are able to use com.arjuna.mw.wst11.UserTransaction and com.arjuna.mw.wst11.TransactionManager.

    Transaction participants have to be child of com.arjuna.wst.Durable2PCParticipant or com.arjuna.wst.Volatile2PCParticipant.

     

    Look at the example how a transaction participant can be enlisted in the distributed transaction:

     

    UserTransaction transactionId = UserTransactionFactory.userTransaction();
if(transactionId != null){
    log.info("Transaction ID = " + transactionId.toString()); // ID can be still unspecified, so it should be checked too
    OrderParticipant op = new OrderParticipant(transactionId.toString(), web service operation parameters);
    try{
        TransactionManagerFactory.transactionManager().enlistForDurableTwoPhase(op, "org.jboss.wstdemo:ExampleService:" + uniqueID);
        .....

    WS-BusinessActivity in Web Services

     

    When the handler chain is set, we are able to use com.arjuna.mw.wst11.UserBusinessActivity and com.arjuna.mw.wst11.BusinessActivityManager.

    Transaction participants have to be child of com.arjuna.wst.BusinessAgreementWithCoordinatorCompletionParticipant or com.arjuna.wst.BusinessAgreementWithParticipantCompletionParticipant.

    The main difference between them is that CoordinationCompletion means the transaction participant will be completed by coordinatior (business process) after continous block of activities and

    ParticipantCompletation means the transaction participant completes itself.

     

    Look at the example how a transaction participant can be enlisted in the distributed transaction:

     

    UserBusinessActivity uba = UserBusinessActivity.getUserBusinessActivity();
if(uba != null){
    log.info("Transaction ID = " + uba.toString()); // ID can be still unspecified, so it should be checked too
    OrderBAParticipant op = new OrderBAParticipant(uba.toString(), web service operation parameters);
    try{
        BusinessActivityManager.getBusinessActivityManager().enlistForBusinessAgreementWithCoordinatorCompletion(op, "org.jboss.wstdemo:ExampleService:" + uniqueID);
        .....

     

    JBoss AS7 XTS Configuration

     

    This chapter describes how to configure JBoss AS7 to use XTS with RiftSaw because in the default configuration the XTS is not included.

     

    Prepared XTS configuration is in jbossas7/docs/examples/configs/standalone-xts.xml

    Copy this configuration into standalone/configuration folder.

    Example configuration does not contain SwitchYard module.

    We copy all SwitchYard parts from standalone.xml configuration, the extension module and SwitchYard subsystem.

     

    In the SwitchYard subsystem, we set bpel.xts.enable property to true in BPEL component like:

     

    <module identifier="org.switchyard.component.bpel" implClass="org.switchyard.component.bpel.deploy.BPELComponent">
      <properties>
        <bpel.xts.enable>true</bpel.xts.enable>
      </properties>
    </module>

     

    To start the JBoss AS7 we run the script ./standalone.sh -c standalone-xts.xml

    It seams to work but if we try to run BPEL process requiring XTS it throws ClassNotFoundException on some XTS class.

    It can be thrown because of missing dependency in BPEL module.

    Shutdown the application server and add this dependency

     

    <module name="org.jboss.xts"/>

     

    into jbossas7/modules/org/switchyard/component/bpel/main/module.xml

    Then the BPEL process requiring XTS should work after restarting the JBoss AS7.

     

    Quickstarts

    xts_wsat

     

    This quickstart demostrates the use of WS-AtomicTransaction in BPEL process which invokes a web service operation requiring WS-AtomicTransaction.

     

    There are 3 scenarios which can be tried:

    1. order request + complete request => commit
    2. abort request + complete request => rollback caused by one of participants
    3. order request + complete request with simulateException set to true => rollback

     

    github sources

    xts_subordinate_wsba

     

    This quickstart shows that it is possible to have a BPEL process (BusinessTravel) requiring WS-BusinessActivity and this BPEL process has to be invoked within distributed transaction. In this example it will be another BPEL process (DefaultBusinessTravel) which creates the distributed transaction automatically.

     

    There are 2 scenarios which can be tried:

     

    1. order request + complete request => partial complete transaction after the first order request and close transaction after the complete request
    2. order request + complete compensate request => partial complete transaction after the first order request and compensate transaction after the complete compensate request

     

    github sources

    Work to be done

     

    1. Setting HandlerChain in SwitchYard configuration https://issues.jboss.org/browse/SWITCHYARD-756

     

    =======================================================================

     

    [1] http://docs.jboss.org/jbosstm/5.0.0.M1/guides/xts-administration_and_development_guide/index.html