Transactions

Fabric3 provides transaction management based on Atomikos TransactionEssentials. Fabric3 supports XA transactions, recovery, and transparent resource enlistment for JDBC DataSources and JMS Sessions. As a performance optimization, Fabric3 also supports transactional DataSource and JMS Session pooling. Since transactions are available on all runtimes, including Ant and Maven, applications may be fully tested without the need to mock, abstract, or otherwise alter transaction infrastructure.   

Declaring Transactional Behavior

Transactional behavior is declared using annotations or in a component configuration contained in a composite.

Transactional Annotations

The following transactional annotations are provided, which correspond to SCA transaction policies:

• org.oasisopen.sca.annotation.ManagedTransaction 

• org.fabric3.api.annotation.transaction.PropagatesTransaction

• org.fabric3.api.annotation.transaction.SuspendsTransaction

 Note only global (XA) transactions are supported. However, this should not impose a performance issue as the Atomikos transaction manager optimizes 2PC when a single resource is enlisted in a transaction. 

Transaction annotations may be applied to an implementation class, method or service reference The following component implementation demonstrates how the various annotations are used:

@ManagedTransaction
public class ManagedTransactionService implements TransactionalService {

   @Reference
   @SuspendsTransaction
   protected TransactionalService suspendedTransactionService;

   @Reference
   @PropagatesTransaction
   protected TransactionalService propagatesTransactionService;

   public void call() throws Exception {

      suspendedTransactionService.call();

      propagatesTransactionService.call();    
   }

}

In the above example, when invoked, the component will either start a new transaction or join an existing one. When it invokes the two services, the current transaction will be suspended and propagated respectivel.

Composite Configuration

Alternatively, transaction semantics can be declared in a composite using the @requires attribute:

<component name="TransactionalService">
   <implementation.java class=".." requires="sca:managedTransaction"/>
   <reference name=" suspendedTransactionService" requires="sca:suspendsTransaction"/>
   <reference name="propagatesTransactionService" requires="sca:propagatesTransaction"/>
</component>

 Transaction annotations are the recommended approach since transactional semantics are generally a fixed implementation requirement as opposed to a configuration option.

Transaction Manager Configuration

Transaction manager properties can be set using the <transaction.manager> element in the systemConfig.xml file. The following attributes on the <transaction.manager> element may be set:

• timeout - The transaction timeout in seconds
• singleThreaded2PC - If the transaction manager should use single threaded 2PC. This value should generally be the default, false.
• enableLogging - Specifies if disk logging should be enabled. This value can be set to false for testing where reliability is not required to improve performance.
• checkPointInterval - Specifies the interval between check points.

Additional transaction manager properties can be set using a <properties> element contained in the <transaction.manager> element in the systemConfig.xml file:

<transaction.manager>
   <properties> 
      <property>
         <key>com.atomikos.icatch.console_log_level</key><value>DEBUG</value>
      </property>
   </properties> 
</transaction.manager>   

To enable transaction debugging as in the previous example, ensure that the monitor level is also set to output debug messages:

<runtime>
   <monitor>
      <runtime.components>
         <level name="TransactionManager" value="debug"/>
      </runtime.components>
   </monitor>
</runtime>

For a detailed description of transaction manager properties, see the Atomikos Documentation

Enabling Transactions

The Fabric3 runtimes must be configured with the required transaction extensions. If a runtime has the JPA or JMS profiles installed, the transaction extensions will be included.