org.zkoss.util.logging
Class Log

java.lang.Object
  extended by org.zkoss.util.logging.Log

public class Log
extends java.lang.Object

The logger. Usage:

private static final Log log = Log.lookup(MyClass.class);
...
if (log.debugable()) log.debug("the information to log:"+some);

Log is designed to minimize the memory usage by avoiding unnecessary allocation of java.util.logging.Logger. In additions, it is possible to use different logger, e.g., log4j, without affecting the client codes.

Since this object is very light-weight, it is OK to have the following statement without using it.
private static final Log log = Log.lookup(MyClass.class);

To log error or warning, simple use the error and warning method.

To log info, depending on the complexity you might want to test infoable first.

log.info("a simple info");
if (log.infoable())
  log.info(a + complex + string + operation);

To log debug information, we usually also test with D.

log.debug("a simple info");
if (log.debugable())
  log.debug(a + complex + string + operation);

There is a special level called FINER whose priority is lower than DEBUG. It is generally used to log massive debug message under certain situation. In other words, it is suggested to use the debug methods to log messages as follows:

if (log.finerable()) {
  ... do massive testing and/or printing (use finer)
}

Author:
tomyeh

Field Summary
static java.util.logging.Level ALL
          All levels.
static java.util.logging.Level DEBUG
          The DEBUG level.
static java.util.logging.Level ERROR
          The ERROR level.
static java.util.logging.Level FINER
          The FINER level.
static java.util.logging.Level INFO
          The INFO level.
static java.util.logging.Level OFF
          The OFF level used to turn of the logging.
static java.util.logging.Level WARNING
          The WARNING level.
 
Constructor Summary
protected Log(java.lang.String name)
          The constructor.
 
Method Summary
static void configure(java.util.Properties props)
          Configures based the properties.
 void debug(int code)
          Logs a debug message by giving message code.
 void debug(int code, java.lang.Object fmtArg)
          Logs a debug message by giving message code.
 void debug(int code, java.lang.Object[] fmtArgs)
          Logs a debug message by giving message code.
 void debug(int code, java.lang.Object[] fmtArgs, java.lang.Throwable t)
          Logs a debug message and a throwable object by giving message code.
 void debug(int code, java.lang.Object fmtArg, java.lang.Throwable t)
          Logs a debug message and a throwable object by giving message code.
 void debug(int code, java.lang.Throwable t)
          Logs a debug message and a throwable object by giving message code.
 void debug(java.lang.Object obj)
          Logs an object, whose toString returns the debug message.
 void debug(java.lang.Object obj, java.lang.Throwable t)
          Logs an object, whose toString returns the debug message, and a throwable object.
 void debug(java.lang.String msg)
          Logs a debug message.
 void debug(java.lang.String format, java.lang.Object... args)
          Logs a debug message with a format and arguments.
 void debug(java.lang.String msg, java.lang.Throwable t)
          Logs a debug message and a throwable object.
 void debug(java.lang.Throwable t)
          Logs a debug throwable object.
 boolean debugable()
          Tests whether the DEBUG level is loggable.
 void eat(java.lang.String message, java.lang.Throwable ex)
          Logs an exception as an warning message about being eaten (rather than thrown).
 void eat(java.lang.Throwable ex)
          Logs an exception as an warning message about being eaten (rather than thrown).
 boolean equals(java.lang.Object o)
           
 void error(int code)
          Logs an error message by giving message code.
 void error(int code, java.lang.Object fmtArg)
          Logs an error message by giving message code.
 void error(int code, java.lang.Object[] fmtArgs)
          Logs an error message by giving message code.
 void error(int code, java.lang.Object[] fmtArgs, java.lang.Throwable t)
          Logs an error message and a throwable object by giving message code.
 void error(int code, java.lang.Object fmtArg, java.lang.Throwable t)
          Logs an error message and a throwable object by giving message code.
 void error(int code, java.lang.Throwable t)
          Logs an error message and a throwable object by giving message code.
 void error(java.lang.Object obj)
          Logs an object, whose toString returns the error message.
 void error(java.lang.Object obj, java.lang.Throwable t)
          Logs an object, whose toString returns the error message, and a throwable object.
 void error(java.lang.String msg)
          Logs an error message.
 void error(java.lang.String format, java.lang.Object... args)
          Logs a debug message with a format and arguments.
 void error(java.lang.String msg, java.lang.Throwable t)
          Logs an error message and a throwable object.
 void error(java.lang.Throwable t)
          Logs an error throwable object.
 boolean errorable()
          Tests whether the ERROR level is loggable.
 void finer(int code)
          Logs a finer message by giving message code.
 void finer(int code, java.lang.Object fmtArg)
          Logs a finer message by giving message code.
 void finer(int code, java.lang.Object[] fmtArgs)
          Logs a finer message by giving message code.
 void finer(int code, java.lang.Object[] fmtArgs, java.lang.Throwable t)
          Logs a finer message and a throwable object by giving message code.
 void finer(int code, java.lang.Object fmtArg, java.lang.Throwable t)
          Logs a finer message and a throwable object by giving message code.
 void finer(int code, java.lang.Throwable t)
          Logs a finer message and a throwable object by giving message code.
 void finer(java.lang.Object obj)
          Logs an object, whose toString returns the finer message.
 void finer(java.lang.Object obj, java.lang.Throwable t)
          Logs an object, whose toString returns the finer message, and a throwable object.
 void finer(java.lang.String msg)
          Logs a finer message.
 void finer(java.lang.String format, java.lang.Object... args)
          Logs a finer message with a format and arguments.
 void finer(java.lang.String msg, java.lang.Throwable t)
          Logs a finer message and a throwable object.
 void finer(java.lang.Throwable t)
          Logs a finer throwable object.
 boolean finerable()
          Tests whether the FINER level is loggable.
 java.util.logging.Level getLevel()
          Returns the logging level.
