Access Keys:
Skip to content (Access Key - 0)
Cancel    
Cancel   
 

Transaction Management

Apr 28, 2004 10:45

Robin Pille

Aug 19, 2013 11:35

Mulesoft Current Mule Documentation

Transaction Management

Mulesoft Documentation Page

Contents

Transaction Management

 Contents

Mule applies the concept of transactions to operations in application for which the result cannot remain indeterminate.  In other words, where a series of steps in flow must succeed or fail as one unit, Mule uses a transaction to demarcate such a unit.  For example, you might use a transaction to encapsulate several steps in a flow for which the end result involves committing information to a database.  In this type of scenario, the commit is either entirely complete and succeeds, or is incomplete and it fails. Even if partially complete, the commit – or transaction – fails. Where a transaction fails, Mule rolls back the operations within the transaction so that no one part results in partial completion.

You can demarcate a transaction by applying a transaction to an endpoint. If a Mule flow begins with a transactional resource (i.e. inbound endpoint), Mule can start a new transaction and manage the entire flow as a transaction. If your flow includes a transactional outbound endpoint, Mule manages the outgoing operation as a transaction. With both a transactional inbound and outbound endpoint, Mule executes the outgoing operation as part of the transaction initiated by the inbound endpoint.

The following endpoints support transactional demarcation:

  • JMS
  • JDBC
  • VM

However, there may be situations in which a Mule flow begins with a non-transactional inbound endpoint – such as HTTP or SFTP – but which requires the use of a transaction within the flow.  For example, a Mule flow may accept information from an external Web service,  then transform the data, before charging a credit card and saving invoice information to a database. In such a situation, you can demarcate a transaction by wrapping the credit card charge and database commit operations within a transaction to ensure either complete success or complete failure and rollback.

Transaction Types

Mule supports three different types of transactions: single resource, multiple resource and extended architecture (XA). The following table describes some of the characteristics of each type.

TypeCharacteristicsNumber of ResourcesAvailable ResourcesPerformance
Single Resource Transactions
  • Receives or sends messages to only one resource.
1
  • JMS
  • VM
  • JDBC 
  • relative to the others, performs better
Multiple Resource Transactions
  • Receives or sends messages to more than one resource.
  • Can handle partial commits and rollbacks. 
  • Uses 1.5 commit protocol as opposed to two-phase commit protocol.
>1
  • JMS
  • VM
  • performs better than XA, though slower than Single Resource
  • with 1.5PC, functions less reliably than XA.
XA Transactions
  • Receives or sends messages to more than one resource.
  • Involves using an two-phase commit algorithm
  • Connectors must be XA-enabled.
>1
 
  • JMS
  • VM
  • JDBC 
  • relative to the others, performs slower but more reliably
Multi-source vs. XA

While XA Transactions offer similar functionality, Multiple Resource transactions use less overhead.  XA transactions, on the other hand, are more reliable and can include JDBC resources. For a discussion of different approaches – including the 1.5 phase commit concept which Multiple Resource transactions use – see the JavaWorld article on distributed transactions.

 

Assumptions

This document assumes that you are familiar with Mule ESB and/or the Mule Studio interface. To increase your familiarity with Mule Studio, consider completing one or more Mule Studio Tutorials. Further, this document assumes you have some knowledge of transaction processing and are familiar with Mule endpoints.  

 

Configuring Transactions

You can demarcate a transaction by either applying a transactional configuration to an endpoint, or by wrapping several elements in a transactional wrapper.

  • Apply a transaction to an inbound endpoint when you want Mule to handle the complete flow as a transaction.
  • Apply a transaction to an outbound endpoint when you want Mule to handle the outgoing operation as part of an existing transaction.
  • Apply a transaction as a wrapper (known as a scope in Studio) when a you want to apply a transaction to elements within a flow which does not begin with a inbound endpoint configured as a transaction.

 The following subsections outline the steps to apply transactions in your flow.

Applying a Transaction to an Endpoint

