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

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `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

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected Logger` | `logger`
    `protected SessionEnvironment.MonitorFactory` | `monitorFactory`
    `protected TransactionManager` | `txnMgr`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `Transactions(SessionEnvironment.MonitorFactory monitorFactory, TransactionManager txnMgr)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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()

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