## org.eclipse.emf.transaction.impl
Class TransactionImpl

    java.lang.Object
      org.eclipse.emf.transaction.impl.TransactionImpl

All Implemented Interfaces:
  InternalTransaction, Transaction

Direct Known Subclasses:
  EMFCommandTransaction, NonEMFTransaction

    public class TransactionImpl

extends Object
implements InternalTransaction

The default transaction implementation.

Nested Class Summary

Nested classes/interfaces inherited from interface org.eclipse.emf.transaction.Transaction
`Transaction.OptionMetadata`

Field Summary
`static String` `ALLOW_CHANGE_PROPAGATION_BLOCKING` This option, when provided to a transaction that inherits from this implementation class and has children transactions that are using this implementation class, provides an optional block of the normal propagation of change descriptions to the parent transaction by any transaction in the child subtree of this transaction.
`static String` `BLOCK_CHANGE_PROPAGATION` This option blocks the propagation of change descriptions to the parent transaction.
`protected CompositeChangeDescription` `change`
`static Map<Object,Object>` `DEFAULT_UNDO_REDO_OPTIONS` The transaction options that should be used when undoing/redoing changes on the command stack.
`protected List<org.eclipse.emf.common.notify.Notification>` `notifications`
`static String` `OPTION_EXECUTING_COMMAND` An internal option that identifies the `Command` that a transaction was created to execute, in the case that it is an `EMFCommandTransaction`.
`static String` `OPTION_IS_TRIGGER_TRANSACTION` An informative option that tags the transaction as a transaction that is executing trigger commands.

Fields inherited from interface org.eclipse.emf.transaction.Transaction
`OPTION_IS_UNDO_REDO_TRANSACTION, OPTION_NO_NOTIFICATIONS, OPTION_NO_TRIGGERS, OPTION_NO_UNDO, OPTION_NO_VALIDATION, OPTION_UNPROTECTED, OPTION_VALIDATE_EDIT, OPTION_VALIDATE_EDIT_CONTEXT`

Constructor Summary
`TransactionImpl(TransactionalEditingDomain domain, boolean readOnly)` Initializes me with my editing domain and read-only state.
`TransactionImpl(TransactionalEditingDomain domain, boolean readOnly, Map<?,?> options)` Initializes me with my editing domain, read-only state, and additional options.

