    001/**
    002 * Copyright (c) 2004-2011 QOS.ch
    003 * All rights reserved.
    004 *
    005 * Permission is hereby granted, free  of charge, to any person obtaining
    006 * a  copy  of this  software  and  associated  documentation files  (the
    007 * "Software"), to  deal in  the Software without  restriction, including
    008 * without limitation  the rights to  use, copy, modify,  merge, publish,
    009 * distribute,  sublicense, and/or sell  copies of  the Software,  and to
    010 * permit persons to whom the Software  is furnished to do so, subject to
    011 * the following conditions:
    012 *
    013 * The  above  copyright  notice  and  this permission  notice  shall  be
    014 * included in all copies or substantial portions of the Software.
    015 *
    016 * THE  SOFTWARE IS  PROVIDED  "AS  IS", WITHOUT  WARRANTY  OF ANY  KIND,
    017 * EXPRESS OR  IMPLIED, INCLUDING  BUT NOT LIMITED  TO THE  WARRANTIES OF
    018 * MERCHANTABILITY,    FITNESS    FOR    A   PARTICULAR    PURPOSE    AND
    019 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
    020 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
    021 * OF CONTRACT, TORT OR OTHERWISE,  ARISING FROM, OUT OF OR IN CONNECTION
    022 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
    023 *
    024 */
    025package org.slf4j.ext;
    026
    027import org.slf4j.Logger;
    028import org.slf4j.Marker;
    029import org.slf4j.MarkerFactory;
    030import org.slf4j.helpers.FormattingTuple;
    031import org.slf4j.helpers.MessageFormatter;
    032import org.slf4j.spi.LocationAwareLogger;
    033
    034/**
    035 * A utility that provides standard mechanisms for logging certain kinds of
    036 * activities.
    037 *
    038 * @author Ralph Goers
    039 * @author Ceki G&uuml;lc&uuml;
    040 */
    041public class XLogger extends LoggerWrapper implements Logger {
    042
    043    private static final String FQCN = XLogger.class.getName();
    044    static Marker FLOW_MARKER = MarkerFactory.getMarker("FLOW");
    045    static Marker ENTRY_MARKER = MarkerFactory.getMarker("ENTRY");
    046    static Marker EXIT_MARKER = MarkerFactory.getMarker("EXIT");
    047
    048    static Marker EXCEPTION_MARKER = MarkerFactory.getMarker("EXCEPTION");
    049    static Marker THROWING_MARKER = MarkerFactory.getMarker("THROWING");
    050    static Marker CATCHING_MARKER = MarkerFactory.getMarker("CATCHING");
    051
    052    static String EXIT_MESSAGE_0 = "exit";
    053    static String EXIT_MESSAGE_1 = "exit with ({})";
    054
    055    static String ENTRY_MESSAGE_0 = "entry";
    056    static String ENTRY_MESSAGE_1 = "entry with ({})";
    057    static String ENTRY_MESSAGE_2 = "entry with ({}, {})";
    058    static String ENTRY_MESSAGE_3 = "entry with ({}, {}, {})";
    059    static String ENTRY_MESSAGE_4 = "entry with ({}, {}, {}, {})";
    060    static int ENTRY_MESSAGE_ARRAY_LEN = 5;
    061    static String[] ENTRY_MESSAGE_ARRAY = new String[ENTRY_MESSAGE_ARRAY_LEN];
    062    static {
    063        ENTRY_MARKER.add(FLOW_MARKER);
    064        EXIT_MARKER.add(FLOW_MARKER);
    065        THROWING_MARKER.add(EXCEPTION_MARKER);
    066        CATCHING_MARKER.add(EXCEPTION_MARKER);
    067
    068        ENTRY_MESSAGE_ARRAY[0] = ENTRY_MESSAGE_0;
    069        ENTRY_MESSAGE_ARRAY[1] = ENTRY_MESSAGE_1;
    070        ENTRY_MESSAGE_ARRAY[2] = ENTRY_MESSAGE_2;
    071        ENTRY_MESSAGE_ARRAY[3] = ENTRY_MESSAGE_3;
    072        ENTRY_MESSAGE_ARRAY[4] = ENTRY_MESSAGE_4;
    073    }
    074
    075    public enum Level {
    076        TRACE("TRACE", LocationAwareLogger.TRACE_INT), DEBUG("DEBUG", LocationAwareLogger.DEBUG_INT), INFO("INFO", LocationAwareLogger.INFO_INT), WARN("WARN",
    077                        LocationAwareLogger.WARN_INT), ERROR("ERROR", LocationAwareLogger.ERROR_INT);
    078
    079        private final String name;
    080        private final int level;
    081
    082        public String toString() {
    083            return this.name;
    084        }
    085
    086        public int intValue() {
    087            return this.level;
    088        }
    089
    090        private Level(String name, int level) {
    091            this.name = name;
    092            this.level = level;
    093        }
    094    }
    095
    096    /**
    097     * Given an underlying logger, construct an XLogger
    098     *
    099     * @param logger
    100     *          underlying logger
    101     */
    102    public XLogger(Logger logger) {
    103        // If class B extends A, assuming B does not override method x(), the caller
    104        // of new B().x() is A and not B, see also
    105        // http://jira.qos.ch/browse/SLF4J-105
    106        super(logger, LoggerWrapper.class.getName());
    107    }
    108
    109    /**
    110     * Log method entry.
    111     *
    112     * @param argArray
    113     *          supplied parameters
    114     */
    115    public void entry(Object... argArray) {
    116        if (instanceofLAL && logger.isTraceEnabled(ENTRY_MARKER)) {
    117            String messagePattern = null;
    118            if (argArray.length < ENTRY_MESSAGE_ARRAY_LEN) {
    119                messagePattern = ENTRY_MESSAGE_ARRAY[argArray.length];
    120            } else {
    121                messagePattern = buildMessagePattern(argArray.length);
    122            }
    123            FormattingTuple tp = MessageFormatter.arrayFormat(messagePattern, argArray);
    124            ((LocationAwareLogger) logger).log(ENTRY_MARKER, FQCN, LocationAwareLogger.TRACE_INT, tp.getMessage(), argArray, tp.getThrowable());
    125        }
    126    }
    127
    128    /**
    129     * Log method exit
    130     */
    131    public void exit() {
    132        if (instanceofLAL && logger.isTraceEnabled(ENTRY_MARKER)) {
    133            ((LocationAwareLogger) logger).log(EXIT_MARKER, FQCN, LocationAwareLogger.TRACE_INT, EXIT_MESSAGE_0, null, null);
    134        }
    135    }
    136
    137    /**
    138     * Log method exit
    139     *
    140     * @param result
    141     *          The result of the method being exited
    142     */
    143    public <T> T exit(T result) {
    144        if (instanceofLAL && logger.isTraceEnabled(ENTRY_MARKER)) {
    145            FormattingTuple tp = MessageFormatter.format(EXIT_MESSAGE_1, result);
    146            ((LocationAwareLogger) logger).log(EXIT_MARKER, FQCN, LocationAwareLogger.TRACE_INT, tp.getMessage(), new Object[] { result }, tp.getThrowable());
    147        }
    148        return result;
    149    }
    150
    151    /**
    152     * Log an exception being thrown. The generated log event uses Level ERROR.
    153     *
    154     * @param throwable
    155     *          the exception being caught.
    156     */
    157    public <T extends Throwable> T throwing(T throwable) {
    158        if (instanceofLAL) {
    159            ((LocationAwareLogger) logger).log(THROWING_MARKER, FQCN, LocationAwareLogger.ERROR_INT, "throwing", null, throwable);
    160        }
    161        return throwable;
    162    }
    163
    164    /**
    165     * Log an exception being thrown allowing the log level to be specified.
    166     *
    167     * @param level
    168     *          the logging level to use.
    169     * @param throwable
    170     *          the exception being caught.
    171     */
    172    public <T extends Throwable> T throwing(Level level, T throwable) {
    173        if (instanceofLAL) {
    174            ((LocationAwareLogger) logger).log(THROWING_MARKER, FQCN, level.level, "throwing", null, throwable);
    175        }
    176        return throwable;
    177    }
    178
    179    /**
    180     * Log an exception being caught. The generated log event uses Level ERROR.
    181     *
    182     * @param throwable
    183     *          the exception being caught.
    184     */
    185    public void catching(Throwable throwable) {
    186        if (instanceofLAL) {
    187            ((LocationAwareLogger) logger).log(CATCHING_MARKER, FQCN, LocationAwareLogger.ERROR_INT, "catching", null, throwable);
    188        }
    189    }
    190
    191    /**
    192     * Log an exception being caught allowing the log level to be specified.
    193     *
    194     * @param level
    195     *          the logging level to use.
    196     * @param throwable
    197     *          the exception being caught.
    198     */
    199    public void catching(Level level, Throwable throwable) {
    200        if (instanceofLAL) {
    201            ((LocationAwareLogger) logger).log(CATCHING_MARKER, FQCN, level.level, "catching", null, throwable);
    202        }
    203    }
    204
    205    private static String buildMessagePattern(int len) {
    206        StringBuilder sb = new StringBuilder();
    207        sb.append(" entry with (");
    208        for (int i = 0; i < len; i++) {
    209            sb.append("{}");
    210            if (i != len - 1)
    211                sb.append(", ");
    212        }
    213        sb.append(')');
    214        return sb.toString();
    215    }
    216}