org.exolab.jms.messagemgr
Class ResourceManager

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

All Implemented Interfaces:

java.lang.Runnable, java.io.Serializable, org.exolab.core.service.Serviceable

public class ResourceManager

extends org.exolab.core.service.BasicService

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.6 $ $Date: 2003/08/17 01:32:25 $

Author:

Jim Alateras

See Also:

Serialized Form

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(java.lang.String dir)
Construct a resource manager using the specified directory, which must already exist.

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
int	getGCMode() Return the garbage collection mode for the resource manager
java.lang.String	getLogDirectory() Retrieve the name of the log directory
int	getLogFileSize() Return the maximum size that each log file can grow too.
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.
static ResourceManager	instance() Return the singleton instance of the ResourceManager
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, java.lang.String 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.
void	run()
boolean	setGCMode(int mode) Set the GC mode for the resource manager.
void	setLogDirectory(java.lang.String dir) Set the log directory.
void	setLogFileSize(int size) Set the maximum size of each log file.
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()
void	start(javax.transaction.xa.Xid id, int flags)
void	stop()

Methods inherited from class org.exolab.core.service.BasicService

toString

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

getName, getState, restart, setState

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(java.lang.String dir)
                throws ResourceManagerException

Construct a resource manager using the specified directory, which must already exist. If the directory does not exist or there is no permisssion to access it then throw a ResourceManagerException

Parameters:

dir - - the base directory

Throws:

ResourceManagerException -

Method Detail

instance

public static ResourceManager instance()
                                throws ResourceManagerException

Return the singleton instance of the ResourceManager

Returns:

ResourceManager

Throws:

ResourceManagerException -

setLogDirectory

public void setLogDirectory(java.lang.String dir)
                     throws java.lang.IllegalArgumentException

Set the log directory. This is the directory where all the log files are stored

Parameters:

dir - - the name of the directory (absolute or relative)

Throws:

java.lang.IllegalArgumentException - if the string is not a directory

getLogDirectory

public java.lang.String getLogDirectory()

Retrieve the name of the log directory

Returns:

String - log dir name

setLogFileSize

public void setLogFileSize(int size)

Set the maximum size of each log file. When this size is reached a new log file is created. The size of the log file can be changed dynamically during runtime. If it is not specified it will default to 1MB.

The size is specified in bytes

Parameters:

size - - the max size of each log file

getLogFileSize

public int getLogFileSize()

Return the maximum size that each log file can grow too.

Returns:

int - log file size

setGCMode

public boolean setGCMode(int mode)

Set the GC mode for the resource manager. Valid values are GC_SYNCHRONOUS, GC_ASYNCHRONOUS and GC_DISABLED.

Parameters:

mode - - one of GC_*

Returns:

boolean - if the specified mode has been correctly set

getGCMode

public int getGCMode()

Return the garbage collection mode for the resource manager

Returns:

int

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,
                               java.lang.String 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:

txid - - 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:

xid - - 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:

xid - - 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:

xid - - 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:

xid - - the xa transaction identity

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.

Parameters:

flag - - One of TMSTARTRSCAN, TMENDRSCAN, TMNOFLAGS. TMNOFLAGS

Xid[] - - the set of Xids to recover

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

Parameters:

xid - - the xa transaction identity

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.

Parameters:

seconds - - timeout in seconds

Returns:

boolean - true if the new transaction timeout was accepted

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

Parameters:

xid - - the xa transaction identity

flags - - One of TMNOFLAGS, TMJOIN, or TMRESUME

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

start

public void start()
           throws org.exolab.core.service.ServiceException

Overrides:

start in class org.exolab.core.service.BasicService

stop

public void stop()
          throws org.exolab.core.service.ServiceException

Overrides:

stop in class org.exolab.core.service.BasicService

run

public void run()

Overrides:

run in class org.exolab.core.service.BasicService

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 -