All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class org.webmacro.util.Log

java.lang.Object
   |
   +----org.webmacro.util.Log

public final class Log
extends Object
The Semiotek Log interface is intended to make logging as simple as possible in order to encourage its use throughout the system. Log messages are categorized two ways : what type/level they are, and what part of the system they come from. The type of the log level ranges from "error" (most severe) to "debug" (least severe). The part of the system is represented by the "class" of the log message--this is an arbitrary string.

The Log class is divided into static methods which are used to control the overall behavior of the logging system, and instance methods which are used to submit log messages to the log.

The expected way to use this class is to create a Log object in a package called "log" and then call it from various points in that package to generate log messages. The "log" object should not be visible beyond the scope of its intended callers.


Variable Index

 o ALL
use with setLevel() to turn on all log messages
 o DEBUG
use with setLevel() to turn off all log messages except ERROR/WARNING/INFO/EXCEPTION/DEBUG
 o debug
Use this variable in your code to decide whether or not to include debug() log messages.
 o ERROR
use with setLevel() to turn off all log messages except ERROR
 o EXCEPTION
use with setLevel() to turn off all log messages except ERROR/WARNING/INFO/EXCEPTION
 o INFO
use with setLevel() to turn off messages other than ERROR/WARNING/INFO
 o NONE
setLevel(Log.NONE) turns off all log messages
 o WARNING
use with setLevel() to turn off all log messages except ERROR/WARNING

Constructor Index

 o Log(String, String)
Create a new log in the specified class.

Method Index

 o debug(Object)
Use to write debugging information to the log.
 o error(Object)
Use to write a log message that indicates a programming error or a system level misconfiguration: for example, unable to locate the config file, etc.
 o exception(Object)
Write a log message that indicates an exceptional condition has occurred.
 o getConstant(int)
Get the log constant that corresponds to the supplied integer.
 o getConstant(String)
Find the constant that matches the supplied string by name.
 o getTypes()
Return an enumeration containing a list of the registered log types
 o getTypesEnabled()
Return an enumeration of the logs types that are currently enabled.
 o info(Object)
Write a log message that simply informs of some interesting events, such as program start up or shut down.
 o logEnable(String[])
Allow printing of only the supplied log types
 o main(String[])
Test harness: opens "log" in the current directory
 o setLevel(Constant)
Log level: what messages to we print out?
 o setTarget(PrintWriter)
Log target: where do we write log messages?
 o setTarget(String)
Log target: set the log to be this file
 o traceExceptions(boolean)
Log includes exception stacktraces
 o warning(Object)
Use to write a log message that indicats suspicious but non-fatal behavior in the program; or else which represents a fatal error that is the fault of data passed to the program.

Variables

 o debug
 public static final boolean debug
Use this variable in your code to decide whether or not to include debug() log messages. A good technique is to use a local variable in your class like this:
final boolean debug = false && Log.debug

See Also:
debug
 o NONE
 public static final Constant NONE
setLevel(Log.NONE) turns off all log messages

 o ERROR
 public static final Constant ERROR
use with setLevel() to turn off all log messages except ERROR

See Also:
error
 o WARNING
 public static final Constant WARNING
use with setLevel() to turn off all log messages except ERROR/WARNING

See Also:
warning
 o INFO
 public static final Constant INFO
use with setLevel() to turn off messages other than ERROR/WARNING/INFO

See Also:
info
 o EXCEPTION
 public static final Constant EXCEPTION
use with setLevel() to turn off all log messages except ERROR/WARNING/INFO/EXCEPTION

See Also:
exception
 o DEBUG
 public static final Constant DEBUG
use with setLevel() to turn off all log messages except ERROR/WARNING/INFO/EXCEPTION/DEBUG

See Also:
debug
 o ALL
 public static final Constant ALL
use with setLevel() to turn on all log messages

Constructors

 o Log
 public Log(String type,
            String description)
Create a new log in the specified class. It is recomended that the type paramter be a word of seven or fewer characters in order to produce a consistent looking log.

Parameters:
type - a single word representing package/category

Methods

 o getConstant
 public static final Constant getConstant(int i)
Get the log constant that corresponds to the supplied integer. If the integer is out of range the closest constant will be returned.

 o getConstant
 public static final Constant getConstant(String name)
Find the constant that matches the supplied string by name. Case is ignored. If the supplied name does not match any constants, then the constant ALL is returned.

 o setLevel
 public static final void setLevel(Constant logLevel)
Log level: what messages to we print out?

Parameters:
logLevelConstant - use one of the log constants defined above
 o setTarget
 public static final void setTarget(PrintWriter target)
Log target: where do we write log messages?

Parameters:
target - the PrintWriter you want to send log messages to
 o setTarget
 public static final void setTarget(String logfile) throws IOException
Log target: set the log to be this file

Parameters:
logfile - the name of a file you want to log messages to
 o traceExceptions
 public static final void traceExceptions(boolean trace)
Log includes exception stacktraces

Parameters:
trace - true if you want exception stacktraces, false otherwise
 o getTypes
 public static final Enumeration getTypes()
Return an enumeration containing a list of the registered log types

 o getTypesEnabled
 public static final Enumeration getTypesEnabled()
Return an enumeration of the logs types that are currently enabled.

 o logEnable
 public static final void logEnable(String types[])
Allow printing of only the supplied log types

 o error
 public final void error(Object logMessage)
Use to write a log message that indicates a programming error or a system level misconfiguration: for example, unable to locate the config file, etc. Error should not be used to indicate an error in data being processed, but rather an error condition that is the fault of the program itself.

 o warning
 public final void warning(Object logMessage)
Use to write a log message that indicats suspicious but non-fatal behavior in the program; or else which represents a fatal error that is the fault of data passed to the program.

 o info
 public final void info(Object logMessage)
Write a log message that simply informs of some interesting events, such as program start up or shut down.

 o exception
 public final void exception(Object logMessage)
Write a log message that indicates an exceptional condition has occurred. It is normal to pass an actual exception in as the object to be logged--if the object passed is actually an exception and stack tracing is enabled, this message will then be able to generate the appropraite stack trace for the Log.

 o debug
 public final void debug(Object logMessage)
Use to write debugging information to the log. This is information that would normally only be of interest to someone trying to discover the actual behavior of the program at runtime.

It is normal to wrap a Log.debug() like this:

 if (Log.debug) { log.debug("debug msg"); } 
 
The "debug" boolean in the Log class can then be toggled on or off in the source, thereby allowing debug statements to be optimized out of the source code at compile time.

 o main
 public static void main(String arg[])
Test harness: opens "log" in the current directory


All Packages  Class Hierarchy  This Package  Previous  Next  Index