com.vladium.logging
Class Logger

java.lang.Object
  extended by com.vladium.logging.Logger
All Implemented Interfaces:
ILogLevels

public final class Logger
extends java.lang.Object
implements ILogLevels

A simple Java version-independent logging framework. Each Logger is also an immutable context that encapsulates configuration elements like the logging verbosity level etc. In general, a Logger is looked up as an inheritable thread-local piece of data. This decouples classes and logging configurations in a way that seems difficult with log4j.

Note that a given class is free to cache its context in an instance field if the class is instantiated and used only on a single thread (or a set of threads that are guaranteed to share the same logging context). [This is different from the usual log4j pattern of caching a logger in a class static field]. In other cases (e.g., the instrumentation runtime), it makes more sense to scope a context to a single method invocation.

Every log message is structured as follows:

  1. message is prefixed with the prefix string set in the Logger if that is not null;
  2. if the calling class could be identified and it supplied the calling method name, the calling method is identified with all name components that are not null;
  3. caller-supplied message is logged, if not null;
  4. caller-supplied Throwable is dumped starting with a new line, if not null.
MT-safety: a given Logger instance will not get corrupted by concurrent usage from multiple threads and guarantees that data written to the underlying PrintWriter in a single log call will be done in one atomic print() step.

Author:
(C) 2001, Vlad Roubtsov
See Also:
ILogLevels

Nested Class Summary
private static class Logger.ThreadLocalStack
           
 
Field Summary
private static java.lang.String COMMA_DELIMITERS
           
private static boolean FLUSH_LOG
           
private  java.util.Set m_classMask
           
private  int m_level
           
private  java.io.PrintWriter m_out
           
private  java.lang.String m_prefix
           
private static java.lang.String PREFIX_TO_STRIP
           
private static int PREFIX_TO_STRIP_LENGTH
           
private static Logger STATIC_LOGGER
           
private static Logger.ThreadLocalStack THREAD_LOCAL_STACK
           
 
Fields inherited from interface com.vladium.logging.ILogLevels
ALL, ALL_STRING, INFO, INFO_STRING, NONE, NONE_STRING, QUIET_STRING, SEVERE, SEVERE_STRING, SILENT_STRING, TRACE1, TRACE1_STRING, TRACE2, TRACE2_STRING, TRACE3, TRACE3_STRING, VERBOSE, VERBOSE_STRING, WARNING, WARNING_STRING
 
Constructor Summary
private Logger(int level, java.io.PrintWriter out, java.lang.String prefix, java.util.Set classMask)
           
 
Method Summary
private  void _log(int level, java.lang.String method, java.lang.String msg, boolean logCaller)
           
private  void _log(int level, java.lang.String method, java.lang.String msg, java.lang.Throwable throwable)
           
 boolean atINFO()
          A convenience method equivalent to isLoggable(INFO).
 boolean atTRACE1()
          A convenience method equivalent to isLoggable(TRACE1).
 boolean atTRACE2()
          A convenience method equivalent to isLoggable(TRACE2).
 boolean atTRACE3()
          A convenience method equivalent to isLoggable(TRACE3).
 boolean atVERBOSE()
          A convenience method equivalent to isLoggable(VERBOSE).
private  void cleanup()
           
static Logger create(int level, java.io.PrintWriter out, java.lang.String prefix, java.util.Set classMask)
           
static Logger create(int level, java.io.PrintWriter out, java.lang.String prefix, java.util.Set classMask, Logger base)
          This works as a cloning creator of sorts.
static Logger getLogger()
          Returns the current top of the thread-local logger stack or the static Logger instance scoped to Logger.class if the stack is empty.
 java.io.PrintWriter getWriter()
          Provides direct access to the PrintWriter used by this Logger.
 void info(java.lang.String msg)
          A convenience method to log 'msg' from an anonymous calling method at INFO level.
 boolean isLoggable(int level)
          A quick method to determine if logging is enabled at a given level.
 void log(int level, java.lang.String msg, boolean logCaller)
          Logs 'msg' from an unnamed calling method.
 void log(int level, java.lang.String method, java.lang.String msg, boolean logCaller)
          Logs 'msg' from a given calling method.
 void log(int level, java.lang.String method, java.lang.String msg, java.lang.Throwable throwable)
          Logs 'msg' from a given calling method followed by the 'throwable' stack trace dump.
 void log(int level, java.lang.String msg, java.lang.Throwable throwable)
          Logs 'msg' from an unnamed calling method followed by the 'throwable' stack trace dump.
static void pop(Logger ctx)
          Requiring a context parameter here helps enforce correct push/pop nesting in the caller code.
static void push(Logger ctx)
           
static int stringToLevel(java.lang.String level)
           
 void trace1(java.lang.String method, java.lang.String msg)
          A convenience method equivalent to log(TRACE1, method, msg).
 void trace2(java.lang.String method, java.lang.String msg)
          A convenience method equivalent to log(TRACE2, method, msg).
 void trace3(java.lang.String method, java.lang.String msg)
          A convenience method equivalent to log(TRACE3, method, msg).
 void verbose(java.lang.String msg)
          A convenience method to log 'msg' from an anonymous calling method at VERBOSE level.
 void warning(java.lang.String msg)
          A convenience method to log 'msg' from an anonymous calling method at WARNING level.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

m_level

private final int m_level

m_out

private final java.io.PrintWriter m_out

m_prefix

