qflib 0.98.1

de.qfs.lib.log
Class Logger

java.lang.Object
  |
  +--de.qfs.lib.log.Logger

public class Logger
extends java.lang.Object

This class simplyfies logging of messages.

It encapsulates the name of its owner and uses it as the sender of the messages it logs. Additionally it provides an advanced scheme to reduce unwanted logging, since logging can get rather expensive in terms of memory and runtime consumption if used seriously.

Typical use of a Logger looks like this:

  // Create the Logger for SomeClass
  private static Logger logger = new Logger (SomeCLass.class);

  public SomeType someMethod (SomeOtherType someParam)
  {
      if (logger.level >= Log.MTD) {
          logger.log (Log.MTD, "someMethod(SomeOtherType)",
                      logger.level < Log.MTDDETAIL ? "" :
                      "someParam: " + someParam);
      }
      ...
 }
 
That way, the log message for the method entry will only be constructed, if logger.level is at least Log.MTD. If it is exactly Log.MTD, no parameters will be added to the log message, if it is higher, the value of someParam will be logged as well.

Note that the Logger's level is not checked in the log methods in order to encourage this style. It cannot be overemphasized: this is the most efficent way to skip unwanted log messages. Nevertheless, for those who value tidy source more than efficient code, the convenience methods err, wrn etc. have been added. These will log a message only if the Logger's level allows it.

The value of logger.level can be customized through the setLogLevel et. al. methods.

Changes in the log levels can be monitored by adding a LogLevelListener via addLogLevelListener.

Version:
$Revision: 1.17 $
Author:
Gregor Schmid
See Also:
Log

Field Summary
static int DEFAULT_LOG_LEVEL
          Default level for a Logger: Log.WRNDETAIL.
 int level
          Log level set indirectly by using setDefaultLogLevel etc.
 
Constructor Summary
Logger(java.lang.Class owner)
          Construct a Logger owned by owner.
Logger(java.lang.Object owner)
          Construct a Logger owned by owner.
Logger(java.lang.String owner)
          Construct a Logger owned by owner.
 
Method Summary
static void addLogLevelListener(LogLevelListener listener)
          Add a LogLevelListener for the log levels.
 void dbg(java.lang.String method, java.lang.String message)
          Log a message at level Log.DBG, if the Logger's level allows it.
 void dbg(java.lang.String method, java.lang.Throwable throwable)
          Log an Exception at level Log.DBG, if the Logger's level allows it.
 void dbg(java.lang.String method, java.lang.Throwable throwable, java.lang.String detail)
          Log an Exception.
 void dumpStack(int level, java.lang.String method, java.lang.String msg)
          Log a stack trace.
 void err(java.lang.String method, java.lang.String message)
          Log a message at level Log.ERR, if the Logger's level allows it.
 void err(java.lang.String method, java.lang.Throwable throwable)
          Log an Exception at level Log.ERR, if the Logger's level allows it.
 void err(java.lang.String method, java.lang.Throwable throwable, java.lang.String detail)
          Log an Exception.
static int getLogLevel(Logger logger)
          Get the level for a Logger.
static java.lang.Object[] getLogLevels()
          Get the current log levels.
 java.lang.String getOwnerName()
          Get the name of the Class owning this Logger.
 void log(int level, java.lang.String method, java.lang.String message)
          Log a message.
 void log(int level, java.lang.String method, java.lang.Throwable throwable)
          Log an Exception at some specified level.
 void log(int level, java.lang.String method, java.lang.Throwable throwable, java.lang.String detail)
          Log an Exception at some specified level.
 void log(java.lang.String method, java.lang.Throwable throwable)
          Log an Exception at leve Log.ERR.
 void log(java.lang.String method, java.lang.Throwable throwable, java.lang.String detail)
          Log an Exception at level Log.ERR.
 void msg(java.lang.String method, java.lang.String message)
          Log a message at level Log.MSG, if the Logger's level allows it.
 void msg(java.lang.String method, java.lang.Throwable throwable)
          Log an Exception at level Log.MSG, if the Logger's level allows it.
 void msg(java.lang.String method, java.lang.Throwable throwable, java.lang.String detail)
          Log an Exception.
 void mtd(java.lang.String method, java.lang.String message)
          Log a message at level Log.MTD, if the Logger's level allows it.
 void mtd(java.lang.String method, java.lang.Throwable throwable)
          Log an Exception at level Log.MTD, if the Logger's level allows it.
 void mtd(java.lang.String method, java.lang.Throwable throwable, java.lang.String detail)
          Log an Exception.