Method Summary
`void` `abort(IStatus status)` Aborts the transaction with a reason given by the specified status.
`void` `add(org.eclipse.emf.common.notify.Notification notification)` Adds the specified notification to the list of notifications received during this transaction.
`void` `addTriggers(TriggerCommand triggers)` Adds a group of triggers that were executed during my commit.
`protected void` `close()` Closes me.
`protected static boolean` `collectsNotifications(Transaction tx)` Queries whether the specified transaction collects notifications for broadcast to listeners or for validation.
`void` `commit()` Attempts to commit the transaction.
`void` `endPrivileged(PrivilegedRunnable<?> runnable)` Returns me to my previous owner, upon completion of the specified privileged runnable.
`TransactionChangeDescription` `getChangeDescription()` Obtains the change description summarizing the changes made to the model during the execution of the transaction.
`protected static Map<?,?>` `getDefaultOptions(TransactionalEditingDomain domain)` Obtains the default transaction options, if any, of the specified editing domain.
`TransactionalEditingDomain` `getEditingDomain()` Queries the editing domain in which I am transacting.
`protected InternalTransactionalEditingDomain` `getInternalDomain()` Obtains my owning editing domain as the internal interface.
`protected InternalLifecycle` `getLifecycle()` Obtains the life-cycle adapter, if any, of my editing domain, with which I will notify it of my lifecycle events.
`List<org.eclipse.emf.common.notify.Notification>` `getNotifications()` Obtains the list of notifications that were received during execution of this transaction.
`Map<Object,Object>` `getOptions()` Obtains the special options with which I was created.
`Thread` `getOwner()` Queries the thread that owns me.
`Transaction` `getParent()` My parent transaction, if any.
`InternalTransaction` `getRoot()` Obtains the root transaction (the one that has no parent).
`IStatus` `getStatus()` Obtains the status of the transaction.
`org.eclipse.emf.common.command.Command` `getTriggers()` Obtains the triggers that were executed during my commit.
`protected static boolean` `hasOption(Transaction tx, String option)` Queries whether the specified transaction has a boolean option.
`protected boolean` `isAborted()` Queries whether I have been aborted.
`boolean` `isActive()` Queries whether I am active.
`protected static boolean` `isNotificationEnabled(Transaction tx)` Queries whether the specified transaction should send post-commit events, according to its `options`.
`boolean` `isReadOnly()` Queries whether I am a read-only transaction.
`boolean` `isRollingBack()` Queries whether this transaction or any of its ancestors is in the process of rolling back.
`protected static boolean` `isTriggerEnabled(Transaction tx)` Queries whether the specified transaction should invoke pre-commit, listeners, according to its `options` and `read-only state`.
`protected static boolean` `isUndoEnabled(Transaction tx)` Queries whether the specified transaction should record undo information, according to its `options` and `read-only state`.
`protected static boolean` `isUnprotected(Transaction tx)` Queries whether the specified transaction is an unprotected write, according to its `options` and `read-only state`.
`protected static boolean` `isValidationEnabled(Transaction tx)` Queries whether the specified transaction should validate changes, according to its `options` and `read-only state`.
`void` `pause()` Pauses me while a child transaction is active, so that I do not collect either notifications or recorded changes during that time.
`void` `resume(TransactionChangeDescription nestedChanges)` Resumes me after completion of a child transaction.
`void` `rollback()` Rolls back the transaction, undoing all of the pending model changes.
`void` `setParent(InternalTransaction parent)` Assigns my parent transaction (the one in which I am nested).
`void` `setStatus(IStatus status)` Sets the status of the transaction.
`void` `start()` Starts me.
`void` `startPrivileged(PrivilegedRunnable<?> runnable)` Transfers ownership of this transaction to the specified privileged runnable.
`String` `toString()`
`protected IStatus` `validate()` Validates me.
`void` `yield()` Temporarily yields access to another read-only transaction.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### ALLOW_CHANGE_PROPAGATION_BLOCKING

    public static final String ALLOW_CHANGE_PROPAGATION_BLOCKING

  This option, when provided to a transaction that inherits from this implementation class and has children transactions that are using this implementation class, provides an optional block of the normal propagation of change descriptions to the parent transaction by any transaction in the child subtree of this transaction. The child exercises its option to negate the propagation of change descriptions by adding the `BLOCK_CHANGE_PROPAGATION` option to its own options with the value of `Boolean.TRUE`. This option IS inherited by child transactions.

  See Also:
    Constant Field Values

### BLOCK_CHANGE_PROPAGATION

    public static final String BLOCK_CHANGE_PROPAGATION

  This option blocks the propagation of change descriptions to the parent transaction. The option has no effect unless the parent transaction has allowed this negation to happen by having the `ALLOW_CHANGE_PROPAGATION_BLOCKING` option added either directly or through option inheritance. Note that to enable this option it must be added to the options map with the value of `Boolean.TRUE`. This option is NOT inherited by child transactions.

  See Also:
    Constant Field Values

### OPTION_IS_TRIGGER_TRANSACTION

    public static final String OPTION_IS_TRIGGER_TRANSACTION

  An informative option that tags the transaction as a transaction that is executing trigger commands.

  See Also:
    Constant Field Values

### OPTION_EXECUTING_COMMAND

    public static final String OPTION_EXECUTING_COMMAND

  An internal option that identifies the `Command` that a transaction was created to execute, in the case that it is an `EMFCommandTransaction`.

  Since:
    1.3
  See Also:
    Constant Field Values

