org.objectweb.howl.log.xa
Class XALogger

java.lang.Object
  extended byorg.objectweb.howl.log.LogObject
      extended byorg.objectweb.howl.log.Logger
          extended byorg.objectweb.howl.log.xa.XALogger
All Implemented Interfaces:
LogEventListener

public class XALogger
extends Logger
implements LogEventListener

A specialized subclass of Logger intended to provide functionality required by any XA Transaction Manager.

This class provides wrappers for all public methods of Logger to allow enforcement of policies that are in place for an XA TM log.

This class implements LogEventListener. During logOverflowNotification processing, entries in the activeTx[] are re-logged and the active mark is moved.

If the application has called setLogEventListener, then Log events are forwarded to the application after they are processed by this class.

Author:
Michael Giroux

Field Summary
 
Fields inherited from class org.objectweb.howl.log.Logger
isClosed
 
Constructor Summary
XALogger()
          Construct a Logger using default Configuration object.
XALogger(Configuration config)
          Construct a Logger using a Configuration supplied by the caller.
 
Method Summary
 void activeTxDisplay()
          displays entries in the activeTx table.
 void close()
          close the Log files and perform necessary cleanup tasks.
 int getActiveTxUsed()
          Used by TM and test cases to obtain the number of entries in the activeTx table.
 java.lang.String getStats()
          return an XML node containing statistics for this object along with the base Logger, the LogFile pool and the LogBuffer pool.
 void logOverflowNotification(long overflowFence)
          called by Logger when log file is about to overflow.
 void open()
          Not supported for XALogger.
 void open(ReplayListener listener)
          calls super.open() to perform standard open functionality then replays the log to rebuild the activeTx table.
 long put(byte[][] data, boolean sync)
          add a USER record consisting of byte[][] to the log.
 long put(byte[] data, boolean sync)
          add a USER record consisting of byte[] to the log.
 XACommittingTx putCommit(byte[][] record)
          Write a begin COMMIT record to the log.
 long putDone(byte[][] record, XACommittingTx tx)
          Write a DONE record to the log.
 void replay(ReplayListener listener)
          Wrapp Logger#replay(ReplayListener) so we can intercept onRecord() notifications to process XACOMMIT and XACOMMITMOVED records.
 void replay(ReplayListener listener, long key)
          Wrapp Logger#replay(ReplayListener, long) so we can intercept onRecord() notifications to process XACOMMIT and XACOMMITMOVED records.
 void replayActiveTx(ReplayListener listener)
          Called by the TM to receive copies of the active transaction entries.
 void setLogEventListener(LogEventListener eventListener)
          Saves a reference to callers LogEventListener.
 
Methods inherited from class org.objectweb.howl.log.Logger
get, getActiveMark, getNext, mark, mark, put, replay, setAutoMark
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XALogger

public XALogger()
         throws java.io.IOException
Construct a Logger using default Configuration object.

Throws:
java.io.IOException

XALogger

public XALogger(Configuration config)
         throws java.io.IOException
Construct a Logger using a Configuration supplied by the caller.

Parameters:
config - Configuration object
Throws:
java.io.IOException
Method Detail

put

public long put(byte[] data,
                boolean sync)
         throws LogClosedException,
                LogRecordSizeException,
                LogFileOverflowException,
                java.lang.InterruptedException,
                java.io.IOException
add a USER record consisting of byte[] to the log.

waits for overflow notification processing to complete prior to putting the data to the log.

Overrides:
put in class Logger
Parameters:
data - byte[] to be written to log
sync - true if caller wishes to block waiting for the record to force to disk.
Returns:
log key for the record
Throws:
LogClosedException - If the TM has called open() but has not called replay(). Also thrown if log is actually closed. Check the toString() for details.
LogRecordSizeException
LogFileOverflowException
java.io.IOException
java.lang.InterruptedException
See Also:
Logger.put(byte[], boolean)

put

public long put(byte[][] data,
                boolean sync)
         throws LogClosedException,
                LogRecordSizeException,
                LogFileOverflowException,
                java.lang.InterruptedException,
                java.io.IOException
add a USER record consisting of byte[][] to the log.

waits for overflow notification processing to complete prior to putting the data to the log.

Overrides:
put in class Logger
Parameters:
data - record data
sync - true if call should block until force
Returns:
a key that can be used to locate the record. Some implementations may use the key as a correlation ID to associate related records. When automark is disabled (false) the caller must invoke mark() using this key to indicate the location of the oldest active entry in the log.
Throws:
LogClosedException - If the TM has called open() but has not called replay(). Also thrown if log is actually closed. Check the toString() for details.
LogFileOverflowException
java.lang.InterruptedException
java.io.IOException
LogRecordSizeException
See Also:
Logger.put(byte[][], boolean)

putCommit

public XACommittingTx putCommit(byte[][] record)
                         throws LogClosedException,
                                LogRecordSizeException,
                                LogFileOverflowException,
                                java.lang.InterruptedException,
                                java.io.IOException
Write a begin COMMIT record to the log.

Call blocks until the data is forced to disk.

Parameters:
record - byte[][] containing data to be logged
Returns:
XACommittingTx object to be used whe putting the DONE record.
Throws:
LogClosedException - If the TM has called open() but has not called replay(). Also thrown if log is actually closed. Check the toString() for details.
java.io.IOException
java.lang.InterruptedException
LogFileOverflowException
LogRecordSizeException

putDone

public long putDone(byte[][] record,
                    XACommittingTx tx)
             throws LogClosedException,
                    LogRecordSizeException,
                    LogFileOverflowException,
                    java.lang.InterruptedException,
                    java.io.IOException
