tyrex.tm
Class Journal

java.lang.Object
  tyrex.tm.Journal

public abstract class Journal

extends java.lang.Object

Abstract class for transactional journal.

This class supports journaling of two-phase commit transactions, recording both prepare, commit, rollback and conslution of transactions.

A complete transaction is one for which XAResource.forget has been called. The transaction manager is not interested in recovering complete transactions. During journaling this is indicated by the forget method which closes the transaction chain. During recovery this is indicated by the complete flag and the completed method.

During recovery, the outcome of every recovered transaction must be recorded in the journal to close the transaction chain. Complete transaction must not be recorded, as the chain has already been closed.

Transaction journaling is only required when the resource manager participates in a distributed transaction. Local transactions are never recovered and need not be recorded in the journal.

If the transaction completes by one-phase commit or rolling back in lieu of two-phase commit, the transaction manager will not attempt to recover the transaction. In this case, it is unnecessary to record the transaction, unless a heuristic decision has been reached.

When performing two-phase commit, the outcome of the prepare stage must be recorded, followed by the concluing commit or rollback of the transaction. If an error occured before the transaction is forgotten, the transaction should be recovered.

Version:

$Revision: 1.3 $

Author:

Assaf Arkin

Nested Class Summary

static class

Journal.RecoveredTransaction Provides information about a recovered transaction.

Constructor Summary

Journal()

Method Summary

abstract void	close() Called to close the journal and release any resources held by the journal.
abstract void	commit(javax.transaction.xa.Xid xid, int decision) Records a transaction commit.
abstract void	forget(javax.transaction.xa.Xid xid) Forgets a heuristically complete transaction.
abstract void	prepare(javax.transaction.xa.Xid xid, int decision) Records the outcome of transaction preparation.
abstract Journal.RecoveredTransaction[]	recover() Called to initiate recovery.
abstract void	rollback(javax.transaction.xa.Xid xid) Records a transaction rollback.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Journal

public Journal()

Method Detail

prepare

public abstract void prepare(javax.transaction.xa.Xid xid,
                             int decision)
                      throws javax.transaction.SystemException

Records the outcome of transaction preparation. The decision code indicates whether the transaction is read-only, requires commit or has rolled back.

This method is called to record the outcome after preparing a transaction. It must record a decision to commit or rollback the transaction. This method may be skipped if the transaction is identified as read-only or for local transactions.

If this method is called, commit or rollback must follow.

Valid values for the decision are XAResource.XA_OK, XAResource.XA_RDONLY, or any of the heuristic codes defined by XAException.XA_HEUR*.

Parameters:

xid - The transaction identifier

decision - The outcome of the prepare stage

Throws:

javax.transaction.SystemException

commit

public abstract void commit(javax.transaction.xa.Xid xid,
                            int decision)
                     throws javax.transaction.SystemException

Records a transaction commit.

This method is called when completing two-phase commit of a transaction branch. This method may be skipped if the transaction is identified as read-only or is a local transaction.

If this method is called, forget must follow.

If the transaction has properly committed, the heuristic decision will be XAResource.XA_HEURCOM. Otherwise, use any of the heuristic codes defined by XAException.XA_HEUR*.

Parameters:

xid - The transaction identifier

decision - The heuristic decision

Throws:

javax.transaction.SystemException

rollback

public abstract void rollback(javax.transaction.xa.Xid xid)
                       throws javax.transaction.SystemException

Records a transaction rollback.

This method is called when completing two-phase commit of a transaction branch. This method may be skipped for local transactions.

If this method is called, forget must follow.

Parameters:

xid - The transaction identifier

Throws:

javax.transaction.SystemException

forget

public abstract void forget(javax.transaction.xa.Xid xid)
                     throws javax.transaction.SystemException

Forgets a heuristically complete transaction.

This method is called when completing two-phase commit to discard the transaction and close the transaction chain.

Parameters:

xid - The transaction identifier

Throws:

javax.transaction.SystemException

recover

public abstract Journal.RecoveredTransaction[] recover()
                                                throws javax.transaction.SystemException

Called to initiate recovery. This method will return information about all transactions that are subject to recovery.

A recoverable transaction is a transaction that has been processed through two-phase commit but has not been completed. This method will return the heuristic decision for the transaction as reached by the transaction manager.

Transactions that have been completed are generally not returned by this method. In addition it is possible that resource managers will return additional transaction branchs for which the transaction manager has not reached any heuristic decision.

Returns:

An array of zero of more recoverable transactions

Throws:

javax.transaction.SystemException

close

public abstract void close()
                    throws javax.transaction.SystemException

Called to close the journal and release any resources held by the journal.

Throws:

javax.transaction.SystemException