tyrex.tm.impl
Class TransactionImpl

java.lang.Object
  tyrex.tm.impl.TransactionImpl

All Implemented Interfaces:

javax.transaction.Status, javax.transaction.Transaction, TyrexTransaction

final class TransactionImpl

extends java.lang.Object

implements TyrexTransaction, javax.transaction.Status

Implements a global transaction. This transaction supports X/A resources (see XAResource), can be part of an OTS global transaction (see ResourceImpl) and can contain OTS subtransactions (see Resource). Tightly integrated with TransactionManagerImpl and TransactionServer.

Synchronizations are called in the reverse order in which they are added.

Version:

$Revision: 1.50 $ $Date: 2005/11/30 13:20:14 $

Author:

Assaf Arkin

See Also:

InternalXAResourceHolder, TransactionManagerImpl, TransactionDomain, ResourceImpl

Field Summary

protected int	_hashCode The transaction hash code derived from the transaction identifier.
protected int	_heuristic The heuristic decision made by the transaction after a call to prepare(), internalCommit(boolean), internalRollback().
protected TransactionImpl	_nextEntry The next entry in the hashtable maintained by TransactionDomain.
protected TransactionImpl	_parent If this transaction is a subtransaction of some global transaction, this variable will reference the parent transaction.
protected long	_started Indicates when the transaction started as system clock.
protected int	_status Holds the current status of the transaction.
protected javax.transaction.SystemException	_sysError Held during a commit/rollback process to indicate that an unexpected error occured.
protected long	_timeout Indicates when the transaction will timeout as system clock.
protected TransactionDomainImpl	_txDomain The domain to which this transaction belongs.
protected BaseXid	_xid The transaction identifier.

Fields inherited from interface javax.transaction.Status

STATUS_ACTIVE, STATUS_COMMITTED, STATUS_COMMITTING, STATUS_MARKED_ROLLBACK, STATUS_NO_TRANSACTION, STATUS_PREPARED, STATUS_PREPARING, STATUS_ROLLEDBACK, STATUS_ROLLING_BACK, STATUS_UNKNOWN

Constructor Summary

(package private)	TransactionImpl(BaseXid xid, int heuristic, TransactionDomainImpl txDomain) Hidden constructor used by TransactionDomain to recreate a transaction during recovery.
(package private)	TransactionImpl(BaseXid xid, org.omg.CosTransactions.PropagationContext pgContext, TransactionDomainImpl txDomain, long timeout) Hidden constructor used by TransactionDomain to create a new transaction.
(package private)	TransactionImpl(BaseXid xid, TransactionImpl parent, TransactionDomainImpl txDomain, long timeout) Hidden constructor used by TransactionDomain to create a new transaction.

Method Summary

