qflib 0.98.0

Package de.qfs.lib.log

This package provides the means for the creation and dispatch of log messages.

See:
          Description

Interface Summary
LogFilter A simple filter that decides, whether a message should be logged or not.
LogFormat Interface for a formatter for LogEntries.
LogLevelCallback Callback that enables access to the log levels of an application as well as the ouput and pre queue levels and the queue and flush buffer parameters.
LogLevelListener Listener interface for changes in the log levels of an application.
LogSource A LogSource passes LogEntries through a chain of LogFilters that can be added to or removed from the LogSource.
LogUser The LogUser interface extends LogFilter for customization.
LogWriter A LogWriter is responsible for the final dispatch of LogEntries after they have passed through the chain of LogFilters.
 

Class Summary
AbstractLogUser This class provides a default implementation of the LogUser interface that reduces the effort of writing a new LogFilter to implementing the isUseful method.
DefaultLogFormat This is a default implementation of the LogFormat interface that produces the same result as the LogEntry.toString method before Version 0.98.0
FileLogWriter An extension of the StreamLogWriter that writes LogEntries to a File.
FlushBuffer.UnitTest Test cases for the FlushBuffer class.
IntTests Integration tests for the log package.
LevelFilter A simple LogFilter that filters messages based on their level.
Log The Log class coordiantes the logging of error and debug messages of different levels of importance.
LogEntry A LogEntry is a container for the elements of a log message.
Logger This class simplyfies logging of messages.
LogLevelEvent LogLevelEvent is used to notify LogLevelListeners of changes in the log levels used by the Loggers of an application.
LogLevels.UnitTest Test cases for the LogLevels class.
LogQueue This is a queue specialized for LogEntries.
LogQueue.UnitTest Test cases for the LogQueue class.
LogStream This stream logs everything written to it.
RingFileLogWriter This class is similar to FileLogWriter but limits the size of the files it writes to.
StreamFilter Deprecated. Replaced by LevelFilter in combination with StreamLogWriter, FileLogWriter or RingFileLogWriter as of version 0.98.0.
StreamLogWriter An implementation of the LogWriter interface that writes LogEntries to a PrintStream or a PrintWriter.
TreeFilter This class filters log messages based on a tree of log levels.
TreeFilter.UnitTest Test cases for the TreeFilter class.
UnitTests Test suite for log package unit testing.
 

Package de.qfs.lib.log Description

This package provides the means for the creation and dispatch of log messages. It is independent of all other qflib packages, so it can be packaged into its own jar and installed seperately, e.g. to reduce download time for applets. It doesn't even depend on the collections package so it can be used from JDK 1.1 Applets without the need for the collections.jar

Logging is especially useful during development and testing since it is an invaluable debugging aid, but also during production runs, where a certain amount of logging is often needed to supervise a program.

There are a few things that have to be considered to get the most out of logging:

All of the above and a little bit more is adressed in the Log and the Logger classes.

The Logger class is responsible for generating log messages as well as for suppressing that generation, while the Log class is responsible for filtering and dispatching log messages.

Log messages can be redirected to a log file with the help of the FileLogWriter class or sent to a separate LogServer process with a RemoteLogWriter.

Typical use of the log package looks like this:

import de.qfs.lib.Log;
import de.qfs.lib.Logger;

class SomeClass
{
    // Initialize the logger for SomeClass
    private final static Logger logger = new Logger (SomeClass.class);


    public void someMethod(int someParameter)
    {
        // log entry to the method, optionally with parameters
        if (logger.level >= Log.MTD) {
	    logger.log(Log.MTD, "someMethod(int)",
	               logger.level < Log.MTDDETAIL ? "" :
		       "someParameter: " + someParameter);
        }
	...

	// some debugging output
        if (logger.level >= Log.DBG) {
	    logger.log(Log.DBG, "someMethod(int)",
                       "Some debug message");
        }
	...

	try {
	    // do something dangerous
	    ...

	} catch (BadException ex) {
	    // log exception at error level
	    if (logger.level >= Log.ERR) {
		logger.log("someMethod(int)", ex);
	    }
	} catch (NotSoBadException ex) {
	    // log exception at warning level
	    if (logger.level >= Log.WRN) {
		logger.log(Log.WRN, "someMethod(int)", ex);
	    }
	}
    }
}
While the above may look overly complicated, it's not that bad if you consider the benefits: With the use of the remote log server qflog, log messages can be viewed, sorted, filtered etc., and the levels of the Loggers relevant for the creation of the messages can be tuned at runtime.


qflib 0.98.0