static java.util.logging.Level getLevel(java.lang.String level)
          Return the logging level of the specified string.
 java.lang.String getName()
          Returns the name of this logger.
 int hashCode()
           
 void info(int code)
          Logs an info message by giving message code.
 void info(int code, java.lang.Object fmtArg)
          Logs an info message by giving message code.
 void info(int code, java.lang.Object[] fmtArgs)
          Logs an info message by giving message code.
 void info(int code, java.lang.Object[] fmtArgs, java.lang.Throwable t)
          Logs an info message and a throwable object by giving message code.
 void info(int code, java.lang.Object fmtArg, java.lang.Throwable t)
          Logs an info message and a throwable object by giving message code.
 void info(int code, java.lang.Throwable t)
          Logs an info message and a throwable object by giving message code.
 void info(java.lang.Object obj)
          Logs an object, whose toString returns the info message.
 void info(java.lang.Object obj, java.lang.Throwable t)
          Logs an object, whose toString returns the info message, and a throwable object.
 void info(java.lang.String msg)
          Logs an info message.
 void info(java.lang.String format, java.lang.Object... args)
          Logs an info message with a format and arguments.
 void info(java.lang.String msg, java.lang.Throwable t)
          Logs an info message and a throwable object.
 void info(java.lang.Throwable t)
          Logs an info throwable object.
 boolean infoable()
          Tests whether the INFO level is loggable.
static boolean isHierarchy()
          Returns whether the loggers support hierarchy.
 void log(java.util.logging.Level level, int code, java.lang.Object[] fmtArgs, java.lang.Throwable t)
          Logs a message and a throwable object at the giving level by giving a message code and multiple format arguments.
 void log(java.util.logging.Level level, int code, java.lang.Object fmtArg, java.lang.Throwable t)
          Logs a message and a throwable object at the giving level by giving a message code and ONE format argument.
 void log(java.util.logging.Level level, int code, java.lang.Throwable t)
          Logs a message and a throwable object at the giving level by giving a message code and NO format argument.
 void log(java.util.logging.Level level, java.lang.Object obj, java.lang.Throwable t)
          Logs any object and a throwable object at the giving level.
 void log(java.util.logging.Level level, java.lang.String msg, java.lang.Throwable t)
          Logs a message and a throwable object at the giving level.
