ModeShape Distribution 3.0.0.Beta4

Class Transactions

  extended by 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 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 regiser 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 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 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 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 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
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  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.
protected  SessionEnvironment.Monitor newMonitor()
 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


protected final TransactionManager txnMgr


protected final SessionEnvironment.MonitorFactory monitorFactory
Constructor Detail


protected Transactions(SessionEnvironment.MonitorFactory monitorFactory,
                       TransactionManager txnMgr)
Method Detail


public abstract Transactions.Transaction begin()
                                        throws NotSupportedException,
Starts a new transaction if one does not already exist, and associate it with the calling thread.

the ModeShape transaction
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.


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.

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


protected SessionEnvironment.Monitor newMonitor()

ModeShape Distribution 3.0.0.Beta4

Copyright © 2008-2012 JBoss, a division of Red Hat. All Rights Reserved.