Write a DONE record to the log.

Remove XACommittingTx object from the list of active transactions.

Parameters:
record - byte[][] containing data to be logged.

If record is null then no user data is written to the journal.

tx - the XACommittingTx that was returned by the putCommit() routine for this transaction.
Returns:
long log key for the record byte[][].

If record is null, then return is 0L.

Throws:
java.io.IOException
java.lang.InterruptedException
LogFileOverflowException
LogRecordSizeException
LogClosedException - If the TM has called open() but has not called replay(). Also thrown if log is actually closed. Check the toString() for details.

logOverflowNotification

public void logOverflowNotification(long overflowFence)
called by Logger when log file is about to overflow.

copies XACommittingTx records forward to allow reuse of older log file space.

calls Logger.mark() to set the new active mark at the completion of the scan.

Exceptions are ignored. Hopefully they will be reported to the TM when a transaction thread attempts to write a log record.

While we are processing activeTx[] we publish the overflowFence so putCommit knows that any record it stores with a key below the fence must be re-put.

This notification is not forwarded to the LogEventListener eventListener that was registered by the TM.

Specified by:
logOverflowNotification in interface LogEventListener
Parameters:
overflowFence - COMMIT records with log keys lower than fence must be moved. All others can be ignored for now.

getStats

public java.lang.String getStats()
return an XML node containing statistics for this object along with the base Logger, the LogFile pool and the LogBuffer pool.

Overrides:
getStats in class Logger
Returns:
String contiining XML document.

setLogEventListener

public void setLogEventListener(LogEventListener eventListener)
Saves a reference to callers LogEventListener.

Some LogEventListener notifications may be passed onto the callers eventListener. Refer to javadocs in this source for individual notifications to determine if the notification is passed on to the TM.

Overrides:
setLogEventListener in class Logger
Parameters:
eventListener - object to be notified of logger events.

open

public void open()
Not supported for XALogger.

XALogger must rebuild the activeTx table prior to allowing any calls to put() methods. To enforce this, callers must use the open(ReplayListener) method.

Overrides:
open in class Logger
Throws:
java.lang.UnsupportedOperationException

open

public void open(ReplayListener listener)
          throws InvalidFileSetException,
                 LogConfigurationException,
                 InvalidLogBufferException,
                 LogClosedException,
                 java.lang.ClassNotFoundException,
                 java.io.IOException,
                 java.lang.InterruptedException
calls super.open() to perform standard open functionality then replays the log to rebuild the activeTx table.

Sets replayNeeded flag to block calls to put() methods until the replay is complete. (This may be unnecessary because the replay blocks until it is complete, but we do this to prevent the TM from trying to make log entries on another thread before the log is fully open.)

During the replay, the XALogger calls the TM's listener.onRecord() with an XALogRecord object. The TM is expected to call getTx() to obtain a reference to the XACommittingTx that will be used to complete the transaction usin putDone() later.

Note that XALogger does not call the TM's listener.getLogRecord().

Parameters:
listener - The TM can receive replay events by providing a ReplayListener. TMs that do not wish to see all records during the open replay should pass a null ReplayListener.
Throws:
InvalidFileSetException
LogConfigurationException
InvalidLogBufferException
LogClosedException
java.lang.ClassNotFoundException
java.io.IOException
java.lang.InterruptedException
See Also:
replayActiveTx(ReplayListener)

close

public void close()
           throws java.io.IOException,
                  java.lang.InterruptedException
Description copied from class: Logger
close the Log files and perform necessary cleanup tasks.

Overrides:
close in class Logger
Throws:
java.io.IOException
java.lang.InterruptedException

getActiveTxUsed

public int getActiveTxUsed()
Used by TM and test cases to obtain the number of entries in the activeTx table.

TIP: if value does not agree with expected value in TM or test case, we probably have a bug somewhere.

Returns:
current number of used entries in activeTx table

activeTxDisplay

public void activeTxDisplay()
displays entries in the activeTx table.

useful for debug.


replay

public void replay(ReplayListener listener)
            throws LogConfigurationException
Wrapp Logger#replay(ReplayListener) so we can intercept onRecord() notifications to process XACOMMIT and XACOMMITMOVED records.

Overrides:
replay in class Logger
Parameters:
listener - an object that implements ReplayListener interface.
Throws:
LogConfigurationException - most likely because the configured LogBuffer class cannot be found.
See Also:
Logger.replay(ReplayListener, long)

replay

public void replay(ReplayListener listener,
                   long key)
            throws InvalidLogKeyException,
                   LogConfigurationException
Wrapp Logger#replay(ReplayListener, long) so we can intercept onRecord() notifications to process XACOMMIT and XACOMMITMOVED records.

Overrides:
replay in class Logger
Parameters:
listener - an object that implements ReplayListener interface.
key - a log key to begin replay from.

The mark should be a valid log key returned by the put() method. To replay the entire log beginning with the oldest available record, mark should be set to zero (0L).

Throws:
InvalidLogKeyException - if mark is not a valid log key.
LogConfigurationException - most likely because the configured LogBuffer class cannot be found.

replayActiveTx

public void replayActiveTx(ReplayListener listener)
Called by the TM to receive copies of the active transaction entries.

TMs can use this method as an alternative to passing a ReplayListener to open. The advantage is that only active transaction entries are returned to the ReplayListener.onRecord() method.

Parameters:
listener - The activeTx entries are passed to the TM through this ReplayListener.


Copyright © 2003-2005 HOWL Development Team. All Rights Reserved.