protected void	addRecovery(javax.transaction.xa.XAResource xaResource, javax.transaction.xa.Xid xid) Called during recovery to add a resource.
void	asyncCommit() Perform an asynchronous commit on the transaction.
void	asyncRollback() Perform an asynchronous rollback on the transaction.
boolean	canUseOnePhaseCommit() Return true if the transaction can be safely committed using one-phase commit.
void	commit()
boolean	delistResource(javax.transaction.xa.XAResource xaResource, int flag)
protected void	endResources() Called to end the resources as part of the one phase commit protocol.
boolean	enlistResource(javax.transaction.xa.XAResource xaResource)
(package private) boolean	enlistResource(javax.transaction.xa.XAResource xaResource, XAResourceCallback callback)
boolean	equals(java.lang.Object other)
protected void	forget(int ignoreHeuristic) Called to forget about the transaction at the end of either a commit or rollback.
org.omg.CosTransactions.Control	getControl() Returns the control interface of the underlying transaction.
protected int	getHeuristic() Returns the heuristic decision of this transaction after it has been prepared, commited or rolledback.
javax.transaction.Transaction	getParent() Returns the parent of this transaction.
protected org.omg.CosTransactions.PropagationContext	getPropagationContext() Returns the propagation context used to import this transaction or null if the transaction was not imported.
long	getStarted() Returns the start time of the tranasction.
int	getStatus()
protected boolean	getTimedOut() Returns true if the transaction has timed out and rolled back.
long	getTimeout() Returns the timeout for the tranasction.
javax.transaction.Transaction	getTopLevel() Returns the top level parent of this transaction, or this transaction if this is a top level transaction.
javax.transaction.xa.Xid	getXid() Returns the Xid of the transaction.
int	hashCode()
protected void	internalCommit(boolean onePhaseCommit) Performs the second part of the two phase commit, after a call to prepare() returned a heuristic decision to commit.
protected void	internalRollback() Called to perform the actual rollback on the transaction.
protected void	internalSetTransactionTimeout(int seconds) Called by TransactionDomain to change the timeout for the transaction's resources to the new value.
protected java.lang.String[]	listResources() Returns a listing of the resources associated with this transaction.
protected int	normalize(int heuristic) Returns a normalized heuristic decision based on the supplied non-normalized heuristic.
void	onePhaseCommit() Perform one-phase commit on the transaction.
protected void	prepare() Called to prepare the resource as part of the two phase commit protocol.
protected void	registerResource(org.omg.CosTransactions.Resource resource) Called to register an OTS resource with the transaction.
void	registerSynchronization(javax.transaction.Synchronization sync)
protected void	resumeAndEnlistResources(XAResourceHolder[] xaResourceHolders) Resume previously suspended resources in the transaction and enlist the new specified resources in the transaction.
void	rollback()
void	setRollbackOnly()
void	setTransactionTimeout(int seconds) Change the timeout for the transaction's resources to the new value.
protected void	suspendResources() Suspend the resources associated with the transaction.
protected void	timedOut() Indicates that the transaction has been rolled back due to time out.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

_xid

protected final BaseXid _xid

The transaction identifier. This must be of type BaseXid.

_hashCode

protected final int _hashCode

The transaction hash code derived from the transaction identifier.

_status

protected int _status

Holds the current status of the transaction.

_sysError

protected javax.transaction.SystemException _sysError

Held during a commit/rollback process to indicate that an unexpected error occured. Will throw that exception if there is no other more important exception to report (e.g. RollbackException).

_heuristic

protected int _heuristic

The heuristic decision made by the transaction after a call to prepare(), internalCommit(boolean), internalRollback(). Held in case the operation is repeated to return a consistent heuristic decision. Defaults to read-only (i.e. no heuristic decision).

_txDomain

protected final TransactionDomainImpl _txDomain

The domain to which this transaction belongs. The domain is notified of the outcome of the transaction and any request to commit/rollback the transaction.

_parent

protected final TransactionImpl _parent

If this transaction is a subtransaction of some global transaction, this variable will reference the parent transaction. Subtransactions cannot commit or rollback directly, only as nested subtransactions.

_timeout

protected long _timeout

Indicates when the transaction will timeout as system clock.

_started

protected final long _started

Indicates when the transaction started as system clock.

_nextEntry

protected TransactionImpl _nextEntry

The next entry in the hashtable maintained by TransactionDomain.

Constructor Detail

TransactionImpl

TransactionImpl(BaseXid xid,
                TransactionImpl parent,
                TransactionDomainImpl txDomain,
                long timeout)

Hidden constructor used by TransactionDomain to create a new transaction. A transaction can only be created through TransactionDomain or TransactionManager which take care of several necessary housekeeping duties.

Parameters:

xid - The Xid for this transaction

parent - The parent of this transaction if this is a nested transaction, null if this is a top level transaction

txDomain - The transaction domain

timeout - The timeout for this transaction, in milliseconds

TransactionImpl