### DEFAULT_UNDO_REDO_OPTIONS

    public static final Map<Object,Object> DEFAULT_UNDO_REDO_OPTIONS

  The transaction options that should be used when undoing/redoing changes on the command stack. Undo and redo must not perform triggers because these were implemented as chained commands during the original execution. Moreover, validation is not required during undo/redo because we can only return the model from a valid state to another valid state if the original execution did so. Finally, it is not necessary to record undo information when we are undoing or redoing.

  As of the 1.2 release, this map is immutable.

### notifications

    protected List<org.eclipse.emf.common.notify.Notification> notifications

### change

    protected final CompositeChangeDescription change

Constructor Detail

### TransactionImpl

    public TransactionImpl(TransactionalEditingDomain domain,
                           boolean readOnly)

  Initializes me with my editing domain and read-only state.

  Parameters:
    `domain` - the editing domain in which I operate
    `readOnly` - `true` if I am read-only; `false` if I am read/write

### TransactionImpl

    public TransactionImpl(TransactionalEditingDomain domain,
                           boolean readOnly,
                           Map<?,?> options)

  Initializes me with my editing domain, read-only state, and additional options.

  Parameters:
    `domain` - the editing domain in which I operate
    `readOnly` - `true` if I am read-only; `false` if I am read/write
    `options` - my options, or `null` for defaults

Method Detail

### start

    public void start()
               throws InterruptedException

  Description copied from interface: `InternalTransaction`
  Starts me. Usually, this will delegate to the editing domain to `activate` me.

  Note that this call should block the current thread until the editing domain grants exclusive access.

  Specified by:
    `start` in interface `InternalTransaction`
  Throws:
    `InterruptedException` - if the current thread is interrupted while waiting for activation

### getEditingDomain

    public final TransactionalEditingDomain getEditingDomain()

  Description copied from interface: `Transaction`
  Queries the editing domain in which I am transacting. Note that this is available also before I start and after I close.

  Specified by:
    `getEditingDomain` in interface `Transaction`
  Returns:
    my editing domain

### getLifecycle

    protected InternalLifecycle getLifecycle()

  Obtains the life-cycle adapter, if any, of my editing domain, with which I will notify it of my lifecycle events.

  Returns:
    my domain's lifecycle adapter, or `null` if my editing domain does not provide one
  Since:
    1.3

### getParent

    public final Transaction getParent()

  Description copied from interface: `Transaction`
  My parent transaction, if any. The thread that owns an editing domain's active transaction can create nested transactions simply by starting new ones. Nested transactions commit differently from top-level transactions: although they send `pre-commit` events, they do not send post-commit events, nor are they validated. Validation is performed only by the top-level transaction to validate all changes made in its scope, and only the top-level transaction then can send the post-commit event. Nested transactions can roll back their changes without affecting their parent transactions.

  Transactions can nest as follows:

  - read-only transactions can be nested in read-only or read/write transactions
  - read/write transactions can only be nested in read/write transactions

  Specified by:
    `getParent` in interface `Transaction`
  Returns:
    my parent transaction

### setParent

    public final void setParent(InternalTransaction parent)

  Description copied from interface: `InternalTransaction`
  Assigns my parent transaction (the one in which I am nested). This must be done by the editing domain immediately upon activating me.

  Specified by:
    `setParent` in interface `InternalTransaction`
  Parameters:
    `parent` - my parent transaction

### getRoot

    public final InternalTransaction getRoot()

  Description copied from interface: `InternalTransaction`
  Obtains the root transaction (the one that has no parent). This could be me if I am the root.

  Specified by:
    `getRoot` in interface `InternalTransaction`
  Returns:
    the root transaction in a nested transaction structure

### getOwner

    public final Thread getOwner()

  Description copied from interface: `Transaction`
  Queries the thread that owns me. Only this thread is allowed to read or write (in the case of read/write transactions) the editing domain's resource set while I am open.

  Specified by:
    `getOwner` in interface `Transaction`
  Returns:
    my owning thread

### isReadOnly

    public final boolean isReadOnly()

  Description copied from interface: `Transaction`
  Queries whether I am a read-only transaction. Even my owning thread is not permitted to make changes to the model if I am read-only.

  Specified by:
    `isReadOnly` in interface `Transaction`
  Returns:
    `true` if I am read-only; `false`, otherwise