static void removeLogLevel(LogLevelListener source, java.lang.String name)
          Callback method for a LogLevelListener to remove the log level for a class or package.
static void removeLogLevel(java.lang.String name)
          Remove the level that was set for a Class or package so the Class or the package's Classes will now inherit the default log level or a package (part) level.
static void removeLogLevelListener(LogLevelListener listener)
          Remove a LogLevelListener for the log levels.
static void setDefaultLogLevel(int level)
          Set the default level for all Loggers, for which no level is set either directly on the class or on (parts of) its package.
static void setLogLevel(LogLevelListener source, java.lang.String name, int level)
          Callback method for a LogLevelListener to change the log level for a class or package.
static void setLogLevel(java.lang.String name, int level)
          Set the log level for a class or package.
static void setLogLevels(java.util.Hashtable properties)
          Set various levels by parsing a set of properties in a Hashtable.
static void setLogLevels(java.util.ResourceBundle rb)
          Set various levels by parsing a ResourceBundle.
 void wrn(java.lang.String method, java.lang.String message)
          Log a message at level Log.WRN, if the Logger's level allows it.
 void wrn(java.lang.String method, java.lang.Throwable throwable)
          Log an Exception at level Log.WRN, if the Logger's level allows it.
 void wrn(java.lang.String method, java.lang.Throwable throwable, java.lang.String detail)
          Log an Exception.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

level

public int level
Log level set indirectly by using setDefaultLogLevel etc. This attribute should be considered read-only. It is public only to keep the clutter of protecting log calls to a minimum.

DEFAULT_LOG_LEVEL

public static final int DEFAULT_LOG_LEVEL
Default level for a Logger: Log.WRNDETAIL.
Constructor Detail

Logger

public Logger(java.lang.String owner)
Construct a Logger owned by owner.
Parameters:
owner - The name of the owner.

Logger

public Logger(java.lang.Object owner)
Construct a Logger owned by owner.
Parameters:
owner - The owner.

Logger

public Logger(java.lang.Class owner)
Construct a Logger owned by owner.
Parameters:
owner - The class of the owner.
Method Detail

setDefaultLogLevel

public static void setDefaultLogLevel(int level)
Set the default level for all Loggers, for which no level is set either directly on the class or on (parts of) its package. This not only affects future calls to getLogLevel, but also changes the log level of already registered loggers.
Parameters:
level - The new default level.

setLogLevel

public static void setLogLevel(java.lang.String name,
                               int level)
Set the log level for a class or package. If the name represents a package or part of a package it must end with '.' to distinguish it from a class name. Otherwise setting the level for e.g. "de.qfs.lib.log.Log" would implicitly set the level for "de.qfs.lib.log.Logger" as well.
Parameters:
name - The name of the class or package (part). Package names must end with a dot ('.').
level - The maximum level at which objects of the class or classes from the package should log messages.

removeLogLevel

public static void removeLogLevel(java.lang.String name)
Remove the level that was set for a Class or package so the Class or the package's Classes will now inherit the default log level or a package (part) level.
Parameters:
name - The name of the class or package (part). Package names must end with a dot.

getLogLevel

public static int getLogLevel(Logger logger)
Get the level for a Logger. Calling this method will register the Logger requesting the level, so that later changes to the default level, its package's level or explicitly for the class can change the Logger's log level.
Parameters:
logger - The Logger requesting its log level.
Returns:
The log level for the class owning the logger, if it has been explicitly set with setLogLevel, the level of its package or the default level set with setDefaultLogLevel otherwise.