static Log lookup(java.lang.Class cls)
          Gets the logger based on the class.
static Log lookup(java.lang.Package pkg)
          Gets the logger based on the package.
static Log lookup(java.lang.String name)
          Gets the logger based on the giving name.
 void realCause(java.lang.String message, java.lang.Throwable ex)
          Logs only the real cause of the specified exception with an extra message as an error message.
 void realCause(java.lang.Throwable ex)
          Logs only the real cause of the specified exception.
 void realCauseBriefly(java.lang.String message, java.lang.Throwable ex)
          Logs only the first few lines of the real cause as an error message.
 void realCauseBriefly(java.lang.Throwable ex)
          Logs only the first few lines of the real cause as an error message.
static void setHierarchy(boolean hierarchy)
          Sets whether to support the hierarchical loggers.
 void setLevel(java.util.logging.Level level)
          Sets the logging level.
 void setLevel(java.lang.String level)
          Sets the logging level.
 java.lang.String toString()
           
 void warning(int code)
          Logs a warning message by giving message code.
 void warning(int code, java.lang.Object fmtArg)
          Logs a warning message by giving message code.
 void warning(int code, java.lang.Object[] fmtArgs)
          Logs a warning message by giving message code.
 void warning(int code, java.lang.Object[] fmtArgs, java.lang.Throwable t)
          Logs a warning message and a throwable object by giving message code.
 void warning(int code, java.lang.Object fmtArg, java.lang.Throwable t)
          Logs a warning message and a throwable object by giving message code.
 void warning(int code, java.lang.Throwable t)
          Logs a warning message and a throwable object by giving message code.
 void warning(java.lang.Object obj)
          Logs an object, whose toString returns the warning message.
 void warning(java.lang.Object obj, java.lang.Throwable t)
          Logs an object, whose toString returns the warning message, and a throwable object.
 void warning(java.lang.String msg)
          Logs a warning message.
 void warning(java.lang.String format, java.lang.Object... args)
          Logs a warning message with a format and arguments.
 void warning(java.lang.String msg, java.lang.Throwable t)
          Logs a warning message and a throwable object.
 void warning(java.lang.Throwable t)
          Logs a warning throwable object.
 boolean warningable()
          Tests whether the WARNING level is loggable.
 void warningBriefly(java.lang.String message, java.lang.Throwable ex)
          Logs only the first few lines of the real cause as an warning message.
 void warningBriefly(java.lang.Throwable ex)
          Lo only the first few lines of the real cause.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

ALL

public static final java.util.logging.Level ALL
All levels.


ERROR

public static final java.util.logging.Level ERROR
The ERROR level.


WARNING

public static final java.util.logging.Level WARNING
The WARNING level.


INFO

public static final java.util.logging.Level INFO
The INFO level.


DEBUG

public static final java.util.logging.Level DEBUG
The DEBUG level.


FINER

public static final java.util.logging.Level FINER
The FINER level.


OFF

public static final java.util.logging.Level OFF
The OFF level used to turn of the logging.

Constructor Detail

Log

protected Log(java.lang.String name)
The constructor.

Method Detail

configure

public static final void configure(java.util.Properties props)
Configures based the properties.

The key is a logger name and the value is the level.

Parameters:
props - the properties
Since:
6.0.0

isHierarchy

public static final boolean isHierarchy()
Returns whether the loggers support hierarchy. If hierarchy is supported, a Log instance is mapped to a Logger instance with the same name. Therefore, it forms the hierarchical relationship among Logger instances. It has the best resolution to control which logger to enable.

On the other hand, if the loggers don't support hierarchy, all Log instances are actually mapped to the same Logger called "org.zkoss". The performance is better in this mode.

Default: false.

Note: configure(java.util.Properties) will invoke setHierarchy(boolean) with true automatically to turn on the hierarchy support, if any level is defined.


setHierarchy

public static final void setHierarchy(boolean hierarchy)
Sets whether to support the hierarchical loggers.


lookup

