Using Bitronix to Manage Transactions

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:

Go to the Global Elements tab.
Click on Create button.
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 Attribute Description Default value

Configuration Attribute	Description	Default value
`mule.bitronix.transactiontimeout`	Timeout for XA transactions, in seconds.	60
`mule.bitronix.recoveryinterval`	Recovery execution interval for XA transactions, in seconds.	60
`mule.bitronix.serverId`	Unique 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.

mule.bitronix.transactiontimeout

Timeout for XA transactions, in seconds.

mule.bitronix.recoveryinterval

Recovery execution interval for XA transactions, in seconds.

mule.bitronix.serverId

Unique 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:config name="dbConfig" doc:name="Database Config"  >
        <db:data-source-connection dataSourceRef="pooledDataSource" />
    </db:config>

</mule-domain>

The table below lists configuration attributes for Pooling Data Source.

Attribute Description Required Default value

Attribute	Description	Required	Default value
`name`	Identifies the pool so that the connector can reference it.	Yes
`datasource-ref`	Reference to the JDBC data source object. An `XADataSource` object must be provided.	Yes
`minPoolSize`	Defines the minimal amount of connections that can be in the pool.	No	4
`maxPoolSize`	Defines the maximum amount of connections that can be in the pool.	No	16
`maxIdleTime`	Defines the number of seconds an idle connection can stay in the pool before it is closed.	No	60
`acquireIncrement`	Determines how many connections at a time will try to acquire when the pool is exhausted.	No	1
`acquireTimeoutSeconds`	The number of seconds a client calling `getConnection()` will wait for a Connection to be checked-in or acquired when the pool is exhausted. Zero means wait indefinitely.	No	30
`preparedStatementCacheSize`	Determines how many statements are cached per pooled connection. 0 means caching is disabled.	No	5

name

Identifies the pool so that the connector can reference it.

Yes

datasource-ref

Reference to the JDBC data source object. An XADataSource object must be provided.

Yes

minPoolSize

Defines the minimal amount of connections that can be in the pool.

maxPoolSize

Defines the maximum amount of connections that can be in the pool.

maxIdleTime

Defines the number of seconds an idle connection can stay in the pool before it is closed.

acquireIncrement

Determines how many connections at a time will try to acquire when the pool is exhausted.

acquireTimeoutSeconds

The number of seconds a client calling getConnection() will wait for a Connection to be checked-in or acquired when the pool is exhausted. Zero means wait indefinitely.

preparedStatementCacheSize

Determines how many statements are cached per pooled connection. 0 means caching is disabled.

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.