Class Logger
- Direct Known Subclasses:
XALogger
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
FieldsModifier and TypeFieldDescription(package private) LogBufferManager
Manages a pool of buffers used for log file IO.protected boolean
indicates whether the LogFile is open.(package private) LogFileManager
Manages a pool of files used for log file IO. -
Constructor Summary
ConstructorsConstructorDescriptionLogger()
Construct a Logger using default Configuration object.Logger
(Configuration config) Construct a Logger using a Configuration supplied by the caller. -
Method Summary
Modifier and TypeMethodDescriptionvoid
close()
close the Log files and perform necessary cleanup tasks.Read a specific record from the log.long
Read the journal record that follows the record identified by lr.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.
-
Field Details
-
isClosed
protected volatile boolean isClosedindicates whether the LogFile is open.Logger methods return LogClosedException when log is closed.
-
bmgr
LogBufferManager bmgrManages a pool of buffers used for log file IO. -
lfmgr
LogFileManager lfmgrManages a pool of files used for log file IO.
-
-
Constructor Details
-
Logger
Construct a Logger using default Configuration object.- Throws:
IOException
-
Logger
Construct a Logger using a Configuration supplied by the caller.- Parameters:
config
- Configuration object- Throws:
IOException
-
-
Method Details
-
getActiveMark
public long getActiveMark()- Returns:
- activeMark member of the associated LogFileManager.
-
put
public long put(byte[][] data, boolean sync) throws LogClosedException, LogRecordSizeException, LogFileOverflowException, InterruptedException, 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 datasync
- 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
InterruptedException
IOException
- See Also:
-
put
public long put(byte[] data, boolean sync) throws LogClosedException, LogRecordSizeException, LogFileOverflowException, InterruptedException, 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 logsync
- true if caller wishes to block waiting for the record to force to disk.- Returns:
- log key for the record
- Throws:
LogClosedException
LogRecordSizeException
LogFileOverflowException
InterruptedException
IOException
-
put
protected long put(short type, byte[][] data, boolean sync) throws LogClosedException, LogRecordSizeException, LogFileOverflowException, InterruptedException, 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
InterruptedException
IOException
-
mark
public void mark(long key, boolean force) throws InvalidLogKeyException, LogClosedException, IOException, 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.IOException
InterruptedException
-
mark
public void mark(long key) throws InvalidLogKeyException, LogClosedException, IOException, 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
IOException
InterruptedException
- See Also:
-
setAutoMark
public void setAutoMark(boolean autoMark) throws InvalidLogKeyException, LogClosedException, LogFileOverflowException, IOException, InterruptedException Sets the LogFile marking mode.passes call to LogFileManager
- Parameters:
autoMark
- true to indicate automatic marking.- Throws:
InvalidLogKeyException
LogClosedException
LogFileOverflowException
IOException
InterruptedException
-
close
close the Log files and perform necessary cleanup tasks.- Throws:
IOException
InterruptedException
-
open
public void open() throws InvalidFileSetException, IOException, LogConfigurationException, InvalidLogBufferException, InterruptedExceptionopen 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. -
setLogEventListener
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
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
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 recordsmark
- 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:
-
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 invalid input: '<' 0L or if the requested key is not within the current range of keys in the log.LogConfigurationException
LogException
InvalidLogBufferException
-
getNext
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:
IllegalArgumentException
- if lr parameter is null or if the lr.buffer member is null.InvalidLogBufferException
LogException
-
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.
-