TransactionImpl(BaseXid xid,
                org.omg.CosTransactions.PropagationContext pgContext,
                TransactionDomainImpl txDomain,
                long timeout)
          throws org.omg.CosTransactions.Inactive

Hidden constructor used by TransactionDomain to create a new transaction. A transaction can only be created through TransactionDomain or TransactionManager which take care of several necessary housekeeping duties. This transaction is created to import an OTS transaction using the propagation context.

Parameters:

xid - The Xid for this transaction

pgContext - The propagation context

txDomain - The transaction domain

timeout - The timeout for this transaction, in milliseconds

Throws:

org.omg.CosTransactions.Inactive - The parent transaction has rolled back or is inactive

TransactionImpl

TransactionImpl(BaseXid xid,
                int heuristic,
                TransactionDomainImpl txDomain)

Hidden constructor used by TransactionDomain to recreate a transaction during recovery. The transaction state and heuristic decision are restored from information available in the recovery log.

Parameters:

xid - The Xid for this transaction

heuristic - The recorded heuristic decision

txDomain - The transaction domain

Method Detail

toString

public java.lang.String toString()

hashCode

public int hashCode()

equals

public boolean equals(java.lang.Object other)

getStatus

public int getStatus()

Specified by:

getStatus in interface javax.transaction.Transaction

registerSynchronization

public void registerSynchronization(javax.transaction.Synchronization sync)
                             throws javax.transaction.RollbackException,
                                    java.lang.IllegalStateException,
                                    javax.transaction.SystemException

Specified by:

registerSynchronization in interface javax.transaction.Transaction

Throws:

javax.transaction.RollbackException

java.lang.IllegalStateException

javax.transaction.SystemException

commit

public void commit()
            throws javax.transaction.RollbackException,
                   javax.transaction.HeuristicMixedException,
                   javax.transaction.HeuristicRollbackException,
                   java.lang.SecurityException,
                   javax.transaction.SystemException

Specified by:

commit in interface javax.transaction.Transaction

Throws:

javax.transaction.RollbackException

javax.transaction.HeuristicMixedException

javax.transaction.HeuristicRollbackException

java.lang.SecurityException

javax.transaction.SystemException

rollback

public void rollback()
              throws java.lang.IllegalStateException,
                     javax.transaction.SystemException

Specified by:

rollback in interface javax.transaction.Transaction

Throws:

java.lang.IllegalStateException

javax.transaction.SystemException

enlistResource

public boolean enlistResource(javax.transaction.xa.XAResource xaResource)
                       throws java.lang.IllegalStateException,
                              javax.transaction.SystemException,
                              javax.transaction.RollbackException

Specified by:

enlistResource in interface javax.transaction.Transaction

Throws:

java.lang.IllegalStateException

javax.transaction.SystemException

javax.transaction.RollbackException

enlistResource

boolean enlistResource(javax.transaction.xa.XAResource xaResource,
                       XAResourceCallback callback)
                 throws java.lang.IllegalStateException,
                        javax.transaction.SystemException,
                        javax.transaction.RollbackException

Throws:

java.lang.IllegalStateException

javax.transaction.SystemException

javax.transaction.RollbackException

delistResource

public boolean delistResource(javax.transaction.xa.XAResource xaResource,
                              int flag)
                       throws java.lang.IllegalStateException,
                              javax.transaction.SystemException

Specified by:

delistResource in interface javax.transaction.Transaction

Throws:

java.lang.IllegalStateException

javax.transaction.SystemException

setRollbackOnly

public void setRollbackOnly()
                     throws java.lang.IllegalStateException,
                            javax.transaction.SystemException

Specified by:

setRollbackOnly in interface javax.transaction.Transaction

Throws:

java.lang.IllegalStateException

javax.transaction.SystemException

setTransactionTimeout

public void setTransactionTimeout(int seconds)

Change the timeout for the transaction's resources to the new value.

Specified by:

setTransactionTimeout in interface TyrexTransaction