### getOptions

    public final Map<Object,Object> getOptions()

  Description copied from interface: `Transaction`
  Obtains the special options with which I was created. The options (map keys) are defined by the `Transaction` interface.

  Specified by:
    `getOptions` in interface `Transaction`
  Returns:
    an unmodifiable view of my options

### isActive

    public boolean isActive()

  Description copied from interface: `Transaction`
  Queries whether I am active. I am active after I have started and before I have closed (committed or rolled back).

  Specified by:
    `isActive` in interface `Transaction`
  Returns:
    whether I am active

### getStatus

    public IStatus getStatus()

  Description copied from interface: `Transaction`
  Obtains the status of the transaction. This may provide warning or or error messages from validation (after I have committed/rolled back) or other sources, or it might be OK.

  Note that while I am still active, my status is usually OK. It may not be OK if I have been aborted, in which case I will roll back on attempt to commit.

  Specified by:
    `getStatus` in interface `Transaction`
  Returns:
    my status, most interesting after I have closed

### setStatus

    public void setStatus(IStatus status)

  Description copied from interface: `InternalTransaction`
  Sets the status of the transaction.

  Specified by:
    `setStatus` in interface `InternalTransaction`
  Parameters:
    `status` - my status

### abort

    public void abort(IStatus status)

  Description copied from interface: `InternalTransaction`
  Aborts the transaction with a reason given by the specified status. This is used, for example, when a transaction is corrupted by another thread concurrently writing the model (obviously without an active transaction!). The transaction is expected to rollback when it attempts to commit, and to propagate this status up to the root transaction.

  Specified by:
    `abort` in interface `InternalTransaction`
  Parameters:
    `status` - a status object providing the reason. It should be the status attached to the eventual `RollbackException`, and should be set as my `status`

### isAborted

    protected boolean isAborted()

  Queries whether I have been aborted.

  Returns:
    `true` if I have been aborted; `false`, otherwise
  See Also:
    `InternalTransaction.abort(IStatus)`

### commit

    public void commit()
                throws RollbackException

  Description copied from interface: `Transaction`
  Attempts to commit the transaction. The transaction may only commit if it is the currently active transaction in the editing domain. After the transaction has committed, it is no longer active and cannot be started again.

  Commit proceeds in three phases: pre-commit events and triggers, validation, and the post-commit events.

  Pre-commit notifications are sent to the editing domain's registered `ResourceSetListener`s to inform them that the transaction is committing. If any listener throws a `RollbackException`, then the transaction is rolled back and the exception is propagated to the caller. Any trigger commands returned by pre-commit listeners are executed after all listeners are invoked, in a nested transaction. This nested transaction, then, follows the commit protocol to send out pre-commit notifications again. This process continues until no more trigger commands are executed or some listener causes rollback.

  After all pre-commit processing completes, the transaction is validated. Validation checks all of the notifications received from the model during the transaction (including any nested transactions, esp. those that executed triggers). If the validation yields an error status (or more severe), then the transaction is rolled back, throwing a `RollbackException` with the validation status.

  The final phase, if validation passes, is to send out the post-commit event to the resource set listeners. This event includes all of the notifications received during the transaction, including triggers. Note that, because these listeners can read the model, they may cause further notifications (by resolving proxies, loading resources, etc.). Listeners are invoked in a nested read-only transaction, so it will also commit and send out a post-commit event if necessary with additional notifications.

  Note that even a `read-only` transaction can roll back. This should only occur, however, if it is corrupted by a concurrent modification by another thread, which means that invalid data could have been read.

  Specified by:
    `commit` in interface `Transaction`
  Throws:
    `RollbackException` - if a listener or validation caused the transaction to roll back instead of committing successfully

### rollback

    public void rollback()

  Description copied from interface: `Transaction`
  Rolls back the transaction, undoing all of the pending model changes. Once it has rolled back, the transaction is no longer active and cannot be started again. No events are sent when the transaction rolls back; to listeners it appears that nothing ever happened.

  Specified by:
    `rollback` in interface `Transaction`

