Author: Sajid Ali Qureshi

Bitronix Transaction Manager allows Mule to automatically recover interrupted transactions on restart.

If a Mule instance crashes or loses connectivity to a resource manager (such as a JMS broker, database, etc.), this can cause a transaction to fail abnormally between the prepare phase and the commit phase of the two-phase commit protocol (2PC). In this case, the transaction manager needs to run a recovery process to complete any in-flight transaction that was taking place during the failure. While this kind of failure is unlikely, a mechanism is needed to retain data consistency when this happens.

Using Bitronix in a Single Application

To configure an application to use Bitronix, declare the transaction manager outside of your flows, as shown below.

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:bti="http://www.mulesoft.org/schema/mule/ee/bti"
      xsi:schemaLocation="
       http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
       http://www.mulesoft.org/schema/mule/ee/bti http://www.mulesoft.org/schema/mule/ee/bti/current/mule-bti-ee.xsd">
    <bti:transaction-manager/>
...
</mule>

Using Bitronix in all Applications in a Mule Domain

To use Bitronix in all applications associated with a Mule domain, define Bitronix as the transaction manager in your domain configuration file, as shown below. Doing so causes all applications associated with the domain to use Bitronix, without needing to declare the transaction manager in individual applications.

<?xml version="1.0" encoding="UTF-8"?>
<domain:mule-domain
        xmlns:bti="http://www.mulesoft.org/schema/mule/ee/bti"
        xmlns="http://www.mulesoft.org/schema/mule/core"
        xmlns:domain="http://www.mulesoft.org/schema/mule/ee/domain"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:doc="http://www.mulesoft.org/schema/mule/documentation" xsi:schemaLocation="
               http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
               http://www.mulesoft.org/schema/mule/ee/domain http://www.mulesoft.org/schema/mule/ee/domain/current/mule-domain-ee.xsd
http://www.mulesoft.org/schema/mule/ee/bti http://www.mulesoft.org/schema/mule/ee/bti/current/mule-bti-ee.xsd">
	<bti:transaction-manager/>

    <!-- ... -->

</domain:mule-domain>

See Shared Resources for information about domains.

Adding Bitronix from Anypoint Studio

You can add Bitronix to your application or domain from Studio, by following these steps:

  1. Go to the Global Elements tab.
  2. Click on the Create button.
  3. Search for Bitronix Transaction Manager.

Configuring the Bitronix Transaction Manager

The default configuration values for Bitronix are suitable for most use cases. However, if you wish to customize the transaction manager, you can do so by using system properties or the wrapper.conf file located in the $MULE_HOME/conf directory.

The table below lists configuration attributes for Bitronix.

Configuration AttributeDescriptionDefault value
mule.bitronix.transactiontimeoutTimeout for XA transactions, in seconds.60
mule.bitronix.recoveryintervalRecovery execution interval for XA transactions, in seconds.60
mule.bitronix.serverIdUnique ID for the transaction manager to register in the XA transaction logs. This value must be unique for each Mule instance.Combination of the host IP and, if running in HA, the cluster node ID.

Configuring a Pooling Data Source for Databases

Bitronix integration provides a data source connection pool for the Database connector, which you must use whenever you want to implement resource pooling in the Database connector.

You can configure a shared Pooling Data Source for all connections. This improves connection utilization when those data sources are not heavily used by applications.

<?xml version="1.0" encoding="UTF-8"?>
<mule-domain xmlns="http://www.mulesoft.org/schema/mule/ee/domain"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:db="http://www.mulesoft.org/schema/mule/db"
      xmlns:bti="http://www.mulesoft.org/schema/mule/ee/bti"
      xmlns:spring="http://www.mulesoft.org/schema/mule/spring"
      xsi:schemaLocation="
               http://www.mulesoft.org/schema/mule/ee/bti http://www.mulesoft.org/schema/mule/ee/bti/current/mule-bti-ee.xsd
               http://www.mulesoft.org/schema/mule/ee/domain http://www.mulesoft.org/schema/mule/ee/domain/current/mule-domain-ee.xsd
               http://www.mulesoft.org/schema/mule/db http://www.mulesoft.org/schema/mule/db/current/mule-db.xsd">

    <spring:config name="springConfig" files="domain-config/datasource-beans.xml"/>

    <bti:transaction-manager/>

    <bti:xa-data-source-pool name="pooledDataSource" dataSource-ref="jdbcDataSource"/>

    <db:generic-config name="dbConfig" dataSource-ref="pooledDataSource"/>

</mule-domain>

The table below lists configuration attributes for Pooling Data Source.

AttributeDescriptionRequiredDefault value
nameIdentifies the pool so that the connector can reference it.Yes
datasource-refReference to the JDBC data source object. An XADataSource object must be provided.Yes
min-pool-sizeDefines the minimal amount of connections that can be in the pool.No4
max-pool-sizeDefines the maximum amount of connections that can be in the pool.No16
max-idle-timeDefines the number of seconds an idle connection can stay in the pool before it is closed.No60
acquire-incrementDetermines how many connections at a time will try to acquire when the pool is exhausted.No1
acquire-timeout-secondsThe number of seconds a client calls getConnection() will wait for a Connection to be checked-in or acquired when the pool is exhausted. Zero means wait indefinitely.No30
prepared-statement-cache-sizeDetermines how many statements are cached per pooled connection. 0 means caching is disabled.No5

Transaction Recovery

Mule includes a transaction recovery procedure that is executed automatically, no configuration is needed. When Mule restarts after a system crash, it connects to all of the resources involved in XA transactions and starts the transaction recovery process, leaving all systems in a consistent state.

See Also

Leave a Comment