org.exolab.jms.messagemgr
Class ResourceManager

java.lang.Object
  |
  +--org.exolab.jms.service.Service
        |
        +--org.exolab.jms.messagemgr.ResourceManager

All Implemented Interfaces:

Serviceable

public class ResourceManager

extends Service

The resource manager provides XA support for the JMS Server.

The resource manager is responsible for managing the various transaction identifiers and managing the association between transaction ids and connections.

The resource manager will store the global XID's and their state in the database for recovery purposes.

Messages that arrive, and are associated with an XID are not processed through the MessageMgr. Instead they are routed to this resource managers where they are cached until the associated XID is committed or rolled back. If the transaction is successfully committed, through the 2PC protocol the messages will pass through the system.

Similarly, messages that are sent to consumers, either synchronously or asynchronously are also cached by the resource manager until the global transaction completes.

On startup the resource manager will read all incomplete transactions, which are incompleted into memory. It will then process trnasactions that have timed out.

The transaction manager will call the recover(int) method and obtain a list of incomplete transaction for the purpose of completing them where possible.

Version:

$Revision: 1.3 $ $Date: 2005/08/30 07:26:49 $

Author:

Jim Alateras

Field Summary

static int	GC_ASYNCHRONOUS Asynchronous garbage collection is used to remove processed log files asynchronous (i.e in a different thread context).
static int	GC_DISABLED This is used to indicate the garbage collection has been disabled and that the client will take responsibility for all aspects of log file management.
static int	GC_SYNCHRONOUS Synchronous gabrage collection is used to remove processed log files when the last trnasaction, in that log file, has been successfully processed.
static java.lang.String	RM_LOGFILE_EXTENSION The extension for all transaction log files

Constructor Summary

ResourceManager(MessageManager messages, DestinationManager destinations, DatabaseService database)
Construct a resource manager using the default directory for its log files.

Method Summary

protected void	buildLogFileList() Build a list of all log files in the specified log directory
void	commit(javax.transaction.xa.Xid id, boolean onePhase) Ensure that a transaction with the specified xid is currently active.
protected TransactionLog	createNextTransactionLog() Create the next TransactionLog and add it to the list of managed transaction logs.
void	end(javax.transaction.xa.Xid id, int flags) Ends the work performed on behalf of a transaction branch.
void	forget(javax.transaction.xa.Xid id) Tell the resource manager to forget about a heuristically completed transaction branch.
void	garbageCollect() This is the entry point for the garbage collection callback.
boolean	gcDisabled() Check whether garbage collection has been disabled
java.lang.String	getResourceManagerId() Return the resource manager identity
protected long	getSequenceNumber(java.lang.String name) Return the sequence number of the file files are associated with a unique number
protected java.lang.Object[]	getTransactionRecords(ExternalXid xid, java.lang.String rid) Return an arrya of records, both state and date, for the specified global transaction
int	getTransactionTimeout() Return the transaction timeout for this instance of the resource manager.
boolean	isSameRM(javax.transaction.xa.XAResource xares) Ask the resource manager to prepare for a transaction commit of the transaction specified in xid
void	logPublishedMessage(javax.transaction.xa.Xid xid, MessageImpl message) Log this published message so that it can be passed through the system when the associated global transaction commits.
void	logReceivedMessage(javax.transaction.xa.Xid xid, long id, MessageHandle handle) Log that this message handle was sent to the consumer within the specified global transaction identity.
void	logTransactionState(javax.transaction.xa.Xid xid, TransactionState state) Add an StateTransactionLogEntry using the specified txid, rid and state
int	prepare(javax.transaction.xa.Xid id) Obtain a list of prepared transaction branches from a resource manager.
javax.transaction.xa.Xid[]	recover(int flag) Inform the resource manager to roll back work done on behalf of a transaction branch
void	rollback(javax.transaction.xa.Xid id) Set the current transaction timeout value for this XAResource instance.
boolean	setTransactionTimeout(int seconds) Start work on behalf of a transaction branch specified in xid If TMJOIN is specified, the start is for joining a transaction previously seen by the resource manager
void	start(javax.transaction.xa.Xid id, int flags)

