org.objectweb.howl.log
Class Logger

java.lang.Object
  extended byorg.objectweb.howl.log.LogObject
      extended byorg.objectweb.howl.log.Logger
Direct Known Subclasses:
XALogger

public class Logger
extends org.objectweb.howl.log.LogObject

Manage a configured set of two or more physical log files.

Log files have a configured maximum size. When a file has reached the configured capacity, Logger switches to the next available alternate file. Normally, log files are created in advance to guarantee that space is available during execution.

Each log file has a file header containing information allowing Logger to reposition and replay the logs during a recovery scenario.

LogFile marking

The LogFile's mark is the the position within the file of the oldest active entry. Initially the mark is set at the beginning of the file. At some configured interval, the caller invokes mark() with the key of the oldest active entry in the log.

For XA the key would be for the oldest transaction still in committing state. In theory, XA could call mark() every time a DONE record is logged. In practice, it should only be necessary to call mark() every minute or so depending on the capacity of the log files.

The Logger maintains an active mark within the set of log files. A file may be reused only if the mark does not reside within the file. The Logger will throw LogFileOverflowException if an attempt is made to switch to a file that contains a mark.

Author:
Michael Giroux

Field Summary
protected  boolean isClosed
          indicates whether the LogFile is open.
 
Constructor Summary
Logger()
          Construct a Logger using default Configuration object.
Logger(Configuration config)
          Construct a Logger using a Configuration supplied by the caller.
 
Method Summary
 void close()
          close the Log files and perform necessary cleanup tasks.
 LogRecord get(LogRecord lr, long mark)
          Read a specific record from the log.
 long getActiveMark()
           
 LogRecord getNext(LogRecord lr)
          Read the journal record that follows the record identified by lr.
 java.lang.String getStats()
          return an XML node containing statistics for the Logger, the LogFile pool and the LogBuffer pool.
 void mark(long key)
          calls Logger.mark(key, force) with force set to true .
 void mark(long key, boolean force)
          sets the LogFile's mark.
 void open()
          open Log files and perform necessart initialization.
 long put(byte[][] data, boolean sync)
          add a USER record consisting of byte[][] to log.
 long put(byte[] data, boolean sync)
          add a USER record consisting of byte[] to the log.
protected  long put(short type, byte[][] data, boolean sync)
          Sub-classes call this method to write log records with a specific record type.
 void replay(ReplayListener listener)
          Replays log from the active mark forward to the current position.
 void replay(ReplayListener listener, long mark)
          Replays log from a specified mark forward to the current mark.
protected  void replay(ReplayListener listener, long mark, boolean replayCtrlRecords)
          Allows sub-classes of Logger to replay control records.
 void setAutoMark(boolean autoMark)
          Sets the LogFile marking mode.
 void setLogEventListener(LogEventListener eventListener)
          Registers a LogEventListener for log event notifications.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

isClosed

protected volatile boolean isClosed
indicates whether the LogFile is open.

Logger methods return LogClosedException when log is closed.

Constructor Detail

Logger

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

Throws:
java.io.IOException

Logger