You can apply a transaction to any of the following inbound or outbound endpoints:

  • JMS
  • VM
  • JDBC 
    1. In the endpoint's properties panel, click the General tab to access the Transaction pane (see image below of the JMS endpoint).



    2. Configure the transactional attributes according to the tables below.

       

      AttributeValueAvailable on EndpointUse
      Type




      JMS TransactionJMSApply a transaction to a flow which involves a single resource (simple).
      JDBC TransactionJDBCApply a transaction to a flow which involves a single resource (simple).
      VM TransactionVMApply a transaction to a flow which involves a single resource (simple).
      XA TransactionJMS VM JDBCApply a transaction to a flow which involves multiple resources.
      Client Ack TransactionJMSApply a transaction to a flow which involves multiple resources.
      Multi-resource TransactionJMSApply a transaction to a flow which involves multiple resources.
      Action




      NONEJMS VM JDBCWhen it receives a message, Mule resolves the transaction, then executes the operation as non-transactional.
      ALWAYS_BEGINJMS VM JDBCWhen it receives a message, Mule always starts a new transaction. If a transaction already exists, Mule resolves the transaction.
      BEGIN_OR_JOINJMS VM JDBCWhen it receives a message, Mule joins a transaction if one is already in progress. Otherwise, Mule simply begins a new transaction.
      ALWAYS_JOINJMS   VM JDBCWhen it receives a message, Mule always expects a transaction to be in progress, and always joins the transaction. If no transaction is in progress, Mule throws an exception.
      JOIN_IF_POSSIBLEJMS   VM JDBCDefault When it receives a message, Mule joins the current transaction if one is available. Otherwise, Mule does not begin a transaction.
      NOT_SUPPORTEDJMS VM JDBCWhen it receives a message, this outbound endpoint executes outside the transactional operation; the transaction continues and does not fail.
      Timeout-JMS   VM JDBCInsert an integer to represent the number of milliseconds (ms) that Mule allows to pass before it ends the transaction.
    3. If applying an XA transaction type to your endpoint, you have the option to check the Interact With External box. When checked, Mule acknowledges transactions which began externally. For example, if you set the transaction Action to BEGIN_OR_JOIN, and check Interact With External, Mule joins any transaction that is already in progress when it receives a message, regardless of whether the transaction began outside of Mule.
    4. If you applied an XA transaction to multiple endpoints in your flow, access the global connectors each references, and configure the connectors to use XA-enabled resources.

    Use Transactions Configuration Reference for quick access to attribute configurations.

    1. Add a transactional child element to the inbound endpoint you wish to make transactional. 

      Child ElementAvailable on EndpointUse
      jms:transactionJMSApply a transaction to a flow which involves a single resource (simple).
      jdbc-ee:transactionJDBCApply a transaction to a flow which involves a single resource (simple).
      vm:transactionVMApply a transaction to a flow which involves a single resource (simple).
      xa-transactionJMS VM JDBCApply a transaction to a flow which involves multiple resources.
      jms:client-ack-transactionJMSApply a transaction to a flow which involves multiple resources.

      ee:multi-transaction

      JMSApply a transaction to a flow which involves multiple resources.
    2. Configure transactional attributes according to the table below.

      AttributeValueAvailable on EndpointUse
      action




      NONEJMS VM JDBCWhen it receives a message, Mule resolves the transaction, then executes the operation as non-transactional.
      ALWAYS_BEGINJMS VM JDBCWhen it receives a message, Mule always starts a new transaction. If a transaction already exists, Mule resolves the transaction.
      BEGIN_OR_JOINJMS VM JDBCWhen it receives a message, Mule joins a transaction if one is already in progress. Otherwise, Mule simply begins a new transaction.
      ALWAYS_JOINJMS   VM JDBCWhen it receives a message, Mule always expects a transaction to be in progress, and always joins the transaction. If no transaction is in progress, Mule throws an exception.
      JOIN_IF_POSSIBLEJMS   VM JDBCWhen it receives a message, Mule joins the current transaction if one is available. Otherwise, Mule does not begin a transaction.
      NOT_SUPPORTEDJMS VM JDBCWhen it receives a message, this outbound endpoint executes outside the transactional operation; the transaction continues and does not fail.
      timeout-JMS   VM JDBCInsert an integer to represent the number of milliseconds (ms) that Mule allows to pass before it ends the transaction.

      interactWithExternal

      true JMS VM JDBCWhen set to true, Mule acknowledges transactions which began externally. For example, if you set the transaction action to BEGIN_OR_JOIN, and set interactWithExternal to true, Mule joins any transaction that is already in progress when it receives a message, regardless of whether the transaction began outside of Mule.
    3. If you applied an XA transaction to multiple endpoints in your flow, access the global connectors each references, and configure the connectors to use XA-enabled resources.

     View Namespace

    Use Transactions Configuration Reference for quick access to attribute configurations.

     

    Applying a Transaction as Wrapper

      Enterprise

      1. From the Scopes palette group, drag a Trasactional scope onto the canvas. Drag building blocks into the Transactional scope to build your transaction.




        Alternatively, select multiple building blocks in a flow (shift+left click), then right-click to select Wrap in... > Transactional.
      2. Configure the details of the transaction according to the table below.

        FieldValueUse
        Display Name-Provide a meaningful name for the transaction scope in your flow.
        Type

        Simple TransactionDefault
        Apply a transaction to a flow which involves a single resource. See Single Resource Transaction for details.
        XA TransactionApply a transaction to a flow which involves multiple resources: JMS, VM or JDBC. See XA Transaction for details.
        Multi TransactionApply a transaction to a flow which involves multiple resources: JMS or VM. See Multiple Resource Transaction for details.
        ActionALWAYS_BEGINDefault
        When it receives a message, Mule always starts a new transaction. If a transaction already exists, Mule resolves the transaction.
        BEGIN_OR_JOINWhen it receives a message, Mule joins a transaction if one is already in progress. Otherwise, Mule simply begins a new transaction.
      3. Drag building blocks inside the Transactional scope to build your transaction.



      Enterprise
      1. To your Mule flow, add one of the following types of transactional elements:

        Single Resource transaction
        <ee:transactional>
        </ee:transactional> 
        Multiple Resource transaction
        <ee:multi-transactional>
        </ee:multi-transactional>
        XA transaction
        <ee:xa-transactional>
        </ee:xa-transactional>
      2. Configure two attributes of the transactional element.

        AttributeValueDescription
        doc:name-Provide a meaningful name for the transaction scope in your flow. Not required in Standalone.
        actionALWAYS_BEGINWhen it receives a message, Mule always starts a new transaction. If a transaction already exists, Mule resolves the transaction.
        BEGIN_OR_JOINWhen it receives a message, Mule joins a transaction if one is already in progress. Otherwise, Mule simply begins a new transaction.
      3. Add child elements inside your new transactional wrapper to build a transaction.

       View the Namespace



       

      Configuration Tips and Tricks

      • Operations that occur inside a transaction execute synchronously. You cannot build an asynchronous flow inside a transaction.
      • Mule creates a transaction for the first outbound endpoint that can be part of a transaction (JMS, JDBC, VM). All the outbound endpoints in the flow which appear after the first outbound endpoint and which use the same type of resource then participate in the transaction. Where such a following endpoint does not use the same type of resource (i.e. where a JDBC endpoint follows a JMS endpoint), the transaction initiated by the first outbound endpoint fails. To avoid execution failure in such a situation, configure the secondary outbound endpoint outside the transaction by setting the action attribute to NOT_SUPPORTED.
      • If you apply an XA transaction to multiple endpoints in your flow, be sure to configure the connectors to use XA-enabled resources.
      • If you apply an XA transaction to a JMS inbound endpoint in your flow, you have the option of specifying the polling frequency of the queue. Access XA Transactions for configuration details.
      • Mule can manage non-transactional outbound endpoints. By default, an outbound endpoint from a non-transactional transport ignores an active transaction rather than rejecting it. In other words, the default transactional action for such endpoints is no longer NONE. The example code below illustrates this behavior. Mule processes messages it receives from the VM queue synchronously and transactionally. The file transport in the code example is not transactional thus, writing to the file is not part of the transaction. However, if a message throws an exception while Mule is creating the file, Mule will roll back the transaction and reprocess the message. This example is, in effect, a multiple resource transaction.
       View the Namespace

       

      Transaction Exception Strategies 

      To handle exceptions Mule throws while processing transactions, you have three options:

      1. Configure no exception strategies for the flow or transaction, thus employing Mule's default exception strategy. 
      2. Configure an exception strategy for the flow in which a transaction exists. The flow's exception strategy handles all exceptions Mule throws while processing the transaction.
      3. Configure an exception strategy for the scope of an individual transaction. The transaction's exception strategy handles all exceptions Mule throws while processing the transaction. If you wish to manage a transactional exception differently from all other exceptions thrown, consider applying an exception strategy to your transaction.

      Refer to the Error Handling documentation to learn more about Mule's default exception strategy and how to apply exception strategies to flows. Follow the steps below to apply an exception strategy to an individual transaction. 

        1. Add a Transactional scope to your flow (refer to steps above), then add building blocks within the scope to build a transaction.
        2. From the Error Handling palette group, drag and drop an exception strategy into the exception strategy section at the bottom of the scope. 



        3. Configure the exception strategy as needed, keeping in mind Mule will use this exception strategy to handle any exceptions thrown while processing the transaction. Reference the Error Handling documentation for exception strategy configuration details.
        1. Within your transactional wrapper, add an exception-strategy child element at the bottom of the wrapper.

        2. Configure the exception strategy as needed, keeping in mind Mule will use this exception strategy to handle any exceptions thrown while processing the transaction. Reference the Error Handling documentation for exception strategy configuration details.

         

        Go Further