Methods inherited from class org.exolab.jms.service.Service

doStart, doStop, getName, isStarted, restart, start, stop, toString

Methods inherited from class java.lang.Object

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

Field Detail

RM_LOGFILE_EXTENSION

public static final java.lang.String RM_LOGFILE_EXTENSION

The extension for all transaction log files

GC_DISABLED

public static final int GC_DISABLED

This is used to indicate the garbage collection has been disabled and that the client will take responsibility for all aspects of log file management. This is useful in situations where the client wants to archive the transaction log files

This is the default mode for GC.

GC_SYNCHRONOUS

public static final int GC_SYNCHRONOUS

Synchronous gabrage collection is used to remove processed log files when the last trnasaction, in that log file, has been successfully processed. This is more efficient means since the log files does not need to be scanned asynchronously to determine whether all the transactions have been processed.

GC_ASYNCHRONOUS

public static final int GC_ASYNCHRONOUS

Asynchronous garbage collection is used to remove processed log files asynchronous (i.e in a different thread context). This is rather expensive since it must manually scan each log file and determine whether all transactions, in that file, have been closed. If this is the case then it will remove the log file.

Constructor Detail

ResourceManager

public ResourceManager(MessageManager messages,
                       DestinationManager destinations,
                       DatabaseService database)
                throws ResourceManagerException

Construct a resource manager using the default directory for its log files.

If the directory does not exist or there is no permisssion to access it, then throw a ResourceManagerException.

Parameters:

messages - the message manager

destinations - the destination manager

database - the database service

Throws:

ResourceManagerException -

Method Detail

gcDisabled

public boolean gcDisabled()

Check whether garbage collection has been disabled

Returns:

boolean - true if gc is disabled

logPublishedMessage

public void logPublishedMessage(javax.transaction.xa.Xid xid,
                                MessageImpl message)
                         throws TransactionLogException,
                                ResourceManagerException,
                                javax.jms.JMSException

Log this published message so that it can be passed through the system when the associated global transaction commits.

Parameters:

xid - - the global transaction identity

message - - the message published

Throws:

TransactionLogException - - error adding the entry

ResourceManagerException - - error getting the trnasaction log

javax.jms.JMSException - - if there is an issue with prep'ing the message

logReceivedMessage

public void logReceivedMessage(javax.transaction.xa.Xid xid,
                               long id,
                               MessageHandle handle)
                        throws TransactionLogException,
                               ResourceManagerException

Log that this message handle was sent to the consumer within the specified global transaction identity. The message will be acknowledged when the global transaction commits. Alternatively, if the global transaction is rolled back the message handle will be returned to the destination

Parameters:

xid - the global transaction identity

id - the consumer receiving this message

handle - - the handle of the message received

Throws:

TransactionLogException - - error adding the entry

ResourceManagerException - - error getting the transaction log

logTransactionState

public void logTransactionState(javax.transaction.xa.Xid xid,
                                TransactionState state)
                         throws TransactionLogException,
                                ResourceManagerException

Add an StateTransactionLogEntry using the specified txid, rid and state

Parameters:

xid - - the transaction identifier

state - - the transaction log state

Throws:

TransactionLogException - - error adding the entry

ResourceManagerException - - error getting the trnasaction log

garbageCollect

public void garbageCollect()

This is the entry point for the garbage collection callback. It scans through the each transaction log file and determines whether it can be garbage collected. If it can then it simply destroys the corresponding TransactionLog.

commit

public void commit(javax.transaction.xa.Xid id,
                   boolean onePhase)
            throws javax.transaction.xa.XAException

Ensure that a transaction with the specified xid is currently active. If this is the case then commit the transaction based onb the value of the onePhase flag.

This will have the effect of passing all messages through

Parameters:

id - - the xa transaction identity