setLogLevels

public static void setLogLevels(java.util.Hashtable properties)
Set various levels by parsing a set of properties in a Hashtable. The Hashtable's keys must be of the form "log-NAME" where "NAME" is the name of a Class or package as required by setLogLevel. The corresponding value must be a String that parses as an int that will be used as the level to set.

Key/value pairs that do not follow these conventions will be silently ignored. Thus for example the system properties may be used to set log levels as follows:

     Logger.setLogLevels(System.getProperties());
 
The default level can be set with the key "log-default".

Parameters:
properties - The Hashtable to parse.

setLogLevels

public static void setLogLevels(java.util.ResourceBundle rb)
Set various levels by parsing a ResourceBundle. The ResourceBundle's names must be of the form "log-NAME" where "NAME" is the name of a Class or package as required by setLogLevel. The corresponding value must parse as an int and will be used as the level to set.

Resources that do not follow these conventions will be silently ignored. The default level can be set with the resource "log-default".

Parameters:
rb - The ResourceBundle to parse.

addLogLevelListener

public static void addLogLevelListener(LogLevelListener listener)
Add a LogLevelListener for the log levels.
Parameters:
listener - The listener to add.

removeLogLevelListener

public static void removeLogLevelListener(LogLevelListener listener)
Remove a LogLevelListener for the log levels.
Parameters:
listener - The listener to remove.

getLogLevels

public static java.lang.Object[] getLogLevels()
Get the current log levels. This method is needed to synchronize the LogLevelListener after initialization.
Returns:
An object array that contains an alternating sequence of class/package names and log levels. The levels are Integers that may be null for classes for which a level has been requested but not explicitly set.

setLogLevel

public static void setLogLevel(LogLevelListener source,
                               java.lang.String name,
                               int level)
Callback method for a LogLevelListener to change the log level for a class or package.
Parameters:
source - The listener that causes the change. It will not be notified to avoid recursion.
name - The name of the affected class or package.
level - The new log level.

removeLogLevel

public static void removeLogLevel(LogLevelListener source,
                                  java.lang.String name)
Callback method for a LogLevelListener to remove the log level for a class or package.
Parameters:
source - The listener that causes the change. It will not be notified to avoid recursion.
name - The name of the affected class or package.

log

public final void log(int level,
                      java.lang.String method,
                      java.lang.String message)
Log a message. The Logger's level is NOT checked.
Parameters:
level - The level of the message.
method - The method that sent the message.
message - The message.

log

public final void log(java.lang.String method,
                      java.lang.Throwable throwable)
Log an Exception at leve Log.ERR. The Logger's level is NOT checked.
Parameters:
method - The method that sent the message.
throwable - The Throwable.

log

public final void log(java.lang.String method,
                      java.lang.Throwable throwable,
                      java.lang.String detail)
Log an Exception at level Log.ERR. The Logger's level is NOT checked.
Parameters:
method - The method that sent the message.
throwable - The Throwable.
detail - Some extra info to log with the Exception name.

log

public final void log(int level,
                      java.lang.String method,
                      java.lang.Throwable throwable)
Log an Exception at some specified level. The Logger's level is NOT checked.
Parameters:
level - The level for the Exception.
method - The method that sent the message.
throwable - The Throwable.

log

public final void log(int level,
                      java.lang.String method,
                      java.lang.Throwable throwable,
                      java.lang.String detail)
Log an Exception at some specified level. The Logger's level is NOT checked.
Parameters:
level - The level for the Exception.
method - The method that sent the message.
throwable - The Throwable.
detail - Some extra info to log with the Exception name.

dumpStack

public void dumpStack(int level,
                      java.lang.String method,
                      java.lang.String msg)
Log a stack trace. The Logger's level is NOT checked.
Parameters:
level - The level to log the stack trace at.
method - The method that sent the message.
msg - The message to log with the stack trace.

