1/**
2 * Copyright (c) 2004-2011 QOS.ch
3 * All rights reserved.
4 *
5 * Permission is hereby granted, free  of charge, to any person obtaining
6 * a  copy  of this  software  and  associated  documentation files  (the
7 * "Software"), to  deal in  the Software without  restriction, including
8 * without limitation  the rights to  use, copy, modify,  merge, publish,
9 * distribute,  sublicense, and/or sell  copies of  the Software,  and to
10 * permit persons to whom the Software  is furnished to do so, subject to
11 * the following conditions:
12 *
13 * The  above  copyright  notice  and  this permission  notice  shall  be
14 * included in all copies or substantial portions of the Software.
15 *
16 * THE  SOFTWARE IS  PROVIDED  "AS  IS", WITHOUT  WARRANTY  OF ANY  KIND,
17 * EXPRESS OR  IMPLIED, INCLUDING  BUT NOT LIMITED  TO THE  WARRANTIES OF
18 * MERCHANTABILITY,    FITNESS    FOR    A   PARTICULAR    PURPOSE    AND
19 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
20 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
21 * OF CONTRACT, TORT OR OTHERWISE,  ARISING FROM, OUT OF OR IN CONNECTION
22 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
23 *
24 */
25package org.slf4j.ext;
26
27import org.slf4j.Logger;
28import org.slf4j.Marker;
29import org.slf4j.MarkerFactory;
30import org.slf4j.helpers.FormattingTuple;
31import org.slf4j.helpers.MessageFormatter;
32import org.slf4j.spi.LocationAwareLogger;
33
34/**
35 * A utility that provides standard mechanisms for logging certain kinds of
36 * activities.
37 *
38 * @author Ralph Goers
39 * @author Ceki Gülcü
40 */
41public class XLogger extends LoggerWrapper implements Logger {
42
43    private static final String FQCN = XLogger.class.getName();
44    static Marker FLOW_MARKER = MarkerFactory.getMarker("FLOW");
45    static Marker ENTRY_MARKER = MarkerFactory.getMarker("ENTRY");
46    static Marker EXIT_MARKER = MarkerFactory.getMarker("EXIT");
47
48    static Marker EXCEPTION_MARKER = MarkerFactory.getMarker("EXCEPTION");
49    static Marker THROWING_MARKER = MarkerFactory.getMarker("THROWING");
50    static Marker CATCHING_MARKER = MarkerFactory.getMarker("CATCHING");
51
52    static String EXIT_MESSAGE_0 = "exit";
53    static String EXIT_MESSAGE_1 = "exit with ({})";
54
55    static String ENTRY_MESSAGE_0 = "entry";
56    static String ENTRY_MESSAGE_1 = "entry with ({})";
57    static String ENTRY_MESSAGE_2 = "entry with ({}, {})";
58    static String ENTRY_MESSAGE_3 = "entry with ({}, {}, {})";
59    static String ENTRY_MESSAGE_4 = "entry with ({}, {}, {}, {})";
60    static int ENTRY_MESSAGE_ARRAY_LEN = 5;
61    static String[] ENTRY_MESSAGE_ARRAY = new String[ENTRY_MESSAGE_ARRAY_LEN];
62    static {
63        ENTRY_MARKER.add(FLOW_MARKER);
64        EXIT_MARKER.add(FLOW_MARKER);
65        THROWING_MARKER.add(EXCEPTION_MARKER);
66        CATCHING_MARKER.add(EXCEPTION_MARKER);
67
68        ENTRY_MESSAGE_ARRAY[0] = ENTRY_MESSAGE_0;
69        ENTRY_MESSAGE_ARRAY[1] = ENTRY_MESSAGE_1;
70        ENTRY_MESSAGE_ARRAY[2] = ENTRY_MESSAGE_2;
71        ENTRY_MESSAGE_ARRAY[3] = ENTRY_MESSAGE_3;
72        ENTRY_MESSAGE_ARRAY[4] = ENTRY_MESSAGE_4;
73    }
74
75    public enum Level {
76        TRACE("TRACE", LocationAwareLogger.TRACE_INT), DEBUG("DEBUG", LocationAwareLogger.DEBUG_INT), INFO("INFO", LocationAwareLogger.INFO_INT), WARN("WARN",
77                        LocationAwareLogger.WARN_INT), ERROR("ERROR", LocationAwareLogger.ERROR_INT);
78
79        private final String name;
80        private final int level;
81
82        public String toString() {
83            return this.name;
84        }
85
86        public int intValue() {
87            return this.level;
88        }
89
90        private Level(String name, int level) {
91            this.name = name;
92            this.level = level;
93        }
94    }
95
96    /**
97     * Given an underlying logger, construct an XLogger
98     *
99     * @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://bugzilla.slf4j.org/show_bug.cgi?id=114
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}
217