com.atomikos.icatch
Interface CompositeTransaction

All Superinterfaces:

Stateful

public interface CompositeTransaction
extends Stateful

A composite transaction is a nested part of a global composite transaction. Each invocation of a server is represented by an instance of this type. For transaction proxies (instances that represent non-local transactions), all non-trivial methods are allowed to generate an exception of type UnsupportedOperationException. The only methods that always work for all instances are the simple getters and test methods.

Method Summary

RecoveryCoordinator	addParticipant(Participant participant) Add a new participant.
void	addSubTxAwareParticipant(SubTxAwareParticipant subtxaware) Register a participant on behalf of a subtransaction, to be notified as soon as the locally finished state is reached.
void	commit() Commit the composite transaction.
CompositeTransaction	createSubTransaction() Create a subtx for this transaction.
CompositeCoordinator	getCompositeCoordinator() Get the coordinator for this tx.
Extent	getExtent() Get the extent for the transaction.
Stack	getLineage() Get the ancestor info.
int	getLocalSubTxCount() Deprecated. This should not matter outside the core.
Properties	getProperties() Gets all properties of this instance.
String	getProperty(String name) Gets the specified metadata property.
Object	getState() Get the current state.
String	getTid() Getter for tid.
long	getTimeout() Get the timeout in ms.
TransactionControl	getTransactionControl() Deprecated. As from release 3.0, the methods in the TransactionControl interface have been moved to this one.
boolean	isAncestorOf(CompositeTransaction ct) Test if this instance is an ancestor of ct.
boolean	isDescendantOf(CompositeTransaction ct) Test if this instance is a descendant of ct.
boolean	isLocal() Test if the transaction is a locally started transaction or not.
boolean	isRelatedTransaction(CompositeTransaction ct) Test if this instance is related to ct.
boolean	isRoot() Test if this instance is a root or not.
boolean	isSameTransaction(CompositeTransaction ct) Test if this intance represents the same transaction as ct.
boolean	isSerial() Test if serial tx or not.
void	registerSynchronization(Synchronization sync) Add a synchronization callback.
void	rollback() Rollback the current transaction.
void	setProperty(String name, String value) Sets metadata property information on the transaction object.
void	setRollbackOnly() Marks the transaction so that the only possible termination is rollback.
void	setSerial() Set serial mode for root.
void	setTag(HeuristicMessage tag) Sets the tag for this transaction.

Method Detail

getState

Object getState()

Get the current state.

Specified by:

getState in interface Stateful

Returns:

Object One of the state constants.

See Also:

TxState

isRoot

boolean isRoot()

Test if this instance is a root or not. Note: a root is the top-level transaction; that is: the first transaction that was created in the distributed transaction hierarchy.

Returns:

True if this is the root.

getLineage

Stack getLineage()

Get the ancestor info.

Returns:

Stack A stack of ancestors, bottom one is root.

getTid

String getTid()

Getter for tid.

Returns:

String The tid for the tx.

isAncestorOf

boolean isAncestorOf(CompositeTransaction ct)

Test if this instance is an ancestor of ct.

Parameters:

ct - The argument to test for ancestor.

Returns:

boolean True iff this is an ancestor of ct.

isDescendantOf

boolean isDescendantOf(CompositeTransaction ct)

Test if this instance is a descendant of ct.

Parameters:

ct - The argument to test for descendant.

Returns:

boolean True iff this instance is a descendant of ct.

isRelatedTransaction

boolean isRelatedTransaction(CompositeTransaction ct)

Test if this instance is related to ct.

Returns:

True if related. That is: if both share the same root transaction.

isSameTransaction

boolean isSameTransaction(CompositeTransaction ct)

Test if this intance represents the same transaction as ct.

Returns:

True iff the same.

getCompositeCoordinator

CompositeCoordinator getCompositeCoordinator()
                                             throws SysException

Get the coordinator for this tx.

Returns:

CompositeCoordinator The composite coordinator instance.

Throws:

SysException - On failure.

addParticipant

RecoveryCoordinator addParticipant(Participant participant)
                                   throws SysException,
                                          IllegalStateException

Add a new participant.