public static final Log lookup(java.lang.Class cls)
Gets the logger based on the class.

Parameters:
cls - the class that identifies the logger.

lookup

public static final Log lookup(java.lang.String name)
Gets the logger based on the giving name.

Since 5.0.7, this constructor, unlike others, ignores isHierarchy() and always assumes the hierarchy name. Notice the hierarchy is always disabled if a library property called org.zkoss.util.logging.hierarchy.disabled is set to true.


lookup

public static final Log lookup(java.lang.Package pkg)
Gets the logger based on the package.


getName

public final java.lang.String getName()
Returns the name of this logger.


getLevel

public final java.util.logging.Level getLevel()
Returns the logging level.


setLevel

public final void setLevel(java.util.logging.Level level)
Sets the logging level.


setLevel

public final void setLevel(java.lang.String level)
Sets the logging level.

Since:
5.0.7

getLevel

public static final java.util.logging.Level getLevel(java.lang.String level)
Return the logging level of the specified string.

Returns:
the level; null if no match at all

errorable

public final boolean errorable()
Tests whether the ERROR level is loggable.


warningable

public final boolean warningable()
Tests whether the WARNING level is loggable.


infoable

public final boolean infoable()
Tests whether the INFO level is loggable.


debugable

public final boolean debugable()
Tests whether the DEBUG level is loggable.


finerable

public final boolean finerable()
Tests whether the FINER level is loggable.


log

public final void log(java.util.logging.Level level,
                      java.lang.String msg,
                      java.lang.Throwable t)
Logs a message and a throwable object at the giving level.

All log methods eventually invokes this method to log messages.

Parameters:
t - the throwable object; null to ignore

log

public final void log(java.util.logging.Level level,
                      java.lang.Object obj,
                      java.lang.Throwable t)
Logs any object and a throwable object at the giving level.

Parameters:
obj - the object whose toString method is called to get the message

log

public final void log(java.util.logging.Level level,
                      int code,
                      java.lang.Object[] fmtArgs,
                      java.lang.Throwable t)
Logs a message and a throwable object at the giving level by giving a message code and multiple format arguments.

Parameters:
t - the throwable object; null to ignore

log

public final void log(java.util.logging.Level level,
                      int code,
                      java.lang.Object fmtArg,
                      java.lang.Throwable t)
Logs a message and a throwable object at the giving level by giving a message code and ONE format argument.

Parameters:
t - the throwable object; null to ignore

log

public final void log(java.util.logging.Level level,
                      int code,
                      java.lang.Throwable t)
Logs a message and a throwable object at the giving level by giving a message code and NO format argument.

Parameters:
t - the throwable object; null to ignore

error

public void error(java.lang.String format,
                  java.lang.Object... args)
Logs a debug message with a format and arguments. The message is formatted by use of String.format.

Since:
6.0.0

error

public final void error(java.lang.String msg,
                        java.lang.Throwable t)
Logs an error message and a throwable object.

See Also:
errorable()

error

public final void error(java.lang.String msg)
Logs an error message.


error

public final void error(java.lang.Object obj,
                        java.lang.Throwable t)
Logs an object, whose toString returns the error message, and a throwable object.

Parameters:
obj - the object whose toString method is called to get the message

error

public final void error(java.lang.Object obj)
Logs an object, whose toString returns the error message.

Parameters:
obj - the object whose toString method is called to get the message

error

public final void error(java.lang.Throwable t)
Logs an error throwable object.


error

public final void error(int code,
                        java.lang.Object[] fmtArgs,
                        java.lang.Throwable t)
Logs an error message and a throwable object by giving message code.


error

public final void error(int code,
                        java.lang.Object fmtArg,
                        java.lang.Throwable t)
Logs an error message and a throwable object by giving message code.


error

public final void error(int code,
                        java.lang.Throwable t)
Logs an error message and a throwable object by giving message code.


error

public final void error(int code,
                        java.lang.Object[] fmtArgs)
Logs an error message by giving message code.


error

public final void error(int code,
                        java.lang.Object fmtArg)
