## org.eclipse.emf.transaction
Interface Transaction

All Known Subinterfaces:
  InternalTransaction

All Known Implementing Classes:
  EMFCommandTransaction, EMFOperationTransaction, NonEMFTransaction, TransactionImpl, TriggerCommandTransaction

    public interface Transaction

Specification of a transaction in a `TransactionalEditingDomain`. All reading and writing of data in a `TransactionalEditingDomain` is performed in the context of a transaction.

This interface is not intended to be implemented by clients. It is used internally and by frameworks extending this API. It is mostly of use to `ResourceSetListener`s to find out the state of a transaction in the event call-backs.

See Also:
  `TransactionalEditingDomain`, `TransactionalCommandStack`, `ResourceSetListener`

Field Summary
`static String` `OPTION_IS_UNDO_REDO_TRANSACTION` An informational option that tags the transaction as a transaction that is performing the undo or redo of a command.
`static String` `OPTION_NO_NOTIFICATIONS` Option to suppress the post-commit event upon completion of the transaction.
`static String` `OPTION_NO_TRIGGERS` Option to suppress the pre-commit event that implements triggers.
`static String` `OPTION_NO_UNDO` Option to suppress undo/redo recording.
`static String` `OPTION_NO_VALIDATION` Option to suppress validation.
`static String` `OPTION_UNPROTECTED` Option to enable a read/write transaction in the scope of a (nesting) read-only transaction.
`static String` `OPTION_VALIDATE_EDIT` Option indicating that a transaction is to validate-edit the resource that it has modified when it commits, and to roll back if any resources are not modifiable.
`static String` `OPTION_VALIDATE_EDIT_CONTEXT` The context object to use when validating edit.

Method Summary
`void` `commit()` Attempts to commit the transaction.
`TransactionChangeDescription` `getChangeDescription()` Obtains the change description summarizing the changes made to the model during the execution of the transaction.
`TransactionalEditingDomain` `getEditingDomain()` Queries the editing domain in which I am transacting.
`Map<?,?>` `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.
`IStatus` `getStatus()` Obtains the status of the transaction.
`boolean` `isActive()` Queries whether I am active.
`boolean` `isReadOnly()` Queries whether I am a read-only transaction.
`void` `rollback()` Rolls back the transaction, undoing all of the pending model changes.
`void` `yield()` Temporarily yields access to another read-only transaction.

Field Detail

### OPTION_NO_NOTIFICATIONS

    static final String OPTION_NO_NOTIFICATIONS

  Option to suppress the post-commit event upon completion of the transaction. This does not suppress the pre-commit triggers.

  The value is a `Boolean`; the default is `Boolean.FALSE`.

  See Also:
    Constant Field Values

### OPTION_NO_TRIGGERS

    static final String OPTION_NO_TRIGGERS

  Option to suppress the pre-commit event that implements triggers. This does not suppress the post-commit event.

  The value is a `Boolean`; the default is `Boolean.FALSE`.

  See Also:
    Constant Field Values

### OPTION_NO_VALIDATION

    static final String OPTION_NO_VALIDATION

  Option to suppress validation. Note that it does not suppress triggers, so a transaction could still roll back on commit if a pre-commit listener throws.

  The value is a `Boolean`; the default is `Boolean.FALSE`.

  See Also:
    Constant Field Values

### OPTION_NO_UNDO

    static final String OPTION_NO_UNDO

  Option to suppress undo/redo recording. This has two effects: it prevents rollback of the transaction, as this requires the undo information. It also prevents undo/redo of any `RecordingCommand`s executed in the scope of this transaction.

  The value is a `Boolean`; the default is `Boolean.FALSE`.

  See Also:
    Constant Field Values

### OPTION_UNPROTECTED

    static final String OPTION_UNPROTECTED

  Option to enable a read/write transaction in the scope of a (nesting) read-only transaction. Because this option deliberately violates the read-write exclusion mechanism for model integrity, this option also suppresses undo recording, triggers, and validation. It does not suppress post-commit events.

  The value is a `Boolean`; the default is `Boolean.FALSE`.

  See Also:
    Constant Field Values

### OPTION_IS_UNDO_REDO_TRANSACTION

    static final String OPTION_IS_UNDO_REDO_TRANSACTION

  An informational option that tags the transaction as a transaction that is performing the undo or redo of a command.

  The value is a `Boolean`; the default is `Boolean.FALSE`.

  Note that this option should not be applied by clients of the transaction API. Clients may only check to see whether a transaction has this option, e.g., in a post-commit listener.

  Since:
    1.1
  See Also:
    Constant Field Values

### OPTION_VALIDATE_EDIT

    static final String OPTION_VALIDATE_EDIT

  Option indicating that a transaction is to validate-edit the resource that it has modified when it commits, and to roll back if any resources are not modifiable.

  The value is either a `Boolean` indicating whether to validate or not, or an instance of the `ValidateEditSupport` interface that provides a custom validate-edit implementation.

  Since:
    1.2
  See Also:
    `ValidateEditSupport`, `OPTION_VALIDATE_EDIT_CONTEXT`, Constant Field Values

### OPTION_VALIDATE_EDIT_CONTEXT

    static final String OPTION_VALIDATE_EDIT_CONTEXT

  The context object to use when validating edit. This is usually a `org.eclipse.swt.widgets.Shell` providing a UI context for interaction with the user.

  Since:
    1.2
  See Also:
    `OPTION_VALIDATE_EDIT`, Constant Field Values

Method Detail

### getEditingDomain

    TransactionalEditingDomain getEditingDomain()

  Queries the editing domain in which I am transacting. Note that this is available also before I start and after I close.

  Returns:
    my editing domain

### getParent

    Transaction getParent()

  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

  Returns:
    my parent transaction

### getOwner

    Thread getOwner()

  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.

  Returns:
    my owning thread

### isReadOnly

    boolean isReadOnly()

  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.

  Returns:
    `true` if I am read-only; `false`, otherwise

### getOptions

    Map<?,?> getOptions()

  Obtains the special options with which I was created. The options (map keys) are defined by the `TransactionalEditingDomain` interface.

  Returns:
    an unmodifiable view of my options

### isActive

    boolean isActive()

  Queries whether I am active. I am active after I have started and before I have closed (committed or rolled back).

  Returns:
    whether I am active

### yield

    void yield()

  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.

### commit

    void commit()
                throws RollbackException

  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.

  Throws:
    `RollbackException` - if a listener or validation caused the transaction to roll back instead of committing successfully

### rollback

    void rollback()

  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.

### getChangeDescription

    TransactionChangeDescription getChangeDescription()

  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.

  Returns:
    the change description, or `null` if the transaction rolled back or is still `active`

### getStatus

    IStatus getStatus()

  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.

  Returns:
    my status, most interesting after I have closed

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