net.jini.core.transaction
Interface Transaction

All Known Subinterfaces:

ManagedTransaction, NestableTransaction

All Known Implementing Classes:

NestableServerTransaction, ServerTransaction

public interface Transaction

Interface for classes representing transactions returned by TransactionManager servers for use with transaction participants that implement the default transaction semantics. The semantics:

The overall effect of executing a set of sibling pure transactions concurrently is always equivalent to some sequential execution.

Ancestor transactions can execute concurrently with child transactions, subject to the locking rules below.

Every transactional operation is described in terms of acquiring locks on objects; these locks are held until the transaction completes. Whatever the lock rules are, conflict rules are defined such that if two operations do not commute, then they acquire conflicting locks. A transaction can acquire a lock only if the conflicting locks are those held by ancestor transactions (or itself). When a subtransaction commits, its locks are inherited by the parent transaction.

If an object is defined to be created under a transaction, then the existence of the object is only visible within that transaction and its inferiors, but will disappear if the transaction aborts. If an object is defined to be deleted under a transaction, then the object is not visible to any transaction (including the deleting transaction) but will reappear if the transaction aborts. When a nested transaction commits, visibility state is inherited by the parent transaction.

Once a transaction reaches the VOTING stage, if all execution under the transaction (and its subtransactions) has finished, then the only reasons the transaction can abort are: the manager crashes (or has crashed); one or more participants crash (or have crashed); or an explicit abort.

Transaction deadlocks are not guaranteed to be prevented or even detected, but managers and participants are permitted to break known deadlocks by aborting transactions.

An orphan transaction (it or one of its ancestors is guaranteed to abort) is not guaranteed to be detected.

Causal ordering information about transactions is not guaranteed to be propagated.

As long as a transaction persists in attempting to acquire a lock that conflicts with another transaction, the participant will persist in attempting to resolve the outcome of the transaction that holds the conflicting lock.

Since:

1.0

Author:

Sun Microsystems, Inc.

See Also:

NestableTransaction, TransactionManager, NestableTransactionManager, TransactionFactory

Nested Class Summary

static class

Transaction.Created Class that holds return values from create methods.

Method Summary

void	abort() Abort the transaction.
void	abort(long waitFor) Abort the transaction, waiting for participants to be notified of the decision.
void	commit() Commit the transaction.
void	commit(long waitFor) Commit the transaction, waiting for participants to be notified of the decision.

Method Detail

commit

void commit()
            throws UnknownTransactionException,
                   CannotCommitException,
                   RemoteException

Commit the transaction. Commit asks the transaction manager to execute the voting process with the participants. Returns if the transaction successfully reaches either the NOTCHANGED or the COMMITTED state, without waiting for the transaction manager to notify all participants of the decision. If the transaction must be aborted (because one or more participants are unable to prepare), CannotCommitException is thrown without waiting for the transaction manager to notify all participants of the decision.

Throws:

UnknownTransactionException - if the transaction is unknown to the manager. This may be because the transaction ID was incorrect, or because the transaction has proceeded to cleanup due to an earlier commit or abort, and has been forgotten.

CannotCommitException - if the transaction reaches the ABORTED state, or is known to have previously reached that state due to an earlier commit or abort.

RemoteException - if a communication error occurs.

commit

void commit(long waitFor)
            throws UnknownTransactionException,
                   CannotCommitException,
                   TimeoutExpiredException,
                   RemoteException

Commit the transaction, waiting for participants to be notified of the decision. Commit asks the transaction manager to execute the voting process with the participants. Returns if the transaction successfully reaches either the NOTCHANGED or the COMMITTED state, and the transaction manager has notified all participants of the decision, before the specified timeout expires. If the transaction must be aborted (because one or more participants are unable to prepare), CannotCommitException is thrown if the transaction manager is able to notify all participants of the decision before the specified timeout expires. If the transaction manager reaches a decision, but is unable to notify all participants of that decision before the specified timeout expires, then TimeoutExpiredException is thrown. If the specified timeout expires before the transaction manager reaches a decision, TimeoutExpiredException is not thrown until the manager reaches a decision.

Parameters:

waitFor - timeout to wait, from the start of the call until all participants have been notified of the transaction manager's decision

Throws:

UnknownTransactionException - if the transaction is unknown to the manager. This may be because the transaction ID was incorrect, or because the transaction has proceeded to cleanup due to an earlier commit or abort, and has been forgotten.

CannotCommitException - if the transaction reaches the ABORTED state, or is known to have previously reached that state due to an earlier commit or abort.

TimeoutExpiredException - if the timeout expires before all participants have been notified.

RemoteException - if a communication error occurs.

abort

void abort()
           throws UnknownTransactionException,
                  CannotAbortException,
                  RemoteException

Abort the transaction. This can be called at any time by any object holding a reference to the transaction. Abort asks the transaction manager to abort the transaction and to notify each participant of the decision, resulting in them rolling back any state changes made as part of the transaction. Returns as soon as the transaction manager records the abort decision, without waiting for the transaction manager to notify all participants of the decision.

Throws:

UnknownTransactionException - if the transaction is unknown to the manager. This may be because the transaction ID was incorrect, or because the transaction has proceeded to cleanup due to an earlier commit or abort, and has been forgotten.

CannotAbortException - if the transaction is known to have previously reached the COMMITTED state due to an earlier commit.

RemoteException - if a communication error occurs.

abort

void abort(long waitFor)
           throws UnknownTransactionException,
                  CannotAbortException,
                  TimeoutExpiredException,
                  RemoteException

Abort the transaction, waiting for participants to be notified of the decision. This can be called at any time by any object holding a reference to the transaction. Abort asks the transaction manager to abort the transaction and to notify each participant of the decision, resulting in them rolling back any state changes made as part of the transaction. Returns if the transaction manager records the decision and is able to notify all participants of the decision before the specified timeout expires. If the transaction manager is unable to notify all participants of the decision before the specified timeout expires, then TimeoutExpiredException is thrown.

Parameters:

waitFor - timeout to wait, from the start of the call until all participants have been notified of the transaction manager's decision.

Throws:

UnknownTransactionException - if the transaction is unknown to the manager. This may be because the transaction ID was incorrect, or because the transaction has proceeded to cleanup due to an earlier commit or abort, and has been forgotten.

CannotAbortException - if the transaction is known to have previously reached the COMMITTED state due to an earlier commit.

TimeoutExpiredException - if the timeout expires before all participants have been notified.

RemoteException - if a communication error occurs.