Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| ModeShape Distribution 3.0.0.Beta3
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 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 `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`
`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

### txnMgr

    protected final TransactionManager txnMgr

### monitorFactory

    protected final SessionEnvironment.MonitorFactory monitorFactory

Constructor Detail

### Transactions

    protected Transactions(SessionEnvironment.MonitorFactory monitorFactory,
                           TransactionManager txnMgr)

Method Detail

### 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

### newMonitor

    protected SessionEnvironment.Monitor newMonitor()

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| ModeShape Distribution 3.0.0.Beta3
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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