org.modeshape.jcr.txn
Class Transactions

java.lang.Object
  org.modeshape.jcr.txn.Transactions

Direct Known Subclasses:

NoClientTransactions, SynchronizedTransactions

public abstract 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, and should be used to obtain the SessionEnvironment.Monitor that is interested in all changes, 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. (Note that the Infinispan cache is enlisted as a resource in the transaction.) 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

protected class	Transactions.BaseTransaction
protected class	Transactions.SimpleTransaction
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

Field Summary

protected Logger	logger
protected SessionEnvironment.MonitorFactory	monitorFactory
protected TransactionManager	txnMgr

Constructor Summary

protected

Transactions(SessionEnvironment.MonitorFactory monitorFactory, TransactionManager txnMgr)

Method Summary

abstract Transactions.Transaction	begin() Starts a new transaction if one does not already exist, and associate it with the calling thread.
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.
protected SessionEnvironment.Monitor	newMonitor()
void	resume(Transaction transaction) Resumes a transaction that was previously suspended via the suspend() call.
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

monitorFactory

protected final SessionEnvironment.MonitorFactory monitorFactory

logger

protected final Logger logger

Constructor Detail

Transactions

protected Transactions(SessionEnvironment.MonitorFactory monitorFactory,
                       TransactionManager txnMgr)

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 abstract Transactions.Transaction begin()
                                        throws NotSupportedException,
                                               SystemException

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.

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)

newMonitor

protected SessionEnvironment.Monitor newMonitor()