As we explained in the overview page, Compass provides an abstraction layer on top of the actual transaction handling using the CompassTransaction interface. Compass has a transaction handling framework in place to support different transaction strategies and comes built in with LocalTranasction and JTA synchronization support.
The CompassTransaction API is completely optional and can be managed by Compass automatically. This means that once a session is obtained, you can start and work with it (and it will automatically start a transaction if needed, internally using the CompassTransaction), and then calling CompassSession#commit() or CompassSession#rollback(). It is usually much simpler to just use the session API.
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, Spring, Hibernate 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.
When using the openSession method, Compass will automatically try and join an already running outer transaction. An outer transaction can be an already running local Compass transaction, a JTA transaction, a Hibernate transaction, or a Spring managed transaction. If Compass manages to join an existing outer transaction, the application does not need to call CompassSession#beginTransaction() or use CompassTransaction to manage the transaction (since it is already managed). This allows to simplify the usage of Compass within managed environments (CMT or Spring) where a transaction is already in progress by not requiring explicit Compass code to manage a Compass transaction. In fact, calling beginTransaction will not actually begin a transaction in such a case, but will simply join it (with only the rollback method used).
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 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. It can be configured to perform the commit in the beforeCompletion phase, which is useful when storing the index in the database.
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 can also set the transaction manager lookup based on the environment your application will be running at (Compass will try to automatically identify it).
Compass provides support for JTA transactions by enlisting an XAResource with a currently active Transaction. This allows for Compass to participate in a two phase commit process. 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).
The XA support provided allows for proper two phase commit transaction operations, but do not provide a full implementation such as a JCA implementation (mostly for recovery).
In order to configure Compass to work with the JTA XA Transaction, you must set the compass.transaction.factory to org.compass.core.transaction.XATransactionFactory. You can also set the transaction manager lookup based on the environment your application will be running at (Compass will try to automatically identify it).