Logs an error message by giving message code.


error

public final void error(int code)
Logs an error message by giving message code.


warning

public void warning(java.lang.String format,
                    java.lang.Object... args)
Logs a warning message with a format and arguments. The message is formatted by use of String.format.

Since:
6.0.0

warning

public final void warning(java.lang.String msg,
                          java.lang.Throwable t)
Logs a warning message and a throwable object.

See Also:
warningable()

warning

public final void warning(java.lang.String msg)
Logs a warning message.


warning

public final void warning(java.lang.Object obj,
                          java.lang.Throwable t)
Logs an object, whose toString returns the warning message, and a throwable object.

Parameters:
obj - the object whose toString method is called to get the message

warning

public final void warning(java.lang.Object obj)
Logs an object, whose toString returns the warning message.

Parameters:
obj - the object whose toString method is called to get the message

warning

public final void warning(java.lang.Throwable t)
Logs a warning throwable object.


warning

public final void warning(int code,
                          java.lang.Object[] fmtArgs,
                          java.lang.Throwable t)
Logs a warning message and a throwable object by giving message code.


warning

public final void warning(int code,
                          java.lang.Object fmtArg,
                          java.lang.Throwable t)
Logs a warning message and a throwable object by giving message code.


warning

public final void warning(int code,
                          java.lang.Throwable t)
Logs a warning message and a throwable object by giving message code.


warning

public final void warning(int code,
                          java.lang.Object[] fmtArgs)
Logs a warning message by giving message code.


warning

public final void warning(int code,
                          java.lang.Object fmtArg)
Logs a warning message by giving message code.


warning

public final void warning(int code)
Logs a warning message by giving message code.


info

public void info(java.lang.String format,
                 java.lang.Object... args)
Logs an info message with a format and arguments. The message is formatted by use of String.format.

Since:
6.0.0

info

public final void info(java.lang.String msg,
                       java.lang.Throwable t)
Logs an info message and a throwable object.

See Also:
infoable()

info

public final void info(java.lang.String msg)
Logs an info message.


info

public final void info(java.lang.Object obj,
                       java.lang.Throwable t)
Logs an object, whose toString returns the info message, and a throwable object.

Parameters:
obj - the object whose toString method is called to get the message

info

public final void info(java.lang.Object obj)
Logs an object, whose toString returns the info message.

Parameters:
obj - the object whose toString method is called to get the message

info

public final void info(java.lang.Throwable t)
Logs an info throwable object.


info

public final void info(int code,
                       java.lang.Object[] fmtArgs,
                       java.lang.Throwable t)
Logs an info message and a throwable object by giving message code.


info

public final void info(int code,
                       java.lang.Object fmtArg,
                       java.lang.Throwable t)
Logs an info message and a throwable object by giving message code.


info

public final void info(int code,
                       java.lang.Throwable t)
Logs an info message and a throwable object by giving message code.


info

public final void info(int code,
                       java.lang.Object[] fmtArgs)
Logs an info message by giving message code.


info

public final void info(int code,
                       java.lang.Object fmtArg)
Logs an info message by giving message code.


info

public final void info(int code)
Logs an info message by giving message code.


debug

public void debug(java.lang.String format,
                  java.lang.Object... args)
Logs a debug message with a format and arguments. The message is formatted by use of String.format.

Since:
6.0.0

debug

public final void debug(java.lang.String msg,
                        java.lang.Throwable t)
Logs a debug message and a throwable object.

Since:
#debugable

debug

public final void debug(java.lang.String msg)
Logs a debug message.


debug

public final void debug(java.lang.Object obj,
                        java.lang.Throwable t)
Logs an object, whose toString returns the debug message, and a throwable object.

Parameters:
obj - the object whose toString method is called to get the message

debug

public final void debug(java.lang.Object obj)
Logs an object, whose toString returns the debug message.

Parameters:
obj - the object whose toString method is called to get the message

debug

public final void debug(java.lang.Throwable t)
Logs a debug throwable object.


debug

public final void debug(int code,
                        java.lang.Object[] fmtArgs,
                        java.lang.Throwable t)
