com.bristle.javalib.log
Class Logger

java.lang.Object
  com.bristle.javalib.log.Logger

public class Logger
extends Object

This class handles logging of messages to one or more Logger.LoggerTargets (XML DOM, file, Writer, ServletContext, etc.)

Usage:
   - The typical scenario for using this class is:

     - To log to an XML DOM:
           Logger logger = new Logger();
           logger.addTarget(new XMLDOMLoggerTarget(xmlDOM));
           logger.setLogLevel(2);
           logger.log(1, "Line of text to write to the log.");

     - To log to a file:
           Logger logger = new Logger();
           logger.addTarget(new Logger.FilenameLoggerTarget("/my/log/file"));
           logger.setLogLevel(2);
           logger.log(1, "Line of text to write to the log.");

     - To log to a Writer:
           Logger logger = new Logger();
           logger.addTarget(new Logger.WriterLoggerTarget(writer));
           logger.setLogLevel(2);
           logger.log(1, "Line of text to write to the log.");

     - To log to a ServletContext:
           Logger logger = new Logger();
           logger.addTarget(new ServletContextLoggerTarget(objServletContext));
           logger.setLogLevel(2);
           logger.log(1, "Line of text to write to the log.");

     - To log to multiple targets:
           Logger logger = new Logger();
           logger.addTarget(new XMLDOMLoggerTarget(xmlDOM));
           logger.addTarget(new XMLDOMLoggerTarget(xmlDOM2));
           ...
           logger.addTarget(new Logger.FilenameLoggerTarget("/my/log/file"));
           logger.addTarget(new Logger.FilenameLoggerTarget("/my/log/file2"));
           ...
           logger.addTarget(new Logger.WriterLoggerTarget(writer));
           logger.addTarget(new Logger.WriterLoggerTarget(writer2));
           ...
           logger.addTarget(new ServletContextLoggerTarget(objServletContext));
           logger.addTarget(new ServletContextLoggerTarget(objServletContext2));
           ...
           logger.setLogLevel(2);
           logger.log(1, "Line of text to write to the logs.");

     - To log to System.out:
           Logger logger = new Logger();
           logger.addTarget(new Logger.WriterLoggerTarget
                                       (new PrintWriter(System.out)));
           logger.setLogLevel(2);
           logger.log(1, "Line of text to write to the log.");

   - There is also support for logging in cases where no error can be 
     tolerated.  For example:

     - To log a message without risk of causing an error, even if the 
       local variable "logger" is null:
           Logger.logSafely(logger, 1, "Line of text to write to the log.");

     - To log an error message without risk of causing another error, even
       if the local variable "logger" is null:
           Logger.logErrorSafely(logger, 1, "An error occurred:", exception);

   - There is also support for using the Logger in cases where the code
     that sets up the Logger is not able to pass the Logger object to 
     other code that must use it.  The startup code sets the Logger's
     internal "singleton", which can be used by other parts of the code
     via the static methods of the Logger.  For example:

     - To set up the Logger's singleton, after configuring it in any of 
       the ways shown above:
           Logger.setSingleton(logger);

     - To use the already configured singleton Logger to log a message: 
           Logger.logSafely(1, "Line of text to write to the log.");

     - To use the already configured singleton Logger to log an error message: 
           Logger.logErrorSafely(1, "An error occurred:", exception);

     - To modify the configuration of the singleton Logger:
           Logger.getSingleton().setLogLevel(9);

   - See the source code of the inner Tester class for more examples.
  
Assumptions:
Effects:

Writes log entries to one or more LoggerTargets, typically in the format (all one one line): 2007/02/16 18:14:25.274 Fri MyApp v1.0 fred [Thread-12] 1171667665274 23510888 27770872 1 This is a sample log message. Where the parts are: <DateTime> is the current date and time on the server in format: yyyy/MM/dd HH:mm:ss.SSS EEE For example: 2007/12/31 23:59:59.999 Mon <AppName> is the name of the application that called the logger. <AppVersion> is the version string of the application. <Username> is the name of the current user. <ThreadName> is the name of the current thread. <Millisecs> is the current time in milliseconds on the server. <UsedMem> is the current number of bytes of used memory in the JVM of the Web Server. <TotalMem> is the current number of bytes of total memory in the JVM of the Web Server. <Level> indicates the logging level of the message. Can be used as an indentation level to format the messages. <Msg> is the text of the message.

Anticipated Changes:
Notes:
Implementation Notes:
Portability Issues:
Revision History:
   $Log$

See Also:

XMLDOMLoggerTarget, ServletContextLoggerTarget

Nested Class Summary

static class	Logger.Entry This class represents a log entry that can be sent by a Logger to a LoggerTarget.
static class	Logger.FilenameLoggerTarget This class implements the LoggerTarget interface, writing log entries to a named text file.
static interface	Logger.LoggerTarget This interface must be implemented by any class that expects to be called by the Logger class to log entries to a target (XML DOM, file, Writer, ServletContext, etc.)
static class	Logger.Tester Each class contains a Tester inner class with a main() for easier unit testing.
static class	Logger.WriterLoggerTarget This class implements the LoggerTarget interface, writing log entries to a Writer.

Field Summary

