001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements. See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache license, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License. You may obtain a copy of the License at
008     *
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the license for the specific language governing permissions and
015     * limitations under the license.
016     */
017    package org.apache.logging.log4j;
018    
019    import org.apache.logging.log4j.message.Message;
020    import org.apache.logging.log4j.message.MessageFactory;
021    
022    /**
023     * This is the central interface in the log4j package. Most logging operations, except configuration, are done through
024     * this interface.
025     *
026     * <p>
027     * The canonical way to obtain a Logger for a class is through {@link LogManager#getLogger()}. Typically, each class
028     * gets its own Logger named after its fully qualified class name (the default Logger name when obtained through the
029     * {@link LogManager#getLogger()} method). Thus, the simplest way to use this would be like so:
030     * </p>
031     * 
032     * <pre>
033     * public class MyClass {
034     *     private static final Logger LOGGER = LogManager.getLogger();
035     *     // ...
036     * }
037     * </pre>
038     * <p>
039     * For ease of filtering, searching, sorting, etc., it is generally a good idea to create Loggers for each class rather
040     * than sharing Loggers. Instead, {@link Marker Markers} should be used for shared, filterable identification.
041     * </p>
042     * <p>
043     * For service provider implementations, it is recommended to extend the
044     * {@link org.apache.logging.log4j.spi.AbstractLogger} class rather than implementing this interface directly.
045     * </p>
046     */
047    public interface LevelLogger {
048    
049        /**
050         * Logs an exception or error that has been caught. Normally, one may wish to provide additional information with an
051         * exception while logging it; in these cases, one would not use this method. In other cases where simply logging
052         * the fact that an exception was swallowed somewhere (e.g., at the top of the stack trace in a {@code main()}
053         * method), this method is ideal for it.
054         *
055         * @param t
056         *        The Throwable.
057         */
058        void catching(Throwable t);
059    
060        /**
061         * Logs entry to a method. Used when the method in question has no parameters or when the parameters should not be
062         * logged.
063         */
064        void entry();
065    
066        /**
067         * Logs entry to a method along with its parameters. For example,
068         * 
069         * <pre>
070         * public void doSomething(String foo, int bar) {
071         *     LOGGER.entry(foo, bar);
072         *     // do something
073         * }
074         * </pre>
075         * <p>
076         * The use of methods such as this are more effective when combined with aspect-oriented programming or other
077         * bytecode manipulation tools. It can be rather tedious (and messy) to use this type of method manually.
078         * </p>
079         *
080         * @param params
081         *        The parameters to the method. TODO Use of varargs results in array creation which can be a substantial
082         *        portion of no-op case. LogMF/LogSF provides several overrides to avoid vararg except in edge cases. (RG)
083         *        LogMF and LogSF implement these in LogXF which calls logger.callAppenders. callAppenders is part of the
084         *        implementation and cannot be used by the API. Adding more methods here and in AbstractLogger is
085         *        sufficient.
086         */
087        void entry(Object... params);
088    
089        /**
090         * Logs exit from a method. Used for methods that do not return anything.
091         */
092        void exit();
093    
094        /**
095         * Logs exiting from a method with the result. This may be coded as:
096         * 
097         * <pre>
098         * return LOGGER.exit(myResult);
099         * </pre>
100         *
101         * @param <R>
102         *        The type of the parameter and object being returned.
103         * @param result
104         *        The result being returned from the method call.
105         * @return the result.
106         */
107        <R> R exit(R result);
108    
109        /**
110         * Gets the Level associated with the Logger.
111         *
112         * @return the Level associate with the Logger.
113         */
114        Level getLevel();
115    
116        /**
117         * Gets the message factory used to convert message Objects and Strings into actual log Messages.
118         *
119         * @return the message factory.
120         */
121        MessageFactory getMessageFactory();
122    
123        /**
124         * Gets the logger name.
125         *
126         * @return the logger name.
127         */
128        String getName();
129    
130        /**
131         * Checks whether this Logger is enabled for the {@link Level#DEBUG DEBUG} Level.
132         *
133         * @return boolean - {@code true} if this Logger is enabled for level DEBUG, {@code false} otherwise.
134         */
135        boolean isDebugEnabled();
136    
137        /**
138         * Checks whether this Logger is enabled for the {@link Level#DEBUG DEBUG} Level.
139         *
140         * @param marker
141         *        The marker data specific to this log statement.
142         * @return boolean - {@code true} if this Logger is enabled for level DEBUG, {@code false} otherwise.
143         */
144        boolean isDebugEnabled(Marker marker);
145    
146        /**
147         * Checks whether this Logger is enabled for the the given Level.
148         * <p>
149         * Note that passing in {@link Level#OFF OFF} always returns {@code true}.
150         * </p>
151         *
152         * @return boolean - {@code true} if this Logger is enabled for level, {@code false} otherwise.
153         */
154        boolean isEnabled(Level level);
155    
156        /**
157         * Checks whether this logger is enabled at the specified level and an optional Marker.
158         *
159         * @param marker
160         *        The marker data specific to this log statement.
161         * @return boolean - {@code true} if this Logger is enabled for level {@link Level#WARN WARN}, {@code false}
162         *         otherwise.
163         */
164        boolean isEnabled(Marker marker);
165    
166        /**
167         * Checks whether this Logger is enabled for the {@link Level#ERROR ERROR} Level.
168         *
169         * @return boolean - {@code true} if this Logger is enabled for level {@link Level#ERROR ERROR}, {@code false}
170         *         otherwise.
171         */
172        boolean isErrorEnabled();
173    
174        /**
175         * Checks whether this Logger is enabled for the {@link Level#ERROR ERROR} Level.
176         *
177         * @param marker
178         *        The marker data specific to this log statement.
179         * @return boolean - {@code true} if this Logger is enabled for level {@link Level#ERROR ERROR}, {@code false}
180         *         otherwise.
181         */
182        boolean isErrorEnabled(Marker marker);
183    
184        /**
185         * Checks whether this Logger is enabled for the {@link Level#FATAL FATAL} Level.
186         *
187         * @return boolean - {@code true} if this Logger is enabled for level {@link Level#FATAL FATAL}, {@code false}
188         *         otherwise.
189         */
190        boolean isFatalEnabled();
191    
192        /**
193         * Checks whether this Logger is enabled for the {@link Level#FATAL FATAL} Level.
194         *
195         * @param marker
196         *        The marker data specific to this log statement.
197         * @return boolean - {@code true} if this Logger is enabled for level {@link Level#FATAL FATAL}, {@code false}
198         *         otherwise.
199         */
200        boolean isFatalEnabled(Marker marker);
201    
202        /**
203         * Checks whether this Logger is enabled for the {@link Level#INFO INFO} Level.
204         *
205         * @return boolean - {@code true} if this Logger is enabled for level INFO, {@code false} otherwise.
206         */
207        boolean isInfoEnabled();
208    
209        /**
210         * Checks whether this Logger is enabled for the {@link Level#INFO INFO} Level.
211         *
212         * @param marker
213         *        The marker data specific to this log statement.
214         * @return boolean - {@code true} if this Logger is enabled for level INFO, {@code false} otherwise.
215         */
216        boolean isInfoEnabled(Marker marker);
217    
218        /**
219         * Checks whether this Logger is enabled for the {@link Level#TRACE TRACE} level.
220         *
221         * @return boolean - {@code true} if this Logger is enabled for level TRACE, {@code false} otherwise.
222         */
223        boolean isTraceEnabled();
224    
225        /**
226         * Checks whether this Logger is enabled for the {@link Level#TRACE TRACE} level.
227         *
228         * @param marker
229         *        The marker data specific to this log statement.
230         * @return boolean - {@code true} if this Logger is enabled for level TRACE, {@code false} otherwise.
231         */
232        boolean isTraceEnabled(Marker marker);
233    
234        /**
235         * Checks whether this Logger is enabled for the {@link Level#WARN WARN} Level.
236         *
237         * @return boolean - {@code true} if this Logger is enabled for level {@link Level#WARN WARN}, {@code false}
238         *         otherwise.
239         */
240        boolean isWarnEnabled();
241    
242        /**
243         * Checks whether this Logger is enabled for the {@link Level#WARN WARN} Level.
244         *
245         * @param marker
246         *        The marker data specific to this log statement.
247         * @return boolean - {@code true} if this Logger is enabled for level {@link Level#WARN WARN}, {@code false}
248         *         otherwise.
249         */
250        boolean isWarnEnabled(Marker marker);
251    
252        /**
253         * Logs a message with the specific Marker at the given level.
254         *
255         * 
256         * @param marker
257         *        the marker data specific to this log statement
258         * @param msg
259         *        the message string to be logged
260         */
261        void log(Marker marker, Message msg);
262    
263        /**
264         * Logs a message with the specific Marker at the given level.
265         *
266         * @param marker
267         *        the marker data specific to this log statement
268         * @param msg
269         *        the message string to be logged
270         * @param t
271         *        A Throwable or null.
272         */
273        void log(Marker marker, Message msg, Throwable t);
274    
275        /**
276         * Logs a message object with the given level.
277         *
278         * @param marker
279         *        the marker data specific to this log statement
280         * @param message
281         *        the message object to log.
282         */
283        void log(Marker marker, Object message);
284    
285        /**
286         * Logs a message at the given level including the stack trace of the {@link Throwable} <code>t</code> passed as
287         * parameter.
288         *
289         * @param marker
290         *        the marker data specific to this log statement
291         * @param message
292         *        the message to log.
293         * @param t
294         *        the exception to log, including its stack trace.
295         */
296        void log(Marker marker, Object message, Throwable t);
297    
298        /**
299         * Logs a message object with the given level.
300         *
301         * 
302         * @param marker
303         *        the marker data specific to this log statement
304         * @param message
305         *        the message object to log.
306         */
307        void log(Marker marker, String message);
308    
309        /**
310         * Logs a message with parameters at the given level.
311         *
312         * @param marker
313         *        the marker data specific to this log statement
314         * @param message
315         *        the message to log; the format depends on the message factory.
316         * @param params
317         *        parameters to the message.
318         * @see #getMessageFactory()
319         */
320        void log(Marker marker, String message, Object... params);
321    
322        /**
323         * Logs a message at the given level including the stack trace of the {@link Throwable} <code>t</code> passed as
324         * parameter.
325         *
326         * @param marker
327         *        the marker data specific to this log statement
328         * @param message
329         *        the message to log.
330         * @param t
331         *        the exception to log, including its stack trace.
332         */
333        void log(Marker marker, String message, Throwable t);
334    
335        /**
336         * Logs a message with the specific Marker at the given level.
337         *
338         * @param msg
339         *        the message string to be logged
340         */
341        void log(Message msg);
342    
343        /**
344         * Logs a message with the specific Marker at the given level.
345         *
346         * @param msg
347         *        the message string to be logged
348         * @param t
349         *        A Throwable or null.
350         */
351        void log(Message msg, Throwable t);
352    
353        /**
354         * Logs a message object with the given level.
355         *
356         * @param message
357         *        the message object to log.
358         */
359        void log(Object message);
360    
361        /**
362         * Logs a message at the given level including the stack trace of the {@link Throwable} <code>t</code> passed as
363         * parameter.
364         *
365         * @param message
366         *        the message to log.
367         * @param t
368         *        the exception to log, including its stack trace.
369         */
370        void log(Object message, Throwable t);
371    
372        /**
373         * Logs a message object with the given level.
374         *
375         * @param message
376         *        the message string to log.
377         */
378        void log(String message);
379    
380        /**
381         * Logs a message with parameters at the given level.
382         *
383         * 
384         * @param message
385         *        the message to log; the format depends on the message factory.
386         * @param params
387         *        parameters to the message.
388         * @see #getMessageFactory()
389         */
390        void log(String message, Object... params);
391    
392        /**
393         * Logs a message at the given level including the stack trace of the {@link Throwable} <code>t</code> passed as
394         * parameter.
395         *
396         * 
397         * @param message
398         *        the message to log.
399         * @param t
400         *        the exception to log, including its stack trace.
401         */
402        void log(String message, Throwable t);
403    
404        /**
405         * Logs a formatted message using the specified format string and arguments.
406         *
407         * 
408         * @param marker
409         *        the marker data specific to this log statement.
410         * @param format
411         *        The format String.
412         * @param params
413         *        Arguments specified by the format.
414         */
415        void printf(Marker marker, String format, Object... params);
416    
417        /**
418         * Logs a formatted message using the specified format string and arguments.
419         *
420         * 
421         * @param format
422         *        The format String.
423         * @param params
424         *        Arguments specified by the format.
425         */
426        void printf(String format, Object... params);
427    
428        /**
429         * Logs an exception or error to be thrown. This may be coded as:
430         * 
431         * <pre>
432         * throw logger.throwing(myException);
433         * </pre>
434         *
435         * @param <T>
436         *        the Throwable type.
437         * @param t
438         *        The Throwable.
439         * @return the Throwable.
440         */
441        <T extends Throwable> T throwing(T t);
442    }