<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
  ~  Copyright (c) 2009, WSO2 Inc. (http://www.wso2.org) All Rights Reserved.
  ~
  ~  WSO2 Inc. licenses this file to you under the Apache License,
  ~  Version 2.0 (the "License"); you may not use this file except
  ~  in compliance with the License.
  ~  You may obtain a copy of the License at
  ~
  ~    http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~  Unless required by applicable law or agreed to in writing,
  ~  software distributed under the License is distributed on an
  ~  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  ~  KIND, either express or implied.  See the License for the
  ~  specific language governing permissions and limitations
  ~  under the License.
  -->

<!DOCTYPE html
     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
    <head>
        <meta http-equiv="content-type" content="text/html; charset=iso-8859-1"/>
        <title>
            WSO2 EI - Transactions
        </title>
        <link href="css/EI-docs.css" rel="stylesheet"/>
        <link href="styles/dist-docs.css" rel="stylesheet" type="text/css" media="all"/>
    </head>
    <body xml:lang="en">
        [ <a href="docs_index.html"> Documentation Index </a> ]
        <h1>WSO2 Enterprise Integrator (EI) Transaction support</h1>
        <h2>Contents</h2>
        <div class="toc">
            <ol>
                <li>
                    <a href="#intro">Introduction</a>
                </li>
                <li>
                    <a href="#tx_mediator">Transaction mediator</a>
                </li>
                <li>
                    <a href="#jms_tx">JMS transaction</a>
                    <ul>
                        <li><a href="#jms_local_tx">JMS local transactions</a></li>
                        <li><a href="#jms_distributed_tx">JMS distributed transaction</a></li>
                    </ul>
                </li>
                <li>
                    <a href="#references">References</a>
                </li>
            </ol>
        </div>
        <h3 id="intro" >Introduction</h3>
        <p>
            Transaction plays a major role in today's business world. It adds a very important functionality to your
            system, which you will only see in a system crash. Having a good transactional support will
            ensure correct functionality in a system crash. This guide describes the transaction support avilable
            in WSO2 EI.
        </p>
        <hr/>
        <h3 id="tx_mediator">
            Transaction mediator
        </h3>
        <p> A new synpase mediator (transaction mediator) has been added to support the distributed transactions
            using Java transaction API(JTA). JTA allows applications to perform a distributed transaction that
            is, transactions that access and update data on two or more networked computer resources (an example would
            be to have two databases or a database and a message queue such as JMS). This mediator can be used to
            perform a distributed transaction. The synapse configuration has been extended to add explicit transaction
            markers. What this means is you can use the synpase configuration language to define the start, end etc..,
            of your transaction. It's the responsibility of the user to define when to start, commit or rollback the
            transaction. For example we can mark the start of a transaction at the start of a database commit and end
            of the transaction at the end of the database commit and we can mark rollback transaction if a failure occurs.
        </p>
        <h4 >
            Transaction mediator configuration
        </h4>
        <p>
            Transaction mediator has the following configuration
        </p>
        <pre xml:space="preserve">
	    &lt;transaction action="new|use-existing-or-new|fault-if-no-tx|commit|rollback|suspend|resume"/&gt;
        </pre>
        <p>The action attribute has the following meanings.</p>
        <table>
            <tr>
                <td>new</td>
                <td>Create a new jta transaction. Generate a fault if a transaction already exist.</td>
            </tr>
            <tr>
                <td>use-existing-or-new</td>
                <td>Create a new jta transaction. Do nothing if a transaction exist.</td>
            </tr>
            <tr>
                <td>fault-if-no-tx</td>
                <td>Generate a fault if no transaction exist. Do nothing if a transaction exist.</td>
            </tr>
            <tr>
                <td>commit</td>
                <td>Commit transaction. Generate a fault if no transaction exist.</td>
            </tr>
            <tr>
                <td>rollback</td>
                <td>Rollback transaction. Generate a fault if no transaction exist.</td>
            </tr>
            <tr>
                <td>suspend</td>
                <td>Suspend transaction. Generate a fault if no transaction exist.</td>
            </tr>
            <tr>
                <td>resume</td>
                <td>Resume transaction. Generate a fault if no transaction exist.</td>
            </tr>
        </table>
        <p>To use the transaction mediator you need to have a JTA provider in your environment. What this mean is you
        need to deploy WSO2 EI in an application sever which provide the JTA service. JBoss is an example of such
        application server. Refer the <a href="#references">Reference</a> section to see how you can deploy EI on JBoss.</p>
        <p>An example is avilable in the article(see <a href="#references">Reference</a> section) which demostrate the
            distributed transaction support.
        </p>
        <hr/>
        <h3 id="jms_tx">Java Message Service(JMS) transactions</h3>
        <p> In addition to the distributed transactions, WSO2 EI also has the support for JMS transactions. The JMS
            transport which ships with WSO2 EI has the support for both local and distrbuted transactions.
        </p>

        <h4><a id="jms_local_tx">JMS local transaction</a></h4>
        <p>
            A local transaction represents a unit of work on a single connection to a data source managed by a resource
            manager. In JMS, we can use the JMS API to get a transacted session and call methods for commit or rollback
            for the relevant transaction objects. This is managed internal to a resource manager. There is no external
            transaction manager involved in the coordination of such transactions
        </p>
        <h4>JMS local transaction configuration</h4>
        <p>To start a local JMS transaction you defined following property in JMS transport Listner/Sender in axis2.xml</p>
        <pre xml:space="preserve">
	    &lt;parameter name="transport.jms.SessionTransacted"&gt;true|false&lt;/parameter&gt;
        </pre>
        <p>By default the sesstion is not transacted and if you want to use JMS local transaction set the above parameter
        to true. And you need to set the following property in synpase fault handler to rollback the transaction in
        case of a failure.
        </p>
        <pre xml:space="preserve">
        &lt;property name="SET_ROLLBACK_ONLY" value="true" scope="axis2"/&gt;
        </pre>
        <p>There is an example of JMS local transaction in the transaction article(see <a href="#references">Reference</a>
        section).</p>

        <h4><a id="jms_distributed_tx">JMS distribued transaction</a></h4>
        <p>WSO2 EI also has the support for distributed JMS transaction. You can use JMS transport with more than one
        distributed resources( for example a JMS queue and a remote database server).</p>
        <p>Transaction mediator can be used to mark a distributed transaction which involves a distrbution transaction
        which span through mulitple JMS resources.</p>
        <p>The article contains a sample on JMS distributed transaction(see <a href="#references">Reference</a>
        section).</p>

        <h4><a id="references">References</a></h4>
        <ul>
            <li>
                <a href="http://wso2.org/library/knowledge-base/2010/03/deploying-wso2EI300-jboss510ga">Deploying EI on JBOSS</a>
            </li>
            <li>
                Check WSO2 Oxygen tank for the transaction article.
            </li>
        </ul>
        
    </body>
</html>