Parameters:

participant - The participant to add.

Returns:

RecoveryCoordinator Whom to ask for indoubt timeout resolution.

Throws:

SysException - Unexpected.

IllegalStateException - Illegal state.

registerSynchronization

void registerSynchronization(Synchronization sync)
                             throws IllegalStateException,
                                    SysException

Add a synchronization callback.

Parameters:

sync - The callback object.

Throws:

IllegalStateException - If no tx longer active.

SysException - Unexptected failure.

addSubTxAwareParticipant

void addSubTxAwareParticipant(SubTxAwareParticipant subtxaware)
                              throws SysException,
                                     IllegalStateException

Register a participant on behalf of a subtransaction, to be notified as soon as the locally finished state is reached. Resources that support lock inheritance can use this feature to be notified whenever a lock should be inherited.

Parameters:

subtxaware - The participant to be notified on local termination.

Throws:

IllegalStateException - If no longer active.

SysException

isSerial

boolean isSerial()

Test if serial tx or not. Serial mode is an optimized way for lock inheritance: no locks among related transactions are necessary if all related transactions are executed serially with respect to each other. The serial property is set by the root transaction and is propagated to all its subtransactions.

Returns:

boolean True iff all for root is serial.

getTransactionControl

TransactionControl getTransactionControl()

Deprecated. As from release 3.0, the methods in the TransactionControl interface have been moved to this one.

Get a control object for this tx.

Returns:

TransactionControl a control object.

isLocal

boolean isLocal()

Test if the transaction is a locally started transaction or not.

Returns:

boolean True iff started in the local VM. For imported transactions, this is false.

createSubTransaction

CompositeTransaction createSubTransaction()
                                          throws SysException,
                                                 IllegalStateException

Create a subtx for this transaction. For activities, the subtransaction will also be an activity.

Returns:

CompositeTransaction The subtx.

Throws:

IllegalStateException - If no longer active.

SysException

setSerial

void setSerial()
               throws IllegalStateException,
                      SysException

Set serial mode for root. This only works on the root itself, and can not be undone. After this, no parallel calls are allowed in any descendant.

Throws:

IllegalStateException - If called for non-root tx.

SysException - For unexpected errors.

getLocalSubTxCount

int getLocalSubTxCount()

Deprecated. This should not matter outside the core.

Get the number of subtxs that were locally started for this instance.

Returns:

int The number of locally started subtxs.

setTag

void setTag(HeuristicMessage tag)

Sets the tag for this transaction. This is returned as a summary of the local work in case the transaction was imported from a remote client TM.

Parameters:

tag - The tag to add to the transaction.

getExtent

Extent getExtent()

Get the extent for the transaction.

getTimeout

long getTimeout()

Get the timeout in ms.

Returns:

long The timeout, in ms, of the tx.

setRollbackOnly

void setRollbackOnly()

Marks the transaction so that the only possible termination is rollback.

commit

void commit()
            throws HeurRollbackException,
                   HeurMixedException,
                   HeurHazardException,
                   SysException,
                   SecurityException,
                   RollbackException

Commit the composite transaction.

Throws:

HeurRollbackException - On heuristic rollback.

HeurMixedException - On heuristic mixed outcome.

SysException - For unexpected failures.

SecurityException - If calling thread does not have right to commit.

HeurHazardException - In case of heuristic hazard.

RollbackException - If the transaction was rolled back before prepare.

rollback

void rollback()
              throws IllegalStateException,
                     SysException

Rollback the current transaction.

Throws:

IllegalStateException - If prepared or inactive.

SysException - If unexpected error.

setProperty

void setProperty(String name,
                 String value)

Sets metadata property information on the transaction object. Once set, metadata properties can't be overwritten. Properties are inherited by all subtransactions created after the set. Properties may or may not be propagated along with exported transactions (depending on the protocol).

Parameters:

name -

value -

getProperty

String getProperty(String name)

Gets the specified metadata property.

Parameters:

name - The name of the property.

Returns:

The property, or null if not set.

getProperties

Properties getProperties()

Gets all properties of this instance.

Returns:

The (cloned) properties of this transaction.