|
|
|
|
org.eclipse.emf.transaction
Interface Transaction
-
All Known Subinterfaces:
-
InternalTransaction
-
All Known Implementing Classes:
-
EMFCommandTransaction,
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
Nested Class Summary
|
static interface
|
Transaction.OptionMetadata
An interface that allows clients to query certain meta-data about
transaction options. |
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
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
Transaction
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
|
|
|