org.modeshape.jcr.txn

Class Transactions

java.lang.Object

org.modeshape.jcr.txn.Transactions

public class Transactions
extends Object

An abstraction for the logic of working with transactions. Sessions use this to create local transactions around a single set of changes (persisted via the Session.save() invocation), but the implementation actually and transparently coordinates the work based upon whether there is already an existing (container-managed or user-managed) transaction associated with the current thread.

The basic workflow is as follows. When transient changes are to be persisted, a new ModeShape transaction is begun. The resulting ModeShape Transactions.Transaction represents the local transaction, to register functions that are to be called upon successful transaction commit, and then either committed or rolled back. If committed, then any changes made should be forwarded to updateCache(WorkspaceCache, ChangeSet, Transaction).

In the typical case where no JTA transactions are being used with JCR, then each time changes are made to a Session and Session.save() is called a new transaction will be created, the changes applied to the workspace, the transaction will be committed, and the workspace cache will be updated based upon the changes.

However, when JTA (local or distributed) transactions are being used with JCR (that is, container-managed transactions or user-managed transactions), then Session.save() still needs to be called (see Chapter 21 of the JSR-283 specification), but the changes are not persisted until the transaction is completed. In other words, even when one or more Session.save() calls are made, the changes are persisted and made visible to the rest of the repository users only when the transaction successfully commits. In these cases, the current thread is already associated with a transaction when Session.save() is called, and therefore ModeShape simply uses that transaction but defers the monitoring and cache update calls until after commit.

Note that when distributed (XA) transactions are used, ModeShape properly integrates and uses the XA transaction but does not register itself as an XAResource. Therefore, even when XA transactions only involve the JCR repository as the single resource, ModeShape enlists only a single resource, allowing the transaction manager to optimize the 2PC with a single resource as a 1PC transaction. (Rather than enlisting the repository as an XAResource, ModeShape registers a Synchronization with the transaction to be notified when the transaction commits successfully, and it uses this to dictate when the events and session's changes are made visible to other sessions.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	Transactions.BaseTransaction
protected class	Transactions.NestableThreadLocalTransaction
protected class	Transactions.RollbackOnlyTransaction
protected class	Transactions.SimpleTransaction
protected class	Transactions.SynchronizedTransaction
protected class	Transactions.TraceableSimpleTransaction
static interface	Transactions.Transaction The representation of a ModeShape fine-grained transaction for use when saving the changes made to a Session.
static interface	Transactions.TransactionFunction A function that should be executed in relation to a transaction.
protected class	Transactions.TransactionTracer

Field Summary

Fields

Modifier and Type	Field and Description
protected Logger	logger
protected TransactionManager	txnMgr

Constructor Summary

Constructors

Constructor and Description
Transactions(TransactionManager txnMgr, TransactionListener listener) Creates a new instance wrapping an existing transaction manager and a transaction listener.

Method Summary

Modifier and Type	Method and Description
Transactions.Transaction	begin() Starts a new transaction if one does not already exist, and associate it with the calling thread.
void	commit() Commits the current transaction, if one exists.
Transactions.Transaction	currentTransaction() Returns a the current ModeShape transaction, if one exists.
String	currentTransactionId() Get a string representation of the current transaction if there already is an existing transaction.
TransactionManager	getTransactionManager() Get the transaction manager.
boolean	isCurrentlyInTransaction() Determine if the current thread is already associated with an existing transaction.
void	resume(Transaction transaction) Resumes a transaction that was previously suspended via the suspend() call.
void	rollback() Rolls back the current transaction, if one exists.
Transaction	suspend() Suspends the existing transaction, if there is one.
void	updateCache(WorkspaceCache workspace, ChangeSet changes, Transactions.Transaction transaction) Notify the workspace of the supplied changes, if and when the current transaction is completed.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

txnMgr

protected final TransactionManager txnMgr

logger

protected final Logger logger

Constructor Detail

Transactions

public Transactions(TransactionManager txnMgr,
                    TransactionListener listener)

Creates a new instance wrapping an existing transaction manager and a transaction listener.

Parameters:

txnMgr - a TransactionManager instance; may not be null

listener - a TransactionListener instance; may not be null

Method Detail

isCurrentlyInTransaction

public boolean isCurrentlyInTransaction()
                                 throws SystemException

Determine if the current thread is already associated with an existing transaction.

Returns:

true if there is an existing transaction, or false if there is none

Throws:

SystemException - If the transaction service fails in an unexpected way.

currentTransactionId

public String currentTransactionId()

Get a string representation of the current transaction if there already is an existing transaction.

Returns:

a string representation of the transaction if there is an existing transaction, or null if there is none

getTransactionManager

public TransactionManager getTransactionManager()

Get the transaction manager.

Returns:

the transaction manager

begin

public Transactions.Transaction begin()
                               throws NotSupportedException,
                                      SystemException,
                                      RollbackException

Starts a new transaction if one does not already exist, and associate it with the calling thread.

Returns:

the ModeShape transaction

Throws:

NotSupportedException - If the calling thread is already associated with a transaction, and nested transactions are not supported.

SystemException - If the transaction service fails in an unexpected way.

RollbackException

currentTransaction

public Transactions.Transaction currentTransaction()

Returns a the current ModeShape transaction, if one exists.

A ModeShape transaction may not necessarily exist when a Transaction is active. This is because ModeShape transactions are only created when a JcrSession is saved.

Returns:

either a instance or null if no ModeShape transaction exists

commit

public void commit()
            throws HeuristicRollbackException,
                   RollbackException,
                   HeuristicMixedException,
                   SystemException

Commits the current transaction, if one exists.

Throws:

IllegalStateException - If the calling thread is not associated with a transaction.

SystemException - If the transaction service fails in an unexpected way.

HeuristicMixedException - If a heuristic decision was made and some some parts of the transaction have been committed while other parts have been rolled back.

HeuristicRollbackException - If a heuristic decision to roll back the transaction was made.

RollbackException

rollback

public void rollback()
              throws SystemException

Rolls back the current transaction, if one exists.

Throws:

IllegalStateException - If the calling thread is not associated with a transaction.

SystemException - If the transaction service fails in an unexpected way.

updateCache

public void updateCache(WorkspaceCache workspace,
                        ChangeSet changes,
                        Transactions.Transaction transaction)

Notify the workspace of the supplied changes, if and when the current transaction is completed. If the current thread is not associated with a transaction when this method is called (e.g., the transaction was started, changes were made, the transaction was committed, and then this method was called), then the workspace is notified immediately. Otherwise, the notifications will be accumulated until the current transaction is committed.

Parameters:

workspace - the workspace to which the changes were made; may not be null

changes - the changes; may be null if there are no changes

transaction - the transaction with which the changes were made; may not be null

suspend

public Transaction suspend()
                    throws SystemException

Suspends the existing transaction, if there is one.

Returns:

either the Transaction which was suspended or null if there isn't such a transaction.

Throws:

SystemException - if the operation fails.

See Also:

TransactionManager.suspend()

resume

public void resume(Transaction transaction)
            throws SystemException

Resumes a transaction that was previously suspended via the suspend() call. If there is no such transaction or there is another active transaction, nothing happens.

Parameters:

transaction - a Transaction instance which was suspended previously or null

Throws:

SystemException - if the operation fails.

See Also:

TransactionManager.resume(javax.transaction.Transaction)