### yield

    public void yield()

  Description copied from interface: `Transaction`
  Temporarily yields access to another read-only transaction. The `TransactionalEditingDomain` supports any number of pseudo-concurrent read-only transactions. Transactions that are expected to be long-running should yield frequently, as a task running in a progress monitor is expected to check for cancellation frequently. However, there is a higher cost (in time) associated with yielding, so it should not be overdone.

  Only read-only transactions may yield, and only the transaction that is currently active in the editing domain may yield. The yielding transaction may be nested, but not within a read/write transaction at any depth.

  Upon yielding, some other read-only transaction that is attempting to start or to return from a yield will take control of the editing domain. Control is never yielded to a read/write transaction (not even to a read-only transaction nested in a read/write) because this would introduce dirty reads (transactions reading uncommitted changes). If there are no other read-only transactions to receive the transfer of control, then the call returns immediately. Otherwise, control is transferred in FIFO fashion to waiting transactions.

  Specified by:
    `yield` in interface `Transaction`

### getChangeDescription

    public TransactionChangeDescription getChangeDescription()

  Description copied from interface: `Transaction`
  Obtains the change description summarizing the changes made to the model during the execution of the transaction. The change description must not be used until after the transaction has successfully committed. If the transaction rolls back, then it has no change description.

  Specified by:
    `getChangeDescription` in interface `Transaction`
  Returns:
    the change description, or `null` if the transaction rolled back or is still `active`

### getInternalDomain

    protected InternalTransactionalEditingDomain getInternalDomain()

  Obtains my owning editing domain as the internal interface.

  Returns:
    the internal view of my editing domain

### pause

    public void pause()

  Description copied from interface: `InternalTransaction`
  Pauses me while a child transaction is active, so that I do not collect either notifications or recorded changes during that time.

  Specified by:
    `pause` in interface `InternalTransaction`

### resume

    public void resume(TransactionChangeDescription nestedChanges)

  Description copied from interface: `InternalTransaction`
  Resumes me after completion of a child transaction. If the child committed, then I add its change description to my changes.

  Specified by:
    `resume` in interface `InternalTransaction`
  Parameters:
    `nestedChanges` - the nested transaction's recorded changes, or `null` if it rolled back (in which case, I do not add anything to my changes)

### isRollingBack

    public boolean isRollingBack()

  Description copied from interface: `InternalTransaction`
  Queries whether this transaction or any of its ancestors is in the process of rolling back.

  Specified by:
    `isRollingBack` in interface `InternalTransaction`
  Returns:
    `true` if I or my `parent` (if any) am rolling back; `false` otherwise

### close

    protected void close()

  Closes me. This is the last step in committing or rolling back, deactivating me in my editing domain. Also, if I have a parent transaction, I `resume` it.

  If a subclass overrides this method, it must ensure that this implementation is also invoked.

### add

    public void add(org.eclipse.emf.common.notify.Notification notification)

  Description copied from interface: `InternalTransaction`
  Adds the specified notification to the list of notifications received during this transaction.

  Specified by:
    `add` in interface `InternalTransaction`
  Parameters:
    `notification` - the notification to add
  See Also:
    `InternalTransaction.getNotifications()`

### getNotifications

    public List<org.eclipse.emf.common.notify.Notification> getNotifications()

  Description copied from interface: `InternalTransaction`
  Obtains the list of notifications that were received during execution of this transaction. These are the notifications that later will be sent to pre-commit listeners, validation, and eventually to post-commit listeners (if I successfully commit).

  Specified by:
    `getNotifications` in interface `InternalTransaction`
  Returns:
    my notifications
  See Also:
    `InternalTransaction.add(Notification)`

### validate

    protected IStatus validate()

  Validates me. Should only be called during commit.

  Returns:
    the result of validation. If this is an error or worse, then I must roll back