public Logger(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

getActiveMark

public long getActiveMark()
Returns:
activeMark member of the associated LogFileManager.

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 log.

if sync parameter is true, then the method will block (in bmgr.put()) until the data buffer is forced to disk. Otherwise, the method returns immediately.

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
LogRecordSizeException
LogFileOverflowException
java.lang.InterruptedException
java.io.IOException
See Also:
mark(long), setAutoMark(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.

wrap byte[] data in a new byte[][] and delegates call to put(byte[][], boolean)

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
LogRecordSizeException
LogFileOverflowException
java.lang.InterruptedException
java.io.IOException

put

protected long put(short type,
                   byte[][] data,
                   boolean sync)
            throws LogClosedException,
                   LogRecordSizeException,
                   LogFileOverflowException,
                   java.lang.InterruptedException,
                   java.io.IOException
Sub-classes call this method to write log records with a specific record type.

Parameters:
type - a record type defined in LogRecordType.
data - record data to be logged.
sync - boolean indicating whether call should wait for data to be written to physical disk.
Returns:
a log key that can be used to reference the record.
Throws:
LogClosedException
LogRecordSizeException
LogFileOverflowException
java.lang.InterruptedException
java.io.IOException

mark

public void mark(long key,
                 boolean force)
          throws InvalidLogKeyException,
                 LogClosedException,
                 java.io.IOException,
                 java.lang.InterruptedException
sets the LogFile's mark.

mark() provides a generalized method for callers to inform the Logger that log space can be released for reuse.

calls LogFileManager to process the request.

Parameters:
key - is a log key returned by a previous call to put().
force - a boolean that indicates whether the mark data should be forced to disk. When set to true the caller is blocked until the mark record is forced to disk.
Throws:
InvalidLogKeyException - if key parameter is out of range. key must be greater than current activeMark and less than the most recent key returned by put().
LogClosedException - if this logger instance has been closed.
java.io.IOException
java.lang.InterruptedException

mark

public void mark(long key)
          throws InvalidLogKeyException,
                 LogClosedException,
                 java.io.IOException,
                 java.lang.InterruptedException
calls Logger.mark(key, force) with force set to true .

Caller is blocked until mark record is forced to disk.

Parameters:
key - a log key returned by a previous call to put().
Throws:
InvalidLogKeyException
LogClosedException
java.io.IOException
java.lang.InterruptedException
See Also:
mark(long, boolean)

setAutoMark

public void setAutoMark(boolean autoMark)
                 throws InvalidLogKeyException,
                        LogClosedException,
                        LogFileOverflowException,
                        java.io.IOException,
                        java.lang.InterruptedException
Sets the LogFile marking mode.

passes call to LogFileManager

Parameters:
autoMark - true to indicate automatic marking.
Throws:
InvalidLogKeyException
LogClosedException
LogFileOverflowException
java.io.IOException
java.lang.InterruptedException

close

public void close()
           throws java.io.IOException,
                  java.lang.InterruptedException
close the Log files and perform necessary cleanup tasks.

Throws:
java.io.IOException
java.lang.InterruptedException

open

public void open()
          throws InvalidFileSetException,
                 java.io.IOException,
                 LogConfigurationException,
                 InvalidLogBufferException,
                 java.lang.InterruptedException
open Log files and perform necessart initialization. TODO: consider open(String name) to allow named configurations. this would allow utility to open two loggers and copy old records to new files.

Throws:
InvalidFileSetException
java.io.IOException
LogConfigurationException
InvalidLogBufferException
java.lang.InterruptedException

setLogEventListener

public void setLogEventListener(LogEventListener eventListener)
Registers a LogEventListener for log event notifications.

Parameters:
eventListener - object to be notified of logger events.

replay

public void replay(ReplayListener listener,
                   long mark)
            throws InvalidLogKeyException,
                   LogConfigurationException
Replays log from a specified mark forward to the current mark.

Beginning with the record located at mark the Logger reads log records forward to the end of the log. USER records are passed to the listener onRecord() method. When the end of log has been reached, replay returns one final record with a type of END_OF_LOG to inform listener that no further records will be returned.

If an error is encountered while reading the log, the listener onError method is called. Replay terminates when any error occurs and when END_OF_LOG is encountered.

Parameters:
listener - an object that implements ReplayListener interface.
mark - 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:
LogConfigurationException - most likely because the configured LogBuffer class cannot be found.
InvalidLogKeyException - if mark is not a valid log key.

replay

public void replay(ReplayListener listener)
            throws LogConfigurationException
Replays log from the active mark forward to the current position.

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

replay

protected void replay(ReplayListener listener,
                      long mark,
                      boolean replayCtrlRecords)
               throws InvalidLogKeyException,
                      LogConfigurationException
Allows sub-classes of Logger to replay control records.

Parameters:
listener - ReplayListener to receive the records
mark - starting mark (log key) for the replay.
replayCtrlRecords - boolean indicating whether to return CTRL records.
Throws:
InvalidLogKeyException - If the mark parameter specifies an invalid log key (one that does not exist in the current set of log files.)
LogConfigurationException
See Also:
org.objectweb.howl.log.LogBufferManager#replay(ReplayListener, long, boolean)

get

public LogRecord get(LogRecord lr,
                     long mark)
              throws InvalidLogKeyException,
                     LogConfigurationException,
                     LogException,
                     InvalidLogBufferException
Read a specific record from the log.

Control records are not filtered by this method. If the requested mark is valid and identifies a control record, the record will be returned.

Parameters:
lr - LogRecord to be updated or null if caller wishes a new LogRecord to be allocated.
mark - a log key identifying the location of the record within the journal
Returns:
LogRecord containing requested record
Throws:
InvalidLogKeyException - if logkey parameter is < 0L or if the requested key is not within the current range of keys in the log.
LogConfigurationException
LogException
InvalidLogBufferException

getNext

public LogRecord getNext(LogRecord lr)
                  throws InvalidLogBufferException,
                         LogException
Read the journal record that follows the record identified by lr.

Parameters:
lr - LogRecord to be updated with the next journal record.

The LogRecord lr must have been returned by a previous call to Logger.get(LogRecord, long).

Effectively, the record identified by lr is located, and the record immediately following it is returned.

Returns:
LogRecord containing the requested record.
Throws:
java.lang.IllegalArgumentException - if lr parameter is null or if the lr.buffer member is null.
InvalidLogBufferException
LogException

getStats

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

The getStats method for the LogBufferManager and LogFileManager are called to include statistics for these contained objects.

Returns:
String contiining XML node.


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