tyrex.tm

Class Journal

public abstract class Journal extends 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
abstract static classJournal.RecoveredTransaction
Provides information about a recovered transaction.
Method Summary
abstract voidclose()
Called to close the journal and release any resources held by the journal.
abstract voidcommit(Xid xid, int decision)
Records a transaction commit.
abstract voidforget(Xid xid)
Forgets a heuristically complete transaction.
abstract voidprepare(Xid xid, int decision)
Records the outcome of transaction preparation.
abstract Journal.RecoveredTransaction[]recover()
Called to initiate recovery.
abstract voidrollback(Xid xid)
Records a transaction rollback.

Method Detail

close

public abstract void close()
Called to close the journal and release any resources held by the journal.

UNKNOWN: SystemException An error occured while performing this operation

commit

public abstract void commit(Xid xid, int decision)
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

UNKNOWN: SystemException An error occured while performing this opetion

forget

public abstract void forget(Xid xid)
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

UNKNOWN: SystemException An error occured while performing this operation

prepare

public abstract void prepare(Xid xid, int decision)
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

UNKNOWN: SystemException An error occured while performing this operation

recover

public abstract Journal.RecoveredTransaction[] recover()
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

UNKNOWN: SystemException An error occured while performing this operation

rollback

public abstract void rollback(Xid xid)
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

UNKNOWN: SystemException An error occured while performing this operation

Original code is Copyright (c) 1999-2001, Intalio, Inc. All Rights Reserved. Contributions by MetaBoss team are Copyright (c) 2003-2005, Softaris Pty. Ltd. All Rights Reserved.