err

public final void err(java.lang.String method,
                      java.lang.String message)
Log a message at level Log.ERR, if the Logger's level allows it.
Parameters:
method - The method that sent the message.
message - The message.
Since:
0.98.1

err

public final void err(java.lang.String method,
                      java.lang.Throwable throwable)
Log an Exception at level Log.ERR, if the Logger's level allows it.
Parameters:
method - The method that sent the message.
throwable - The Throwable.
Since:
0.98.1

err

public final void err(java.lang.String method,
                      java.lang.Throwable throwable,
                      java.lang.String detail)
Log an Exception.
Parameters:
method - The method that sent the message.
throwable - The Throwable.
detail - Some extra info to log with the Exception name.
Since:
0.98.1

wrn

public final void wrn(java.lang.String method,
                      java.lang.String message)
Log a message at level Log.WRN, if the Logger's level allows it.
Parameters:
method - The method that sent the message.
message - The message.
Since:
0.98.1

wrn

public final void wrn(java.lang.String method,
                      java.lang.Throwable throwable)
Log an Exception at level Log.WRN, if the Logger's level allows it.
Parameters:
method - The method that sent the message.
throwable - The Throwable.
Since:
0.98.1

wrn

public final void wrn(java.lang.String method,
                      java.lang.Throwable throwable,
                      java.lang.String detail)
Log an Exception.
Parameters:
method - The method that sent the message.
throwable - The Throwable.
detail - Some extra info to log with the Exception name.
Since:
0.98.1

msg

public final void msg(java.lang.String method,
                      java.lang.String message)
Log a message at level Log.MSG, if the Logger's level allows it.
Parameters:
method - The method that sent the message.
message - The message.
Since:
0.98.1

msg

public final void msg(java.lang.String method,
                      java.lang.Throwable throwable)
Log an Exception at level Log.MSG, if the Logger's level allows it.
Parameters:
method - The method that sent the message.
throwable - The Throwable.
Since:
0.98.1

msg

public final void msg(java.lang.String method,
                      java.lang.Throwable throwable,
                      java.lang.String detail)
Log an Exception.
Parameters:
method - The method that sent the message.
throwable - The Throwable.
detail - Some extra info to log with the Exception name.
Since:
0.98.1

mtd

public final void mtd(java.lang.String method,
                      java.lang.String message)
Log a message at level Log.MTD, if the Logger's level allows it.
Parameters:
method - The method that sent the message.
message - The message.
Since:
0.98.1

mtd

public final void mtd(java.lang.String method,
                      java.lang.Throwable throwable)
Log an Exception at level Log.MTD, if the Logger's level allows it.
Parameters:
method - The method that sent the message.
throwable - The Throwable.
Since:
0.98.1

mtd

public final void mtd(java.lang.String method,
                      java.lang.Throwable throwable,
                      java.lang.String detail)
Log an Exception.
Parameters:
method - The method that sent the message.
throwable - The Throwable.
detail - Some extra info to log with the Exception name.
Since:
0.98.1

dbg

public final void dbg(java.lang.String method,
                      java.lang.String message)
Log a message at level Log.DBG, if the Logger's level allows it.
Parameters:
method - The method that sent the message.
message - The message.
Since:
0.98.1

dbg

public final void dbg(java.lang.String method,
                      java.lang.Throwable throwable)
Log an Exception at level Log.DBG, if the Logger's level allows it.
Parameters:
method - The method that sent the message.
throwable - The Throwable.
Since:
0.98.1

dbg

public final void dbg(java.lang.String method,
                      java.lang.Throwable throwable,
                      java.lang.String detail)
Log an Exception.
Parameters:
method - The method that sent the message.
throwable - The Throwable.
detail - Some extra info to log with the Exception name.
Since:
0.98.1

getOwnerName

public java.lang.String getOwnerName()
Get the name of the Class owning this Logger.
Returns:
The owner's name.

qflib 0.98.1