private ArrayList	m_alTargets
private int	m_intLogLevel
private String	m_strAppName
private String	m_strAppVersion
private String	m_strUsername
private static Logger	st_loggerSingleton

Constructor Summary

Logger()

Method Summary

void	addTarget(Logger.LoggerTarget target) Add to the list of LoggerTargets to which logging is done.
String	getAppName() Get the application name.
String	getAppVersion() Get the application version.
int	getLogLevel() Get the log level.
static Logger	getSingleton() Get the singleton Logger, if any.
String	getUsername() Get the username.
void	log(int intLogLevel, String strMsg) Log a message to the various LoggerTargets.
static void	logErrorSafely(int intLogLevel, String strMsg, Throwable e) Log an error message via the singleton Logger, suppressing all possible errors, even the error of having a null value for the singleton Logger.
static void	logErrorSafely(Logger logger, int intLogLevel, String strMsg, Throwable e) Log an error message, suppressing all possible errors, even the error of passing a null value for logger.
static void	logSafely(int intLogLevel, String strMsg) Log a message via the singleton Logger, suppressing all possible errors, even the error of having a null value for the singleton Logger.
static void	logSafely(Logger logger, int intLogLevel, String strMsg) Log a message, suppressing all possible errors, even the error of passing a null value for logger.
void	setAppName(String strNew) Set the application name to be recorded in log entries.
void	setAppVersion(String strNew) Set the application version to be recorded in log entries.
void	setLogLevel(int intNew) Set the log level.
static void	setSingleton(Logger logger) Set the singleton Logger.
void	setUsername(String strNew) Set the username to be recorded in log entries.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

st_loggerSingleton

private static Logger st_loggerSingleton

m_intLogLevel

private int m_intLogLevel

m_strAppName

private String m_strAppName

m_strAppVersion

private String m_strAppVersion

m_strUsername

private String m_strUsername

m_alTargets

private ArrayList m_alTargets

Constructor Detail

Logger

public Logger()

Method Detail

addTarget

public void addTarget(Logger.LoggerTarget target)

Add to the list of LoggerTargets to which logging is done.

Parameters:

target - An additional LoggerTarget to log to.

setLogLevel

public void setLogLevel(int intNew)

Set the log level. Each call to log() with a logLevel greater than this value will be ignored. Only calls with logLevel less than or equal to this value are logged. Default = 1.

Parameters:

intNew - The new log level.

getLogLevel

public int getLogLevel()

Get the log level.

Returns:

The log level.

setAppName

public void setAppName(String strNew)

Set the application name to be recorded in log entries. Default = "".

Parameters:

strNew - The new application name.

getAppName

public String getAppName()

Get the application name.

Returns:

The application name.

setAppVersion

public void setAppVersion(String strNew)

Set the application version to be recorded in log entries. Default = "".

Parameters:

strNew - The new application version.

getAppVersion

public String getAppVersion()

Get the application version.

Returns:

The application version.

setUsername

public void setUsername(String strNew)

Set the username to be recorded in log entries. Default = current logged in username.

Parameters:

strNew - The new username.

getUsername

public String getUsername()

Get the username.

Returns:

The username.

log

public void log(int intLogLevel,
                String strMsg)

Log a message to the various LoggerTargets. Compares the specified log level with the current log level. Logs the message if the specified level is less than or equal to the current level.

Parameters:

intLogLevel - Level at which to log the message.

strMsg - String to write to the log entry.

logSafely

public static void logSafely(Logger logger,
                             int intLogLevel,
                             String strMsg)

Log a message, suppressing all possible errors, even the error of passing a null value for logger. It is safe to call this method from an exception handler or finally clause without fear of throwing another exception.

Parameters:

logger - The Logger to pass the message to.

intLogLevel - Level at which to log the message.

strMsg - String to write to the log entry.

logErrorSafely

public static void logErrorSafely(Logger logger,
                                  int intLogLevel,
                                  String strMsg,
                                  Throwable e)

Log an error message, suppressing all possible errors, even the error of passing a null value for logger. It is safe to call this method from an exception handler or finally clause without fear of throwing another exception.

Parameters:

logger - The Logger to pass the message to.

intLogLevel - Level at which to log the message.

strMsg - String to write to the log entry.

e - Throwable to include in the message text, or null.

setSingleton

public static void setSingleton(Logger logger)

Set the singleton Logger.

Parameters:

logger - The Logger instance to be stored as the singleton.

getSingleton

public static Logger getSingleton()

Get the singleton Logger, if any.

Returns:

The singleton Logger, or null.

logSafely

public static void logSafely(int intLogLevel,
                             String strMsg)

Log a message via the singleton Logger, suppressing all possible errors, even the error of having a null value for the singleton Logger. It is safe to call this method from an exception handler or finally clause without fear of throwing another exception.

Parameters:

intLogLevel - Level at which to log the message.

strMsg - String to write to the log entry.

logErrorSafely

public static void logErrorSafely(int intLogLevel,
                                  String strMsg,
                                  Throwable e)

Log an error message via the singleton Logger, suppressing all possible errors, even the error of having a null value for the singleton Logger. It is safe to call this method from an exception handler or finally clause without fear of throwing another exception.

Parameters:

intLogLevel - Level at which to log the message.

strMsg - String to write to the log entry.

e - Throwable to include in the message text, or null.