vladium/logging/Logger.java

/* 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
// ----------------------------------------------------------------------------