com.sun.sgs.impl.service.transaction
Class TransactionImpl

java.lang.Object
  com.sun.sgs.impl.service.transaction.TransactionImpl

All Implemented Interfaces:

Transaction

final class TransactionImpl
extends Object
implements Transaction

Provides an implementation of Transaction.

Note that this implementation does not check that each joining TransactionParticipant has a unique value for getTypeName. Nor is this check done for TransactionListeners. If two participants or listeners have the same type name then their profiling data will be aggregated and reported as a single result.

Constructor Summary

TransactionImpl(long tid, long timeout, boolean usePrepareAndCommitOpt, ProfileCollectorHandle collectorHandle)
Creates an instance with the specified transaction ID, timeout, prepare and commit optimization flag, and collectorHandle.

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.
(package private) void	commit() Commits this transaction
boolean	equals(Object object) Returns true if the argument is an instance of the same class with the same transaction ID.
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.
int	hashCode() Returns a hash code value for this object.
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.
String	toString() Returns a string representation of this instance.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

TransactionImpl

TransactionImpl(long tid,
                long timeout,
                boolean usePrepareAndCommitOpt,
                ProfileCollectorHandle collectorHandle)

Creates an instance with the specified transaction ID, timeout, prepare and commit optimization flag, and collectorHandle.

Method Detail

getId

public 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.

Specified by:

getId in interface Transaction

Returns:

the transaction's identifier

getCreationTime

public 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.

Specified by:

getCreationTime in interface Transaction

Returns:

the creation time-stamp

getTimeout

public long getTimeout()

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

Specified by:

getTimeout in interface Transaction

Returns:

the timeout length

checkTimeout

public void checkTimeout()

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

Specified by:

checkTimeout in interface Transaction

join

public 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.

Specified by:

join in interface Transaction

Parameters:

participant - the TransactionParticipant joining the transaction

abort

public 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.

Specified by:

abort in interface Transaction

Parameters:

cause - the exception that caused the abort

isAborted

public boolean isAborted()

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

Specified by:

isAborted in interface Transaction

Returns:

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

getAbortCause

public Throwable getAbortCause()

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

Specified by:

getAbortCause in interface Transaction

Returns:

the exception that caused the abort or null

registerListener

public 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.

Specified by:

registerListener in interface Transaction

Parameters:

listener - the listener

toString

public String toString()

Returns a string representation of this instance.

Overrides:

toString in class Object

Returns:

a string representation of this instance

equals

public boolean equals(Object object)

Returns true if the argument is an instance of the same class with the same transaction ID.

Overrides:

equals in class Object

Returns:

true if the argument equals this instance, otherwise false

hashCode

public int hashCode()

Returns a hash code value for this object.

Overrides:

hashCode in class Object

Returns:

a hash code value for this object.

commit

void commit()
      throws Exception

Commits this transaction

Throws:

TransactionNotActiveException - if the transaction has been aborted

TransactionAbortedException - if a call to prepare on a transaction participant or to beforeCompletion on a transaction listener aborts the transaction but does not throw an exception

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

Exception - any exception thrown when calling prepare on a participant or beforeCompletion on a listener

See Also:

TransactionHandle.commit