| /* Copyright (C) 2003 Vladimir Roubtsov. All rights reserved. |
| * |
| * This program and the accompanying materials are made available under |
| * the terms of the Common Public License v1.0 which accompanies this distribution, |
| * and is available at http://www.eclipse.org/legal/cpl-v10.html |
| * |
| * $Id: Logger.java,v 1.1.1.1.2.2 2004/07/16 23:32:29 vlad_r Exp $ |
| */ |
| package com.vladium.logging; |
| |
| import java.io.PrintWriter; |
| import java.io.StringWriter; |
| import java.util.HashSet; |
| import java.util.LinkedList; |
| import java.util.NoSuchElementException; |
| import java.util.Properties; |
| import java.util.Set; |
| import java.util.StringTokenizer; |
| |
| import com.vladium.emma.AppLoggers; |
| import com.vladium.emma.IAppConstants; |
| import com.vladium.util.ClassLoaderResolver; |
| import com.vladium.util.Property; |
| import com.vladium.util.Strings; |
| |
| // ---------------------------------------------------------------------------- |
| /** |
| * 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.<P> |
| * |
| * 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.<P> |
| * |
| * Every log message is structured as follows: |
| * <OL> |
| * <LI> message is prefixed with the prefix string set in the Logger if that is |
| * not null; |
| * <LI> 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; |
| * <LI> caller-supplied message is logged, if not null; |
| * <LI> caller-supplied Throwable is dumped starting with a new line, if not null. |
| * </OL> |
| * |
| * 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. |
| * |
| * @see ILogLevels |
| * |
| * @author (C) 2001, Vlad Roubtsov |
| */ |
| public |
| final class Logger implements ILogLevels |
| { |
| // public: ................................................................ |
| |
| // TODO: update javadoc for 'logCaller' |
| // TODO: need isLoggable (Class) |
| |
| public static Logger create (final int level, final PrintWriter out, final String prefix, final Set classMask) |
| { |
| if ((level < NONE) || (level > ALL)) |
| throw new IllegalArgumentException ("invalid log level: " + level); |
| |
| if ((out == null) || out.checkError ()) |
| throw new IllegalArgumentException ("null or corrupt input: out"); |
| |
| return new Logger (level, out, prefix, classMask); |
| } |
| |
| /** |
| * This works as a cloning creator of sorts. |
| * |
| * @param level |
| * @param out |
| * @param prefix |
| * @param classMask |
| * @param base |
| * @return |
| */ |
| public static Logger create (final int level, final PrintWriter out, final String prefix, final Set classMask, |
| final Logger base) |
| { |
| if (base == null) |
| { |
| return create (level, out, prefix, classMask); |
| } |
| else |
| { |
| final int _level = level >= NONE |
| ? level |
| : base.m_level; |
| |
| final PrintWriter _out = (out != null) && ! out.checkError () |
| ? out |
| : base.m_out; |
| |
| // TODO: do a better job of logger cloning |
| final String _prefix = prefix; |
| // final String _prefix = prefix != null |
| // ? prefix |
| // : base.m_prefix; |
| |
| final Set _classMask = classMask != null |
| ? classMask |
| : base.m_classMask; |
| |
| |
| return new Logger (_level, _out, _prefix, _classMask); |
| } |
| } |
| |
| |
| /** |
| * 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 ILogLevels |
| */ |
| public final boolean isLoggable (final int level) |
| { |
| return (level <= m_level); |
| } |
| |
| /** |
| * A convenience method equivalent to isLoggable(INFO). |
| */ |
| public final boolean atINFO () |
| { |
| return (INFO <= m_level); |
| } |
| |
| /** |
| * A convenience method equivalent to isLoggable(VERBOSE). |
| */ |
| public final boolean atVERBOSE () |
| { |
| return (VERBOSE <= m_level); |
| } |
| |
| /** |
| * A convenience method equivalent to isLoggable(TRACE1). |
| */ |
| public final boolean atTRACE1 () |
| { |
| return (TRACE1 <= m_level); |
| } |
| |
| /** |
| * A convenience method equivalent to isLoggable(TRACE2). |
| */ |
| public final boolean atTRACE2 () |
| { |
| return (TRACE2 <= m_level); |
| } |
| |
| /** |
| * A convenience method equivalent to isLoggable(TRACE3). |
| */ |
| public final boolean atTRACE3 () |
| { |
| return (TRACE3 <= m_level); |
| } |
| |
| |
| /** |
| * A convenience method to log 'msg' from an anonymous calling method |
| * at WARNING level. |
| * |
| * @param msg log message [ignored if null] |
| */ |
| public final void warning (final String msg) |
| { |
| _log (WARNING, null, msg, false); |
| } |
| |
| /** |
| * A convenience method to log 'msg' from an anonymous calling method |
| * at INFO level. |
| * |
| * @param msg log message [ignored if null] |
| */ |
| public final void info (final String msg) |
| { |
| _log (INFO, null, msg, false); |
| } |
| |
| /** |
| * A convenience method to log 'msg' from an anonymous calling method |
| * at VERBOSE level. |
| * |
| * @param msg log message [ignored if null] |
| */ |
| public final void verbose (final String msg) |
| { |
| _log (VERBOSE, null, msg, false); |
| } |
| |
| |
| /** |
| * A convenience method equivalent to log(TRACE1, method, msg). |
| * |
| * @param method calling method name [ignored if null] |
| * @param msg log message [ignored if null] |
| */ |
| public final void trace1 (final String method, final String msg) |
| { |
| _log (TRACE1, method, msg, true); |
| } |
| |
| /** |
| * A convenience method equivalent to log(TRACE2, method, msg). |
| * |
| * @param method calling method name [ignored if null] |
| * @param msg log message [ignored if null] |
| */ |
| public final void trace2 (final String method, final String msg) |
| { |
| _log (TRACE2, method, msg, true); |
| } |
| |
| /** |
| * A convenience method equivalent to log(TRACE3, method, msg). |
| * |
| * @param method calling method name [ignored if null] |
| * @param msg log message [ignored if null] |
| */ |
| public final void trace3 (final String method, final String msg) |
| { |
| _log (TRACE3, method, msg, true); |
| } |
| |
| /** |
| * Logs 'msg' from an unnamed calling method. |
| * |
| * @param level level to log at [the method does nothing if this is less |
| * than the set level]. |
| * @param msg log message [ignored if null] |
| */ |
| public final void log (final int level, final String msg, final boolean logCaller) |
| { |
| _log (level, null, msg, logCaller); |
| } |
| |
| /** |
| * Logs 'msg' from a given calling method. |
| * |
| * @param level level to log at [the method does nothing if this is less |
| * than the set level]. |
| * @param method calling method name [ignored if null] |
| * @param msg log message [ignored if null] |
| */ |
| public final void log (final int level, final String method, final String msg, final boolean logCaller) |
| { |
| _log (level, method, msg, logCaller); |
| } |
| |
| /** |
| * Logs 'msg' from an unnamed calling method followed by the 'throwable' stack |
| * trace dump. |
| * |
| * @param level level to log at [the method does nothing if this is less |
| * than the set level]. |
| * @param msg log message [ignored if null] |
| * @param throwable to dump after message [ignored if null] |
| */ |
| public final void log (final int level, final String msg, final Throwable throwable) |
| { |
| _log (level, null, msg, throwable); |
| } |
| |
| /** |
| * Logs 'msg' from a given calling method followed by the 'throwable' stack |
| * trace dump. |
| * |
| * @param level level to log at [the method does nothing if this is less |
| * than the set level]. |
| * @param method calling method name [ignored if null] |
| * @param msg log message [ignored if null] |
| * @param throwable to dump after message [ignored if null] |
| */ |
| public final void log (final int level, final String method, final String msg, final Throwable throwable) |
| { |
| _log (level, method, msg, throwable); |
| } |
| |
| |
| /** |
| * Provides direct access to the PrintWriter used by this Logger. |
| * |
| * @return print writer used by this logger [never null] |
| */ |
| public PrintWriter getWriter () |
| { |
| return m_out; |
| } |
| |
| |
| /** |
| * Returns the current top of the thread-local logger stack or the static |
| * Logger instance scoped to Logger.class if the stack is empty. |
| * |
| * @return current logger [never null] |
| */ |
| public static Logger getLogger () |
| { |
| final LinkedList stack = (LinkedList) THREAD_LOCAL_STACK.get (); |
| |
| // [assertion: stack != null] |
| |
| if (stack.isEmpty ()) |
| { |
| return STATIC_LOGGER; |
| } |
| else |
| { |
| return (Logger) stack.getLast (); |
| } |
| } |
| |
| /** |
| * |
| * @param ctx [may not be null] |
| */ |
| public static void push (final Logger ctx) |
| { |
| if (ctx == null) |
| throw new IllegalArgumentException ("null input: ctx"); |
| |
| final LinkedList stack = (LinkedList) THREAD_LOCAL_STACK.get (); |
| stack.addLast (ctx); |
| } |
| |
| /** |
| * Requiring a context parameter here helps enforce correct push/pop |
| * nesting in the caller code. |
| * |
| * @param ctx [may not be null] |
| */ |
| public static void pop (final Logger ctx) |
| { |
| // TODO: add guards for making sure only the pushing thread is allowed to |
| // execute this |
| |
| final LinkedList stack = (LinkedList) THREAD_LOCAL_STACK.get (); |
| |
| try |
| { |
| final Logger current = (Logger) stack.getLast (); |
| if (current != ctx) |
| throw new IllegalStateException ("invalid context being popped: " + ctx); |
| |
| stack.removeLast (); |
| current.cleanup (); |
| } |
| catch (NoSuchElementException nsee) |
| { |
| throw new IllegalStateException ("empty logger context stack on thread [" + Thread.currentThread () + "]: " + nsee); |
| } |
| } |
| |
| |
| public static int stringToLevel (final String level) |
| { |
| if (ILogLevels.SEVERE_STRING.equalsIgnoreCase (level) || ILogLevels.SILENT_STRING.equalsIgnoreCase (level)) |
| return ILogLevels.SEVERE; |
| else if (ILogLevels.WARNING_STRING.equalsIgnoreCase (level) || ILogLevels.QUIET_STRING.equalsIgnoreCase (level)) |
| return ILogLevels.WARNING; |
| else if (ILogLevels.INFO_STRING.equalsIgnoreCase (level)) |
| return ILogLevels.INFO; |
| else if (ILogLevels.VERBOSE_STRING.equalsIgnoreCase (level)) |
| return ILogLevels.VERBOSE; |
| else if (ILogLevels.TRACE1_STRING.equalsIgnoreCase (level)) |
| return ILogLevels.TRACE1; |
| else if (ILogLevels.TRACE2_STRING.equalsIgnoreCase (level)) |
| return ILogLevels.TRACE2; |
| else if (ILogLevels.TRACE3_STRING.equalsIgnoreCase (level)) |
| return ILogLevels.TRACE3; |
| else if (ILogLevels.NONE_STRING.equalsIgnoreCase (level)) |
| return ILogLevels.NONE; |
| else if (ILogLevels.ALL_STRING.equalsIgnoreCase (level)) |
| return ILogLevels.ALL; |
| else |
| { |
| int _level = Integer.MIN_VALUE; |
| try |
| { |
| _level = Integer.parseInt (level); |
| } |
| catch (Exception ignore) {} |
| |
| if ((_level >= ILogLevels.NONE) && (_level <= ILogLevels.ALL)) |
| return _level; |
| else |
| return ILogLevels.INFO; // default to something middle of the ground |
| } |
| } |
| |
| // protected: ............................................................. |
| |
| // package: ............................................................... |
| |
| // private: ............................................................... |
| |
| |
| private static final class ThreadLocalStack extends InheritableThreadLocal |
| { |
| protected Object initialValue () |
| { |
| return new LinkedList (); |
| } |
| |
| } // end of nested class |
| |
| |
| private Logger (final int level, final PrintWriter out, final String prefix, final Set classMask) |
| { |
| m_level = level; |
| m_out = out; |
| m_prefix = prefix; |
| m_classMask = classMask; // no defensive clone |
| } |
| |
| private void cleanup () |
| { |
| m_out.flush (); |
| } |
| |
| private void _log (final int level, final String method, |
| final String msg, final boolean logCaller) |
| { |
| if ((level <= m_level) && (level >= SEVERE)) |
| { |
| final Class caller = logCaller ? ClassLoaderResolver.getCallerClass (2) : null; |
| final StringBuffer buf = new StringBuffer (m_prefix != null ? m_prefix + ": " : ""); |
| |
| if ((caller != null) || (method != null)) |
| { |
| buf.append ("["); |
| |
| if (caller != null) // if the caller could not be determined, s_classMask is ignored |
| { |
| String callerName = caller.getName (); |
| |
| if (callerName.startsWith (PREFIX_TO_STRIP)) |
| callerName = callerName.substring (PREFIX_TO_STRIP_LENGTH); |
| |
| String parentName = callerName; |
| |
| final int firstDollar = callerName.indexOf ('$'); |
| if (firstDollar > 0) parentName = callerName.substring (0, firstDollar); |
| |
| if ((m_classMask == null) || m_classMask.contains (parentName)) |
| buf.append (callerName); |
| else |
| return; |
| } |
| |
| if (method != null) |
| { |
| buf.append ("::"); |
| buf.append (method); |
| } |
| |
| buf.append ("] "); |
| } |
| |
| final PrintWriter out = m_out; |
| |
| if (msg != null) buf.append (msg); |
| |
| out.println (buf); |
| if (FLUSH_LOG) out.flush (); |
| } |
| } |
| |
| private void _log (final int level, final String method, |
| final String msg, final Throwable throwable) |
| { |
| if ((level <= m_level) && (level >= SEVERE)) |
| { |
| final Class caller = ClassLoaderResolver.getCallerClass (2); |
| final StringBuffer buf = new StringBuffer (m_prefix != null ? m_prefix + ": " : ""); |
| |
| if ((caller != null) || (method != null)) |
| { |
| buf.append ("["); |
| |
| if (caller != null) // if the caller could not be determined, s_classMask is ignored |
| { |
| String callerName = caller.getName (); |
| |
| if (callerName.startsWith (PREFIX_TO_STRIP)) |
| callerName = callerName.substring (PREFIX_TO_STRIP_LENGTH); |
| |
| String parentName = callerName; |
| |
| final int firstDollar = callerName.indexOf ('$'); |
| if (firstDollar > 0) parentName = callerName.substring (0, firstDollar); |
| |
| if ((m_classMask == null) || m_classMask.contains (parentName)) |
| buf.append (callerName); |
| else |
| return; |
| } |
| |
| if (method != null) |
| { |
| buf.append ("::"); |
| buf.append (method); |
| } |
| |
| buf.append ("] "); |
| } |
| |
| final PrintWriter out = m_out; |
| |
| if (msg != null) buf.append (msg); |
| |
| if (throwable != null) |
| { |
| final StringWriter sw = new StringWriter (); |
| final PrintWriter pw = new PrintWriter (sw); |
| |
| throwable.printStackTrace (pw); |
| pw.flush (); |
| |
| buf.append (sw.toString ()); |
| } |
| |
| out.println (buf); |
| if (FLUSH_LOG) out.flush (); |
| } |
| } |
| |
| |
| |
| private final int m_level; // always in [NONE, ALL] range |
| private final PrintWriter m_out; // never null |
| private final String m_prefix; // null is equivalent to no prefix |
| private final Set /* String */ m_classMask; // null is equivalent to no class filtering |
| |
| private static final String PREFIX_TO_STRIP = "com.vladium."; // TODO: can this be set programmatically ? |
| private static final int PREFIX_TO_STRIP_LENGTH = PREFIX_TO_STRIP.length (); |
| private static final boolean FLUSH_LOG = true; |
| private static final String COMMA_DELIMITERS = "," + Strings.WHITE_SPACE; |
| |
| private static final Logger STATIC_LOGGER; // set in <clinit> |
| private static final ThreadLocalStack THREAD_LOCAL_STACK; // set in <clinit> |
| |
| static |
| { |
| THREAD_LOCAL_STACK = new ThreadLocalStack (); |
| |
| // TODO: unfortunately, this init code makes Logger coupled to the app classes |
| // (via the app namespace string constants) |
| // I don't quite see an elegant solution to this design problem yet |
| |
| final Properties properties = Property.getAppProperties (IAppConstants.APP_NAME_LC, Logger.class.getClassLoader ()); |
| |
| // verbosity level: |
| |
| final int level; |
| { |
| final String _level = properties.getProperty (AppLoggers.PROPERTY_VERBOSITY_LEVEL, |
| AppLoggers.DEFAULT_VERBOSITY_LEVEL); |
| level = stringToLevel (_level); |
| } |
| |
| // verbosity filter: |
| |
| final Set filter; |
| { |
| final String _filter = properties.getProperty (AppLoggers.PROPERTY_VERBOSITY_FILTER); |
| Set temp = null; |
| |
| if (_filter != null) |
| { |
| final StringTokenizer tokenizer = new StringTokenizer (_filter, COMMA_DELIMITERS); |
| if (tokenizer.countTokens () > 0) |
| { |
| temp = new HashSet (tokenizer.countTokens ()); |
| while (tokenizer.hasMoreTokens ()) |
| { |
| temp.add (tokenizer.nextToken ()); |
| } |
| } |
| } |
| |
| filter = temp; |
| } |
| |
| |
| STATIC_LOGGER = create (level, |
| new PrintWriter (System.out, false), |
| IAppConstants.APP_NAME, |
| filter); |
| } |
| |
| } // end of class |
| // ---------------------------------------------------------------------------- |
