com.pentagaia.tb.tx
Interface ITransaction

public interface ITransaction

Representation of pds transactions

Since:

0.1.0

Version:

0.1.0

Author:

mepeisen

Method Summary

void	abort(Throwable cause) Aborts the transaction, optionally supplying the exception that caused the abort.
void	checkTimeout() Checks if this Transaction has timed out, throwing a TransactionTimeoutException if it has.
void	commit() Commits this transaction
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(ITransactionParticipant participant) Tells the Transaction that the given TransactionParticipant is participating in the transaction.
void	rollback() Rollback this transaction

Method Detail

commit

void commit()
            throws IllegalStateException

Commits this transaction

Throws:

IllegalStateException - thrown if this transaction is not active or if there was a problem commiting this transaction

rollback

void rollback()
              throws IllegalStateException

Rollback this transaction

Throws:

IllegalStateException - thrown if this transaction is not active or if there was a problem rolling back this transaction

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

join

void join(ITransactionParticipant 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

abort

void abort(Throwable cause)

Aborts the transaction, optionally supplying the exception that caused the abort. 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. This 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. If no cause was supplied, then the exception will either not implement ExceptionRetryStatus or its shouldRetry method will return false.

Parameters:

cause - the exception that caused the abort, or null if the cause is not known or the abort was not caused by an exception

Throws:

TransactionNotActiveException - if the transaction has been aborted

IllegalStateException - if all transaction participants have been prepared and abort has not been called

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