Class Logger

  • Direct Known Subclasses:
    XALogger

    public class Logger
    extends 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.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      (package private) LogBufferManager bmgr
      Manages a pool of buffers used for log file IO.
      protected boolean isClosed
      indicates whether the LogFile is open.
      (package private) LogFileManager lfmgr
      Manages a pool of files used for log file IO.
    • Constructor Summary

      Constructors 
      Constructor Description
      Logger()
      Construct a Logger using default Configuration object.
      Logger​(Configuration config)
      Construct a Logger using a Configuration supplied by the caller.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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.

      • lfmgr

        LogFileManager lfmgr
        Manages a pool of files used for log file IO.
    • 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

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