Parameters:

seconds - The new timeout in seconds

See Also:

TransactionDomain#setTransactionTimeout

asyncCommit

public void asyncCommit()
                 throws javax.transaction.SystemException,
                        java.lang.SecurityException,
                        javax.transaction.RollbackException

Description copied from interface: TyrexTransaction

Perform an asynchronous commit on the transaction.

Specified by:

asyncCommit in interface TyrexTransaction

Throws:

java.lang.SecurityException - The current thread is not allowed to rollback the transaction

javax.transaction.SystemException - A problem occured while associating the transaction with the new thread.

javax.transaction.RollbackException - The transaction has been marked for rollback

asyncRollback

public void asyncRollback()
                   throws java.lang.IllegalStateException,
                          javax.transaction.SystemException,
                          java.lang.SecurityException

Description copied from interface: TyrexTransaction

Perform an asynchronous rollback on the transaction.

Specified by:

asyncRollback in interface TyrexTransaction

Throws:

java.lang.SecurityException - The current thread is not allowed to rollback the transaction.

java.lang.IllegalStateException - The transaction is not in the proper state to be rolled back

javax.transaction.SystemException - A problem occured while associating the transaction with the new thread.

canUseOnePhaseCommit

public boolean canUseOnePhaseCommit()

Description copied from interface: TyrexTransaction

Return true if the transaction can be safely committed using one-phase commit.

Specified by:

canUseOnePhaseCommit in interface TyrexTransaction

Returns:

True if the transaction can be safely committed using one-phase commit

onePhaseCommit

public void onePhaseCommit()
                    throws javax.transaction.RollbackException,
                           javax.transaction.HeuristicMixedException,
                           javax.transaction.HeuristicRollbackException,
                           java.lang.SecurityException,
                           java.lang.IllegalStateException,
                           javax.transaction.SystemException

Description copied from interface: TyrexTransaction

Perform one-phase commit on the transaction.

Specified by:

onePhaseCommit in interface TyrexTransaction

Throws:

java.lang.IllegalStateException - The current thread is not associated with a transaction.

javax.transaction.HeuristicRollbackException - A heuristic decision was made and that some relevant updates have been rolled back.

javax.transaction.HeuristicMixedException - A heuristic decision was made and that some relevant updates have been committed while others have been rolled back.

javax.transaction.SystemException - The transaction manager encountered an unexpected error condition

java.lang.SecurityException - The thread is not allowed to commit the transaction.

javax.transaction.RollbackException - Indicates that the transaction has been rolled back rather than committed.

getParent

public javax.transaction.Transaction getParent()

Description copied from interface: TyrexTransaction

Returns the parent of this transaction.

Specified by:

getParent in interface TyrexTransaction

Returns:

The parent of this transaction, null if the transaction is top-level

getTopLevel

public javax.transaction.Transaction getTopLevel()

Description copied from interface: TyrexTransaction

Returns the top level parent of this transaction, or this transaction if this is a top level transaction.

Specified by:

getTopLevel in interface TyrexTransaction

Returns:

The top level transaction

getTimeout

public long getTimeout()

Description copied from interface: TyrexTransaction

Returns the timeout for the tranasction. This is the system clock at which the transaction will time out.

Specified by:

getTimeout in interface TyrexTransaction

Returns:

The timeout for the tranasction

getStarted

public long getStarted()

Description copied from interface: TyrexTransaction

Returns the start time of the tranasction.

Specified by:

getStarted in interface TyrexTransaction

Returns:

The start time of the tranasction

getXid

public javax.transaction.xa.Xid getXid()

Description copied from interface: TyrexTransaction

Returns the Xid of the transaction.

Specified by:

getXid in interface TyrexTransaction

Returns:

The Xid of the transaction

getControl

public org.omg.CosTransactions.Control getControl()

Description copied from interface: TyrexTransaction

Returns the control interface of the underlying transaction.

