As we explained in the overview page, Compass::Core provides an abstraction layer on top of the actual transaction handling using the CompassTransaction interface. Compass::Core has a transaction handling framework in place to support different transaction strategies and comes built in with LocalTranasction and JTA synchronization support.

As oppose to transaction handling based on JDBC data source or JCA based resources (and until compass will implement something similar to JCA), you have to use the CompassTransaction abstraction. Note, that it is made much simpler when using CompassTemplate and CompassCallback classes since both the session management and the transaction management is done by the template class.

Compass::Core Compass interface manages the creation of CompassSession using the openSession() method. When beginTransaction() is called on the CompassTransaction, the session is bound to the created transaction (JTA or Local) and used throughout the life-cycle of the transaction. It means that if an additional session is opened within the current transaction, the originating session will be returned by the openSession() method.

Compass::Core provides support for compass local transactions. Local transactions are Compass session level transaction, with no knowledge of other running transactions (like JDBC or JTA).

A local transaction which starts within the boundaries of a compass local transaction will share the same session and transaction context and will be controlled by the outer transaction.

In order to configure Compass to work with the Local Transaction, you must set the compass.transaction.factory to org.compass.core.transaction.LocalTransactionFactory.

Compass::Core provides support for JTA transactions, using the JTA synchronization support. A JTA transaction will be joined if already started (by CMT for example) or will be started if non was initiated.

The support for JTA also includes support for suspend and resume provided by the JTA transaction manager (or REQUIRES_NEW in CMT when there is already a transaction running).

JTA transaction support is best used when wishing to join with other transactional resources (like DataSource).

The current implementation performs the full transaction commit (first and second phase) at the afterCompletion method and any exception is logged but not propagated.

In order to configure Compass to work with the JTA Sync Transaction, you must set the compass.transaction.factory to org.compass.core.transaction.JTASyncTransactionFactory. You must also set the transaction manager lookup based on the environment your application will be running at.

If you wish to unit test your application without a container, you might consider using JOTM as your JTA transaction manager.