Logs a debug message and a throwable object by giving message code.


debug

public final void debug(int code,
                        java.lang.Object fmtArg,
                        java.lang.Throwable t)
Logs a debug message and a throwable object by giving message code.


debug

public final void debug(int code,
                        java.lang.Throwable t)
Logs a debug message and a throwable object by giving message code.


debug

public final void debug(int code,
                        java.lang.Object[] fmtArgs)
Logs a debug message by giving message code.


debug

public final void debug(int code,
                        java.lang.Object fmtArg)
Logs a debug message by giving message code.


debug

public final void debug(int code)
Logs a debug message by giving message code.


finer

public void finer(java.lang.String format,
                  java.lang.Object... args)
Logs a finer message with a format and arguments. The message is formatted by use of String.format.

Since:
6.0.0

finer

public final void finer(java.lang.String msg,
                        java.lang.Throwable t)
Logs a finer message and a throwable object.


finer

public final void finer(java.lang.String msg)
Logs a finer message.


finer

public final void finer(java.lang.Object obj,
                        java.lang.Throwable t)
Logs an object, whose toString returns the finer message, and a throwable object.

Parameters:
obj - the object whose toString method is called to get the message

finer

public final void finer(java.lang.Object obj)
Logs an object, whose toString returns the finer message.

Parameters:
obj - the object whose toString method is called to get the message

finer

public final void finer(java.lang.Throwable t)
Logs a finer throwable object.


finer

public final void finer(int code,
                        java.lang.Object[] fmtArgs,
                        java.lang.Throwable t)
Logs a finer message and a throwable object by giving message code.


finer

public final void finer(int code,
                        java.lang.Object fmtArg,
                        java.lang.Throwable t)
Logs a finer message and a throwable object by giving message code.


finer

public final void finer(int code,
                        java.lang.Throwable t)
Logs a finer message and a throwable object by giving message code.


finer

public final void finer(int code,
                        java.lang.Object[] fmtArgs)
Logs a finer message by giving message code.


finer

public final void finer(int code,
                        java.lang.Object fmtArg)
Logs a finer message by giving message code.


finer

public final void finer(int code)
Logs a finer message by giving message code.


realCause

public final void realCause(java.lang.Throwable ex)
Logs only the real cause of the specified exception. It is useful because sometimes the stack trace is too big.


realCause

public final void realCause(java.lang.String message,
                            java.lang.Throwable ex)
Logs only the real cause of the specified exception with an extra message as an error message.


realCauseBriefly

public final void realCauseBriefly(java.lang.String message,
                                   java.lang.Throwable ex)
Logs only the first few lines of the real cause as an error message.

To control the number of lines to log, you can specify a library property called org.zkoss.util.logging.realCauseBriefly.lines. If not specified, 6 is assumed. If nonpositive is specified, the full stack traces are logged.

Notice that # of lines don't include packages starting with java, javax or sun.


realCauseBriefly

public final void realCauseBriefly(java.lang.Throwable ex)
Logs only the first few lines of the real cause as an error message.


warningBriefly

public final void warningBriefly(java.lang.String message,
                                 java.lang.Throwable ex)
Logs only the first few lines of the real cause as an warning message.

To control the number of lines to log, you can specify a library property called org.zkoss.util.logging.warningBriefly.lines. If not specified, 3 is assumed. If nonpositive is specified, the full stack traces are logged.

Notice that # of lines don't include packages starting with java, javax or sun.


warningBriefly

public final void warningBriefly(java.lang.Throwable ex)
Lo only the first few lines of the real cause.


eat

public final void eat(java.lang.String message,
                      java.lang.Throwable ex)
Logs an exception as an warning message about being eaten (rather than thrown).


eat

public final void eat(java.lang.Throwable ex)
Logs an exception as an warning message about being eaten (rather than thrown).


hashCode

public int hashCode()
Overrides:
hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object o)
Overrides:
equals in class java.lang.Object

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object


Copyright © 2005-2011 Potix Corporation. All Rights Reserved. SourceForge.net Logo