com.objectwave.logging
Class MessageLog

java.lang.Object
  |
  +--com.objectwave.logging.MessageLog

public class MessageLog

extends java.lang.Object

This class provides an abstraction to any logging system. For example, Log4J or the Logging API put forth to the Java Community Process. The class works in much the same way that other "pluggable" APIs work, i.e. the MessageLog class is merely a skeleton class that has a "peer" that performs the real logging work. The MessageLog class manages that peer and delegates method calls to that peer.

How do I set the peer?
The requirement for the peer classes is limited to one : The Peer class must implement the com.objectwave.logging.LogIF interface.

What is the default peer?
The default peer is the com.objectwave.logging.log4j.Log4jImpl class. This class delegates the the Apache Log4J Logging system.
If log4j is not found in the classpath, then the ConsoleImpl is used.
So how do I use this class In it's most simplistic form, simply call :
com.objectwave.logging.MessageLog.info(this, "My Message");

A note about Message Levels (or ranks)
different ranks that allow logging thresholds to be specified.

debug - This level will almost always be disabled during production. This is the lowest message level.
info - Another low level, but a step above debug. Use this to convey information about the progress of the application. If these messages are not seen, its no big deal.
warn - A setp above info - Will likely be enabled for a production application. Warn level messages report that something odd happened, but not odd enough to necessarily require any immediate action. The odd behavior may actually be expected, just that the module generating the warn message doesn't know enough to make that judgement call.
error - The most severe. The application module has decided that something terrible has happen. Its probably best to begin shutting down the application.

If the source is a string, MessageLog will assume that is a category the caller specifically wants to use, and will not change that string in any way.

Version:

$Id: MessageLog.java,v 2.3 2002/08/24 17:43:16 dave_hoag Exp $

Author:

Dave Hoag

Field Summary

static boolean	showBootstrapLogMessages This flag determines whether or not bootstrap messages should be logged, or shown.
static java.lang.ThreadLocal	traceHolder This maintains the traces on a per thread basis.

Constructor Summary

MessageLog()

Method Summary

static void	debug(java.lang.Object source, java.lang.String message) Display information helpful for debugging applications.
static void	debug(java.lang.Object source, java.lang.String message, java.lang.Throwable cause) Display information helpful for debugging applications.
static void	error(java.lang.Object source, java.lang.String message, java.lang.Throwable cause) There is has been an error.
static LogIF	getLoggingEngine() This method returns the LogIF peer class for the MessageLog.
static void	info(java.lang.Object source, java.lang.String message) Informational messages.
static boolean	isDebugEnabled(java.lang.Object source) isDebugEnabled for the given source.
static void	setLoggingEngine(LogIF engine) Allow any application to plug in their own implementation.
static void	track(java.lang.String categoryName, java.lang.Runnable codeBlock) Run the provided code block and decorate any resulting log messages with specified category.
static void	track(java.lang.String categoryName, Trace codeBlock) Run the provided code block and decorate any resulting log messages with specified category.
static void	warn(java.lang.Object source, java.lang.String message) Warning messages.
static void	warn(java.lang.Object source, java.lang.String message, java.lang.Throwable cause) Warning messages.

Methods inherited from class java.lang.Object

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

Field Detail

showBootstrapLogMessages

public static boolean showBootstrapLogMessages

This flag determines whether or not bootstrap messages should be logged, or shown. This should be changed directly as there is no need for a public mutator method.

traceHolder

public static java.lang.ThreadLocal traceHolder

This maintains the traces on a per thread basis.

Constructor Detail

MessageLog

public MessageLog()

Method Detail

setLoggingEngine

public static final void setLoggingEngine(LogIF engine)

Allow any application to plug in their own implementation. This in effect sets the peer class for the MessageLog. If engine is set to null, then the com.objectwave.logging.ConsoleImpl peer class is used.

Parameters:

engine - The new LoggingEngine value

See Also:

ConsoleImpl

isDebugEnabled

public static boolean isDebugEnabled(java.lang.Object source)

isDebugEnabled for the given source. Since logging is managed by "categories" the source parameter to this method calls queries whether or not debug is enabled for the appropriate category.

Parameters:

source - An object or String category

Returns:

true if debug is enabled for the object source or "category"

getLoggingEngine

public static final LogIF getLoggingEngine()

This method returns the LogIF peer class for the MessageLog. If the peer class is null, then an instance of ConsoleImpl is returned. However, each time, a new ConsoleImpl is returned, so subsequent calls to this method will NOT return the same intance.

Returns:

the MessageLog LogIF peer implementation

info

public static void info(java.lang.Object source,
                        java.lang.String message)

Informational messages. Messages that should useful information about a running application. Information you would want to know, weather or not the application is being debugged.

Parameters:

source - An object that will provide context to the message being logged.

message -

warn

public static void warn(java.lang.Object source,
                        java.lang.String message,
                        java.lang.Throwable cause)

Warning messages. Something may be wrong with the application, but it is not fatal and the application is going to try to recover.

Parameters:

source - An object that will provide context to the message being logged.

message -

cause -

warn

public static void warn(java.lang.Object source,
                        java.lang.String message)

Warning messages. Something may be wrong with the application, but it is not fatal and the application is going to try to recover.

Parameters:

source - An object that will provide context to the message being logged.

message -

debug

public static void debug(java.lang.Object source,
                         java.lang.String message)

Display information helpful for debugging applications.

Parameters:

source - An object that will provide context to the message being logged.

message -

debug

public static void debug(java.lang.Object source,
                         java.lang.String message,
                         java.lang.Throwable cause)

Display information helpful for debugging applications. It may be helpful to log stack traces of Throwables that are not necessarily errors. Use this debug message to accomplish this feat.

Parameters:

source - An object that will provide context to the message being logged.

message -

cause -

error

public static void error(java.lang.Object source,
                         java.lang.String message,
                         java.lang.Throwable cause)

There is has been an error.

Parameters:

source - An object that will provide context to the message being logged.

message -

cause -

track

public static void track(java.lang.String categoryName,
                         Trace codeBlock)
                  throws java.lang.Exception

Run the provided code block and decorate any resulting log messages with specified category. This actually OVERRIDES the category put forth by an object if it's code is executed within the tracked thread.
For example, a normal log may look like: [DEBUG] test.MyClassA - sayHello enter
[DEBUG] test.MyClassB - getName enter, return Trever
[DEBUG] test.MyClassA - sayHello exit

when executed with the "track" method, in the "mytrace1" category would look like:
[DEBUG] mytrace1.test.MyClassA - sayHello enter
[DEBUG] mytrace1.test.MyClassB - getName enter, return Trever
[DEBUG] mytrace1.test.MyClassA - sayHello exit

Notice how the categories "test.MyClassA and test.MyClassB" were decorated with the mytrace1 category passed into the track method.

Parameters:

categoryName - The 'tracking' name that will be used to follow the call path.

codeBlock - The code to execute.

Throws:

java.lang.Exception - Any exception could occur while running code!

track

public static void track(java.lang.String categoryName,
                         java.lang.Runnable codeBlock)

Run the provided code block and decorate any resulting log messages with specified category.

Parameters:

categoryName - The 'tracking' name that will be used to follow the call path.

codeBlock - The code to execute.

See Also:

track(String,Trace)