onePhase - - treu if it is a one phase commit

Throws:

javax.transaction.xa.XAException - - if there is a problem completing the call

end

public void end(javax.transaction.xa.Xid id,
                int flags)
         throws javax.transaction.xa.XAException

Ends the work performed on behalf of a transaction branch. The resource manager disassociates the XA resource from the transaction branch specified and let the transaction be completedCommits an XA transaction that is in progress.

Parameters:

id - - the xa transaction identity

flags - - one of TMSUCCESS, TMFAIL, or TMSUSPEND

Throws:

javax.transaction.xa.XAException - - if there is a problem completing the call

forget

public void forget(javax.transaction.xa.Xid id)
            throws javax.transaction.xa.XAException

Tell the resource manager to forget about a heuristically completed transaction branch.

Parameters:

id - - the xa transaction identity

Throws:

javax.transaction.xa.XAException - - if there is a problem completing the call

getTransactionTimeout

public int getTransactionTimeout()
                          throws javax.transaction.xa.XAException

Return the transaction timeout for this instance of the resource manager.

Returns:

int - the timeout in seconds

Throws:

javax.transaction.xa.XAException - - if there is a problem completing the call

isSameRM

public boolean isSameRM(javax.transaction.xa.XAResource xares)
                 throws javax.transaction.xa.XAException

Ask the resource manager to prepare for a transaction commit of the transaction specified in xid

Parameters:

xares -

Returns:

int - XA_RDONLY or XA_OK

Throws:

javax.transaction.xa.XAException - - if there is a problem completing the call

prepare

public int prepare(javax.transaction.xa.Xid id)
            throws javax.transaction.xa.XAException

Obtain a list of prepared transaction branches from a resource manager. The transaction manager calls this method during recovery to obtain the list of transaction branches that are currently in prepared or heuristically completed states.

Throws:

javax.transaction.xa.XAException - - if there is a problem completing the call

recover

public javax.transaction.xa.Xid[] recover(int flag)
                                   throws javax.transaction.xa.XAException

Inform the resource manager to roll back work done on behalf of a transaction branch

Throws:

javax.transaction.xa.XAException - - if there is a problem completing the call

rollback

public void rollback(javax.transaction.xa.Xid id)
              throws javax.transaction.xa.XAException

Set the current transaction timeout value for this XAResource instance.

Throws:

javax.transaction.xa.XAException - - if there is a problem completing the call

setTransactionTimeout

public boolean setTransactionTimeout(int seconds)
                              throws javax.transaction.xa.XAException

Start work on behalf of a transaction branch specified in xid If TMJOIN is specified, the start is for joining a transaction previously seen by the resource manager

Throws:

javax.transaction.xa.XAException - - if there is a problem completing the call

start

public void start(javax.transaction.xa.Xid id,
                  int flags)
           throws javax.transaction.xa.XAException

getResourceManagerId

public java.lang.String getResourceManagerId()

Return the resource manager identity

Returns:

the resource manager identity

createNextTransactionLog

protected TransactionLog createNextTransactionLog()
                                           throws ResourceManagerException

Create the next TransactionLog and add it to the list of managed transaction logs.

The method will throw ResourceManagerException if there is a problem completing the request.

Throws:

ResourceManagerException -

buildLogFileList

protected void buildLogFileList()

Build a list of all log files in the specified log directory

Throws:

java.lang.IllegalArgumentException - - if the directory does not exist.

getTransactionRecords

protected java.lang.Object[] getTransactionRecords(ExternalXid xid,
                                                   java.lang.String rid)

Return an arrya of records, both state and date, for the specified global transaction

Parameters:

xid - - the global transaction id

rid - - the resource id

Returns:

Object[] - array of records

getSequenceNumber

protected long getSequenceNumber(java.lang.String name)
                          throws ResourceManagerException

Return the sequence number of the file files are associated with a unique number

Parameters:

name - - the file name to investigate

Returns:

long - the transaction log number

Throws:

ResourceManagerException -