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ülcü
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),
077                INFO("INFO", LocationAwareLogger.INFO_INT), WARN("WARN", LocationAwareLogger.WARN_INT),
078                ERROR("ERROR", LocationAwareLogger.ERROR_INT);
079
080                private final String name;
081                private final int level;
082
083                public String toString() {
084                        return this.name;
085                }
086
087                public int intValue() {
088                        return this.level;
089                }
090
091                private Level(String name, int level) {
092                        this.name = name;
093                        this.level = level;
094                }
095        }
096
097        /**
098         * Given an underlying logger, construct an XLogger
099         * 
100         * @param logger 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 supplied parameters
113         */
114        public void entry(Object... argArray) {
115                if (instanceofLAL && logger.isTraceEnabled(ENTRY_MARKER)) {
116                        String messagePattern = null;
117                        if (argArray.length < ENTRY_MESSAGE_ARRAY_LEN) {
118                                messagePattern = ENTRY_MESSAGE_ARRAY[argArray.length];
119                        } else {
120                                messagePattern = buildMessagePattern(argArray.length);
121                        }
122                        FormattingTuple tp = MessageFormatter.arrayFormat(messagePattern, argArray);
123                        ((LocationAwareLogger) logger).log(ENTRY_MARKER, FQCN, LocationAwareLogger.TRACE_INT, tp.getMessage(),
124                                        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,
134                                        null);
135                }
136        }
137
138        /**
139         * Log method exit
140         * 
141         * @param result 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(),
147                                        new Object[] { result }, tp.getThrowable());
148                }
149                return result;
150        }
151
152        /**
153         * Log an exception being thrown. The generated log event uses Level ERROR.
154         * 
155         * @param throwable 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,
160                                        throwable);
161                }
162                return throwable;
163        }
164
165        /**
166         * Log an exception being thrown allowing the log level to be specified.
167         * 
168         * @param level     the logging level to use.
169         * @param throwable the exception being caught.
170         */
171        public <T extends Throwable> T throwing(Level level, T throwable) {
172                if (instanceofLAL) {
173                        ((LocationAwareLogger) logger).log(THROWING_MARKER, FQCN, level.level, "throwing", null, throwable);
174                }
175                return throwable;
176        }
177
178        /**
179         * Log an exception being caught. The generated log event uses Level ERROR.
180         * 
181         * @param throwable the exception being caught.
182         */
183        public void catching(Throwable throwable) {
184                if (instanceofLAL) {
185                        ((LocationAwareLogger) logger).log(CATCHING_MARKER, FQCN, LocationAwareLogger.ERROR_INT, "catching", null,
186                                        throwable);
187                }
188        }
189
190        /**
191         * Log an exception being caught allowing the log level to be specified.
192         * 
193         * @param level     the logging level to use.
194         * @param throwable the exception being caught.
195         */
196        public void catching(Level level, Throwable throwable) {
197                if (instanceofLAL) {
198                        ((LocationAwareLogger) logger).log(CATCHING_MARKER, FQCN, level.level, "catching", null, throwable);
199                }
200        }
201
202        private static String buildMessagePattern(int len) {
203                StringBuilder sb = new StringBuilder();
204                sb.append(" entry with (");
205                for (int i = 0; i < len; i++) {
206                        sb.append("{}");
207                        if (i != len - 1)
208                                sb.append(", ");
209                }
210                sb.append(')');
211                return sb.toString();
212        }
213}