com.sun.sgs.service
Interface Transaction

public interface Transaction

This interface represents a single transaction. It is used by participants to join a transaction and manage state associated with a transaction.

Note that some transaction implementations may only support transactions with at most one durable transaction participant, because of the need to communicate the outcome of prepared transactions to transaction participants following a crash when there are multiple durable participants.

All implementations of Transaction must implement equals and hashCode. Two Transactions are equal if and only if they represent the same transaction.

The implementations of the join, abort, and registerListener methods of this interface are not thread-safe. Callers should insure that calls they make to these methods are made from the thread that created the transaction.

Method Summary

void	abort(Throwable cause) Aborts the transaction, specifying the cause.
void	checkTimeout() Checks if this Transaction has timed out, throwing a TransactionTimeoutException if it has.
Throwable	getAbortCause() Returns the cause supplied in the first call to abort on this transaction, or null if abort has not been called.
long	getCreationTime() Returns the time at which this Transaction was created.
byte[]	getId() Returns the unique identifier for this Transaction.
long	getTimeout() Returns the length of time in milliseconds that this Transaction is allowed to run before it should timeout.
boolean	isAborted() Returns information about whether abort has been called on this transaction.
void	join(TransactionParticipant participant) Tells the Transaction that the given TransactionParticipant is participating in the transaction.
void	registerListener(TransactionListener listener) Registers a listener that will be notified just before this transaction is prepared, and after it commits or aborts.

Method Detail

getId

byte[] getId()

Returns the unique identifier for this Transaction. If two Transactions have the same identifier then they represent the same transaction. This will always return a unique copy of the identifier.

Returns:

the transaction's identifier

getCreationTime

long getCreationTime()

Returns the time at which this Transaction was created. This is a value in milliseconds measured from 1/1/1970. This is typically used for determining whether a Transaction has run too long, or how it should be re-scheduled, but in practice may be used as a participant sees fit.

Returns:

the creation time-stamp

getTimeout

long getTimeout()

Returns the length of time in milliseconds that this Transaction is allowed to run before it should timeout.

Returns:

the timeout length

checkTimeout

void checkTimeout()

Checks if this Transaction has timed out, throwing a TransactionTimeoutException if it has.

Throws:

TransactionNotActiveException - if the transaction is not active

TransactionTimeoutException - if the transaction has timed out

IllegalStateException - if called from a thread that is not the thread that created this transaction

join

void join(TransactionParticipant participant)

Tells the Transaction that the given TransactionParticipant is participating in the transaction. A TransactionParticipant is allowed to join a Transaction more than once, but will only be registered as a single participant.

If the transaction has been aborted, then the exception thrown will have as its cause the value provided in the first call to abort, if any. If the cause implements ExceptionRetryStatus, then the exception thrown will, too, and its shouldRetry method will return the value returned by calling that method on the cause. If no cause was supplied, then the exception will either not implement ExceptionRetryStatus or its shouldRetry method will return false.

Parameters:

participant - the TransactionParticipant joining the transaction

Throws:

TransactionNotActiveException - if the transaction has been aborted

IllegalStateException - if prepare has been called on any transaction participant and the transaction has not been aborted, or if called from a thread that is not the thread that created this transaction

UnsupportedOperationException - if participant does not implement NonDurableTransactionParticipant and the implementation cannot support an additional durable transaction participant

abort

void abort(Throwable cause)

Aborts the transaction, specifying the cause. This notifies all participants that the transaction has aborted, and invalidates all future use of this transaction. The caller should always follow a call to abort by throwing an exception that details why the transaction was aborted. If the exception could be caught by application code, then the exception thrown should be a TransactionAbortedException, created by wrapping the original cause if needed. Throwing an exception is needed not only to communicate the cause of the abort and whether to retry the exception, but also because the application code associated with this transaction will continue to execute normally unless an exception is raised. Supplying the cause to this method allows future calls to the transaction to include the cause to explain why the transaction is no longer active.

If the transaction has been aborted, then the exception thrown will have as its cause the value provided in the first call to abort, if any. If the cause implements ExceptionRetryStatus, then the exception thrown will, too, and its shouldRetry method will return the value returned by calling that method on the cause.

Parameters:

cause - the exception that caused the abort

Throws:

TransactionNotActiveException - if the transaction has been aborted

IllegalStateException - if all transaction participants have been prepared and abort has not been called, or if called from a thread that is not the thread that created this transaction

isAborted

boolean isAborted()

Returns information about whether abort has been called on this transaction.

Returns:

true if abort has been called on this transaction, else false

getAbortCause

Throwable getAbortCause()

Returns the cause supplied in the first call to abort on this transaction, or null if abort has not been called.

Returns:

the exception that caused the abort or null

registerListener

void registerListener(TransactionListener listener)

Registers a listener that will be notified just before this transaction is prepared, and after it commits or aborts.

The listener's beforeCompletion method will be called after the main work of the transaction is complete, just before the transaction is prepared. The transaction will still be considered active at the time of the call, although calls should not be made to independent Services. If the call to beforeCompletion throws an exception, then this transaction will be aborted, and the exception will be treated as if it were thrown by the main body of the transaction. The listener's beforeCompletion method will not be called if this transaction is aborted before it reaches the preparation stage, including if an earlier call to beforeCompletion on another listener throws an exception or aborts this transaction.

The listener's afterCompletion method will be called after this transaction is committed or aborted.

Any number of listeners can be registered for this transaction by making multiple calls to this method. If multiple listeners are registered, the order in which the listeners are called is unspecified.

Parameters:

listener - the listener

Throws:

TransactionNotActiveException - if this transaction is not active

IllegalStateException - if called from a thread that is not the thread that created this transaction