### getTriggers

    public org.eclipse.emf.common.command.Command getTriggers()

  Description copied from interface: `InternalTransaction`
  Obtains the triggers that were executed during my commit.

  Specified by:
    `getTriggers` in interface `InternalTransaction`
  Returns:
    my pre-commit trigger commands, or `null` if I have no triggers (perhaps because the `Transaction.OPTION_NO_TRIGGERS` was applied). This may be a single `Command` or a compound of multiple

### addTriggers

    public void addTriggers(TriggerCommand triggers)

  Description copied from interface: `InternalTransaction`
  Adds a group of triggers that were executed during my commit.

  Specified by:
    `addTriggers` in interface `InternalTransaction`
  Parameters:
    `triggers` - the triggers to add

### startPrivileged

    public void startPrivileged(PrivilegedRunnable<?> runnable)

  Description copied from interface: `InternalTransaction`
  Transfers ownership of this transaction to the specified privileged runnable.

  Specified by:
    `startPrivileged` in interface `InternalTransaction`
  Parameters:
    `runnable` - the runnable whose thread is to borrow me

### endPrivileged

    public void endPrivileged(PrivilegedRunnable<?> runnable)

  Description copied from interface: `InternalTransaction`
  Returns me to my previous owner, upon completion of the specified privileged runnable.

  Specified by:
    `endPrivileged` in interface `InternalTransaction`
  Parameters:
    `runnable` - the runnable whose thread had borrowed me

### toString

    public String toString()

  Overrides:
    `toString` in class `Object`

### isUndoEnabled

    protected static boolean isUndoEnabled(Transaction tx)

  Queries whether the specified transaction should record undo information, according to its `options` and `read-only state`.

  Parameters:
    `tx` - a transaction
  Returns:
    `true` if the transaction should record undo information; `false`, otherwise

### isValidationEnabled

    protected static boolean isValidationEnabled(Transaction tx)

  Queries whether the specified transaction should validate changes, according to its `options` and `read-only state`.

  Parameters:
    `tx` - a transaction
  Returns:
    `true` if the transaction should validate changes; `false`, otherwise

### isTriggerEnabled

    protected static boolean isTriggerEnabled(Transaction tx)

  Queries whether the specified transaction should invoke pre-commit, listeners, according to its `options` and `read-only state`.

  Parameters:
    `tx` - a transaction
  Returns:
    `true` if the transaction should perform the pre-commit procedures; `false`, otherwise

### isNotificationEnabled

    protected static boolean isNotificationEnabled(Transaction tx)

  Queries whether the specified transaction should send post-commit events, according to its `options`.

  Parameters:
    `tx` - a transaction
  Returns:
    `true` if the transaction should send post-commit events; `false`, otherwise

### isUnprotected

    protected static boolean isUnprotected(Transaction tx)

  Queries whether the specified transaction is an unprotected write, according to its `options` and `read-only state`.

  Parameters:
    `tx` - a transaction
  Returns:
    `true` if the transaction is an unprotected write transaction; `false`, otherwise

### collectsNotifications

    protected static boolean collectsNotifications(Transaction tx)

  Queries whether the specified transaction collects notifications for broadcast to listeners or for validation. This is determined by the transaction's options.

  Parameters:
    `tx` - a transaction
  Returns:
    `true` any of notification, triggers, and validation are enabled; `false`, otherwise
  See Also:
    `isNotificationEnabled(Transaction)`, `isTriggerEnabled(Transaction)`, `isValidationEnabled(Transaction)`

### hasOption

    protected static boolean hasOption(Transaction tx,
                                       String option)

  Queries whether the specified transaction has a boolean option.

  Parameters:
    `tx` - a transaction
    `option` - the boolean-valued option to query
  Returns:
    `true` if the transaction has the option; `false` if it does not

### getDefaultOptions

    protected static Map<?,?> getDefaultOptions(TransactionalEditingDomain domain)

  Obtains the default transaction options, if any, of the specified editing domain.

  Parameters:
    `domain` - an editing domain
  Returns:
    its default transaction options, or an empty map if none are defined
  Since:
    1.2

Copyright 2002, 2007 IBM Corporation and others. All Rights Reserved.