Specified by:

getControl in interface TyrexTransaction

Returns:

The control interface

prepare

protected void prepare()
                throws java.lang.IllegalStateException,
                       javax.transaction.RollbackException

Called to prepare the resource as part of the two phase commit protocol. On entry the status must be either #STATUS_ACTIVE) or {@link #STATUS_MARKED_ROLLBACK).

All enlisted resources are notified that the transaction has ended, and are they asked to prepare it. If a resource succeeds we will commit it (unless we decide to rollback the entire transaction). If a resource is read-only (or shared) we will mark it as read-only. If at least one resource fails to prepare, or any other error is encountered, we stop preparation and return a heuristic decision.

The heuristic decision can be any of the following:

• {@link #Heuristic.READONLY} There were no resources for this transaction, or all resources are read only -- there is no need to commit/rollback this transaction
• {@link #Heuristic.COMMIT} All resources are prepared and those with a false {@link InternalXAResourceHolder#readOnly} need to be commited.
• {@link #Heuristic.ROLLBACK} The transaction has been marked for rollback, an error has occured or at least one resource failed to prepare and there were no resources that commited
• {@link #Heuristic.MIXED} Some resources have already commited, others have either rolledback or failed to commit, or we got an error in the process: all resources must be rolledback

Throws:

java.lang.IllegalStateException - The transaction is not active or is in the process of being commited

javax.transaction.RollbackException

internalCommit

protected void internalCommit(boolean onePhaseCommit)
                       throws java.lang.IllegalStateException

Performs the second part of the two phase commit, after a call to prepare() returned a heuristic decision to commit. Will attempt to commit on all the resources that are not read-only. The end result is described in a heuristic decision. Multiple calls are supported.

The heuristic decision can be any of the following:

• #Heuristic.COMMIT All resources were commited successfuly
• #Heuristic.ROLLBACK No resources were commited successfuly, all resources were rolledback successfuly
• #Heuristic.MIXED Some resources have commited, others have rolled back

Parameters:

onePhaseCommit - True if one phase commit is to be used

Throws:

java.lang.IllegalStateException - Transaction has not been prepared

internalRollback

protected void internalRollback()

Called to perform the actual rollback on the transaction. Will force a rollback on all the enlisted resources and delisted resources and return the heuristic decision of the rollback. Multiple calls are supported.

The heuristic decision can be any of the following:

• #Heuristic.READONLY There were no resources for this transaction, or all resources are read only -- there is no need to commit/rollback this transaction
• #Heuristic.COMMIT All resources have decided to commit
• #Heuristic.ROLLBACK All resources have rolled back (except for read-only resources)
• #Heuristic.MIXED Some resources have already commited, others have rolled back

Throws:

java.lang.IllegalStateException - The transaction is not active

suspendResources

protected void suspendResources()
                         throws java.lang.IllegalStateException,
                                javax.transaction.SystemException

Suspend the resources associated with the transaction.

The resources that are already suspended are not affected.

Throws:

java.lang.IllegalStateException

javax.transaction.SystemException

resumeAndEnlistResources

protected void resumeAndEnlistResources(XAResourceHolder[] xaResourceHolders)
                                 throws java.lang.IllegalStateException,
                                        javax.transaction.SystemException,
                                        javax.transaction.RollbackException

Resume previously suspended resources in the transaction and enlist the new specified resources in the transaction. The resources may already be enlisted.

Active resources (ie non-suspended) are not affected.

Throws:

java.lang.IllegalStateException

javax.transaction.SystemException

javax.transaction.RollbackException

registerResource

protected void registerResource(org.omg.CosTransactions.Resource resource)
                         throws java.lang.IllegalStateException

Called to register an OTS resource with the transaction. Used internally to perform nested transactions and exposed through the OTS interface.

Throws:

java.lang.IllegalStateException

normalize

protected int normalize(int heuristic)

Returns a normalized heuristic decision based on the supplied non-normalized heuristic. A normalized heuristic has at most one flag set it in. For example, if both commit and rollback flags are set, the outcome is a mixed heuristic. If both commit and mixed are set, the outcome is again a mixed heuristic.

Parameters:

heuristic - A non-normalized heuristic decision

Returns:

A normalized heuristic decision

getHeuristic

protected int getHeuristic()

Returns the heuristic decision of this transaction after it has been prepared, commited or rolledback. At all other times this method will return #Heuristic.READONLY.

Returns:

The heuristic decision of this transaction

internalSetTransactionTimeout

protected void internalSetTransactionTimeout(int seconds)

Called by TransactionDomain to change the timeout for the transaction's resources to the new value. This might or might not have an effect on the underlying resources. All consistency checks are made by the server.

See Also:

TransactionDomain#setTransactionTimeout

timedOut

protected void timedOut()

Indicates that the transaction has been rolled back due to time out. Automatically performs a rollback on the transaction. We only reach this state if the transaction is active.

getTimedOut

protected boolean getTimedOut()

Returns true if the transaction has timed out and rolled back.

getPropagationContext

protected org.omg.CosTransactions.PropagationContext getPropagationContext()

Returns the propagation context used to import this transaction or null if the transaction was not imported.

listResources

protected java.lang.String[] listResources()

Returns a listing of the resources associated with this transaction. Provides an identification of all the XA resources, OTS resources and subtransactions.

Returns:

Array of description of all resources enlisted with this transaction

endResources

protected void endResources()
                     throws java.lang.IllegalStateException,
                            javax.transaction.RollbackException

Called to end the resources as part of the one phase commit protocol. On entry the status must be either #STATUS_ACTIVE) or {@link #STATUS_MARKED_ROLLBACK).

The heuristic decision can be any of the following:

• {@link #Heuristic.COMMIT} All resources are ended successfully need to be commited using one phase commit on the resources.
• {@link #Heuristic.ROLLBACK} The transaction has been marked for rollback, an error has occured or at least one resource failed to end

Throws:

java.lang.IllegalStateException - The transaction is not active or is in the process of being commited, or prepared for two phase commit.

javax.transaction.RollbackException

forget

protected void forget(int ignoreHeuristic)
               throws java.lang.IllegalStateException

Called to forget about the transaction at the end of either a commit or rollback. This method servers three purposes. First, it will tell all the resources to forget about the transaction and release them if the appropriate heuristic exception occurred. Second, it will notify all the synchronziation objects that the transaction has completed with the transaction's status. Last, it will release any objects held by the transaction and dissocaite it from the list of available transactions.

The ignoreHeuristic argument is used to determine what heuristic outcomes cause forget to be called on the resources associated with the transaction. For instance if transaction commit has been called and the outcome is Heuristic.COMMIT then resource forget should be not be called. In this case resource forget should be called on all other heuristic outcomes like Heuristic.ROLLBACK for instance. Similarly if transaction rollback has been called and the outcome is Heuristic.ROLLBACK then resource forget should not be called. In this case resource forget should be called on all other heuristic outcomes like Heuristic.COMMIT.

Forget always gets called if we are doing two-phase commit.

Parameters:

ignoreHeuristic - the heuristic to ignore

Throws:

java.lang.IllegalStateException - The transaction has not commited or rolledback yet

See Also:

HeuristicExceptions

addRecovery

protected void addRecovery(javax.transaction.xa.XAResource xaResource,
                           javax.transaction.xa.Xid xid)

Called during recovery to add a resource. This method is called for every resource that reports a transaction branch during recovery. The resource's Xid is preserved and the resource is not started in the transaction. If an error occurs, the transaction heuristic decision is changed to hazard (not knowing whether the resource commits or rollsback).

Parameters:

xaResource - The XA resource

xid - The Xid for the transaction branch