Interface TransactionSession

All Superinterfaces:

AutoCloseable, Closeable, OsidSession, OsidSession

public interface TransactionSession
extends OsidSession

The transaction session is coordinate transactions. A transaction session allows for Transactions to be added to the list of transactions it is managing. Upon a commit() , all registered transactions receive a prepare() and a commit() . Upon an abort() all registered transactions receive an abort() . A TransactionSession itself may implement transactions (as it is an OsidSession ) as a means of enabling a form of federated transaction management.

Method Summary

Modifier and Type	Method	Description
void	abort()	Cancels this transaction, rolling back the queue of operations since the start of this transaction.
void	add(Transaction transaction)	Adds a Transaction to be managed by this transaction service.
void	commit()	Commits the transaction and makes the state change(s) visible.
TransactionState	getState()	Gets the current state of this transaction.

Methods inherited from interface Closeable

close

Methods inherited from interface OsidSession

close

Modifier and Type	Method	Description
void	close()	Close this session.

Methods inherited from interface OsidSession

getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions

Modifier and Type	Method	Description
Agent	getAuthenticatedAgent()	Gets the agent authenticated to this session.
Id	getAuthenticatedAgentId()	Gets the Id of the agent authenticated to this session.
BigDecimal	getClockRate()	Gets the rate of the service clock.
Date	getDate()	Gets the service date which may be the current date or the effective date in which this session exists.
Agent	getEffectiveAgent()	Gets the effective agent in use by this session.
Id	getEffectiveAgentId()	Gets the Id of the effective agent in use by this session.
Type	getFormatType()	Gets the DisplayText format Type preference in effect for this session.
Locale	getLocale()	Gets the locale indicating the localization preferences in effect for this session.
boolean	isAuthenticated()	Tests if an agent is authenticated to this session.
Transaction	startTransaction()	Starts a new transaction for this sesson.
boolean	supportsTransactions()	Tests for the availability of transactions.

Method Details

add

void add(Transaction transaction)
  throws AlreadyExistsException,
OperationFailedException,
PermissionDeniedException

Adds a Transaction to be managed by this transaction service.

Parameters:

transaction - the transaction to add

Throws:

AlreadyExistsException - transaction already added

IllegalStateException - this transaction has ended

InvalidArgumentException - the session doesn't support transactions

NullArgumentException - a null argument provided

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

commit

void commit()
     throws OperationFailedException,
PermissionDeniedException

Commits the transaction and makes the state change(s) visible. This transaction is effectively closed and the only valid method that may be invoked is getState() .

Throws:

IllegalStateException - this transaction has been committed or aborted

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

Notes:

{@code - prepare()} should be invoked on all regstered transactions and iff all are successful should {@code commit()} be invoked on all registered transactions. In case of error on any {@code prepare()} , all transactions should be aborted. If an error occurs on a {@code commit()} after a transaction reported success on a {@code prepare()} after one or more transactions were already committed, then it is not ACID compliant and success should be assumed by committing the rest of the transactions. If a {@code commit()} error occurs when no transactions have been committed, then this operation should not proceed.

abort

void abort()

Cancels this transaction, rolling back the queue of operations since the start of this transaction. This transaction is effectively closed and the only valid method that may be invoked is getState() .

Throws:

IllegalStateException - this transaction has been committed or aborted

Compliance:

mandatory - This method must be implemented.

Notes:

Invokes - {@code abort()} on all registered transactions().

getState

TransactionState getState()

Gets the current state of this transaction.

Returns:

the current state of this transaction

Throws:

IllegalStateException - this transaction has been committed or aborted

Compliance:

mandatory - This method must be implemented.