private final java.lang.String m_prefix

m_classMask

private final java.util.Set m_classMask

PREFIX_TO_STRIP

private static final java.lang.String PREFIX_TO_STRIP
See Also:
Constant Field Values

PREFIX_TO_STRIP_LENGTH

private static final int PREFIX_TO_STRIP_LENGTH

FLUSH_LOG

private static final boolean FLUSH_LOG
See Also:
Constant Field Values

COMMA_DELIMITERS

private static final java.lang.String COMMA_DELIMITERS
See Also:
Constant Field Values

STATIC_LOGGER

private static final Logger STATIC_LOGGER

THREAD_LOCAL_STACK

private static final Logger.ThreadLocalStack THREAD_LOCAL_STACK
Constructor Detail

Logger

private Logger(int level,
               java.io.PrintWriter out,
               java.lang.String prefix,
               java.util.Set classMask)
Method Detail

create

public static Logger create(int level,
                            java.io.PrintWriter out,
                            java.lang.String prefix,
                            java.util.Set classMask)

create

public static Logger create(int level,
                            java.io.PrintWriter out,
                            java.lang.String prefix,
                            java.util.Set classMask,
                            Logger base)
This works as a cloning creator of sorts.

Parameters:
level -
out -
prefix -
classMask -
base -
Returns:

isLoggable

public final boolean isLoggable(int level)
A quick method to determine if logging is enabled at a given level. This method acquires no monitors and should be used when calling one of log() or convenience logging methods directly incurs significant parameter construction overhead.

See Also:
ILogLevels

atINFO

public final boolean atINFO()
A convenience method equivalent to isLoggable(INFO).


atVERBOSE

public final boolean atVERBOSE()
A convenience method equivalent to isLoggable(VERBOSE).


atTRACE1

public final boolean atTRACE1()
A convenience method equivalent to isLoggable(TRACE1).


atTRACE2

public final boolean atTRACE2()
A convenience method equivalent to isLoggable(TRACE2).


atTRACE3

public final boolean atTRACE3()
A convenience method equivalent to isLoggable(TRACE3).


warning

public final void warning(java.lang.String msg)
A convenience method to log 'msg' from an anonymous calling method at WARNING level.

Parameters:
msg - log message [ignored if null]

info

public final void info(java.lang.String msg)
A convenience method to log 'msg' from an anonymous calling method at INFO level.

Parameters:
msg - log message [ignored if null]

verbose

public final void verbose(java.lang.String msg)
A convenience method to log 'msg' from an anonymous calling method at VERBOSE level.

Parameters:
msg - log message [ignored if null]

trace1

public final void trace1(java.lang.String method,
                         java.lang.String msg)
A convenience method equivalent to log(TRACE1, method, msg).

Parameters:
method - calling method name [ignored if null]
msg - log message [ignored if null]

trace2

public final void trace2(java.lang.String method,
                         java.lang.String msg)
A convenience method equivalent to log(TRACE2, method, msg).

Parameters:
method - calling method name [ignored if null]
msg - log message [ignored if null]

trace3

public final void trace3(java.lang.String method,
                         java.lang.String msg)
A convenience method equivalent to log(TRACE3, method, msg).

Parameters:
method - calling method name [ignored if null]
msg - log message [ignored if null]

log

public final void log(int level,
                      java.lang.String msg,
                      boolean logCaller)
Logs 'msg' from an unnamed calling method.

Parameters:
level - level to log at [the method does nothing if this is less than the set level].
msg - log message [ignored if null]

log

public final void log(int level,
                      java.lang.String method,
                      java.lang.String msg,
                      boolean logCaller)
Logs 'msg' from a given calling method.

Parameters:
level - level to log at [the method does nothing if this is less than the set level].
method - calling method name [ignored if null]
msg - log message [ignored if null]

log

public final void log(int level,
                      java.lang.String msg,
                      java.lang.Throwable throwable)
Logs 'msg' from an unnamed calling method followed by the 'throwable' stack trace dump.

Parameters:
level - level to log at [the method does nothing if this is less than the set level].
msg - log message [ignored if null]
throwable - to dump after message [ignored if null]

log

public final void log(int level,
                      java.lang.String method,
                      java.lang.String msg,
                      java.lang.Throwable throwable)
Logs 'msg' from a given calling method followed by the 'throwable' stack trace dump.

Parameters:
level - level to log at [the method does nothing if this is less than the set level].
method - calling method name [ignored if null]
msg - log message [ignored if null]
throwable - to dump after message [ignored if null]

getWriter

public java.io.PrintWriter getWriter()
Provides direct access to the PrintWriter used by this Logger.

Returns:
print writer used by this logger [never null]

getLogger

public static Logger getLogger()
Returns the current top of the thread-local logger stack or the static Logger instance scoped to Logger.class if the stack is empty.

Returns:
current logger [never null]

push

public static void push(Logger ctx)
Parameters:
ctx - [may not be null]

pop

public static void pop(Logger ctx)
Requiring a context parameter here helps enforce correct push/pop nesting in the caller code.

Parameters:
ctx - [may not be null]

stringToLevel

public static int stringToLevel(java.lang.String level)

cleanup

private void cleanup()

_log

private void _log(int level,
                  java.lang.String method,
                  java.lang.String msg,
                  boolean logCaller)

_log

private void _log(int level,
                  java.lang.String method,
                  java.lang.String msg,
                  java.lang.Throwable throwable)