View Javadoc

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   */
25  
26  package org.slf4j;
27  
28  /**
29   * The org.slf4j.Logger interface is the main user entry point of SLF4J API.
30   * It is expected that logging takes place through concrete implementations
31   * of this interface.
32   * <p/>
33   * <h3>Typical usage pattern:</h3>
34   * <pre>
35   * import org.slf4j.Logger;
36   * import org.slf4j.LoggerFactory;
37   *
38   * public class Wombat {
39   *
40   *   <span style="color:green">final static Logger logger = LoggerFactory.getLogger(Wombat.class);</span>
41   *   Integer t;
42   *   Integer oldT;
43   *
44   *   public void setTemperature(Integer temperature) {
45   *     oldT = t;
46   *     t = temperature;
47   *     <span style="color:green">logger.debug("Temperature set to {}. Old temperature was {}.", t, oldT);</span>
48   *     if(temperature.intValue() > 50) {
49   *       <span style="color:green">logger.info("Temperature has risen above 50 degrees.");</span>
50   *     }
51   *   }
52   * }
53   * </pre>
54   *
55   * Be sure to read the FAQ entry relating to <a href="../../../faq.html#logging_performance">parameterized
56   * logging</a>. Note that logging statements can be parameterized in
57   * <a href="../../../faq.html#paramException">presence of an exception/throwable</a>.
58   *
59   * <p>Once you are comfortable using loggers, i.e. instances of this interface, consider using
60   * <a href="MDC.html">MDC</a> as well as <a href="Marker.html">Markers</a>.</p>
61   *
62   * @author Ceki G&uuml;lc&uuml;
63   */
64  public interface Logger {
65  
66      /**
67       * Case insensitive String constant used to retrieve the name of the root logger.
68       *
69       * @since 1.3
70       */
71      final public String ROOT_LOGGER_NAME = "ROOT";
72  
73      /**
74       * Return the name of this <code>Logger</code> instance.
75       * @return name of this logger instance 
76       */
77      public String getName();
78  
79      /**
80       * Is the logger instance enabled for the TRACE level?
81       *
82       * @return True if this Logger is enabled for the TRACE level,
83       *         false otherwise.
84       * @since 1.4
85       */
86      public boolean isTraceEnabled();
87  
88      /**
89       * Log a message at the TRACE level.
90       *
91       * @param msg the message string to be logged
92       * @since 1.4
93       */
94      public void trace(String msg);
95  
96      /**
97       * Log a message at the TRACE level according to the specified format
98       * and argument.
99       * <p/>
100      * <p>This form avoids superfluous object creation when the logger
101      * is disabled for the TRACE level. </p>
102      *
103      * @param format the format string
104      * @param arg    the argument
105      * @since 1.4
106      */
107     public void trace(String format, Object arg);
108 
109     /**
110      * Log a message at the TRACE level according to the specified format
111      * and arguments.
112      * <p/>
113      * <p>This form avoids superfluous object creation when the logger
114      * is disabled for the TRACE level. </p>
115      *
116      * @param format the format string
117      * @param arg1   the first argument
118      * @param arg2   the second argument
119      * @since 1.4
120      */
121     public void trace(String format, Object arg1, Object arg2);
122 
123     /**
124      * Log a message at the TRACE level according to the specified format
125      * and arguments.
126      * <p/>
127      * <p>This form avoids superfluous string concatenation when the logger
128      * is disabled for the TRACE level. However, this variant incurs the hidden
129      * (and relatively small) cost of creating an <code>Object[]</code> before invoking the method,
130      * even if this logger is disabled for TRACE. The variants taking {@link #trace(String, Object) one} and
131      * {@link #trace(String, Object, Object) two} arguments exist solely in order to avoid this hidden cost.</p>
132      *
133      * @param format    the format string
134      * @param arguments a list of 3 or more arguments
135      * @since 1.4
136      */
137     public void trace(String format, Object... arguments);
138 
139     /**
140      * Log an exception (throwable) at the TRACE level with an
141      * accompanying message.
142      *
143      * @param msg the message accompanying the exception
144      * @param t   the exception (throwable) to log
145      * @since 1.4
146      */
147     public void trace(String msg, Throwable t);
148 
149     /**
150      * Similar to {@link #isTraceEnabled()} method except that the
151      * marker data is also taken into account.
152      *
153      * @param marker The marker data to take into consideration
154      * @return True if this Logger is enabled for the TRACE level,
155      *         false otherwise.
156      *         
157      * @since 1.4
158      */
159     public boolean isTraceEnabled(Marker marker);
160 
161     /**
162      * Log a message with the specific Marker at the TRACE level.
163      *
164      * @param marker the marker data specific to this log statement
165      * @param msg    the message string to be logged
166      * @since 1.4
167      */
168     public void trace(Marker marker, String msg);
169 
170     /**
171      * This method is similar to {@link #trace(String, Object)} method except that the
172      * marker data is also taken into consideration.
173      *
174      * @param marker the marker data specific to this log statement
175      * @param format the format string
176      * @param arg    the argument
177      * @since 1.4
178      */
179     public void trace(Marker marker, String format, Object arg);
180 
181     /**
182      * This method is similar to {@link #trace(String, Object, Object)}
183      * method except that the marker data is also taken into
184      * consideration.
185      *
186      * @param marker the marker data specific to this log statement
187      * @param format the format string
188      * @param arg1   the first argument
189      * @param arg2   the second argument
190      * @since 1.4
191      */
192     public void trace(Marker marker, String format, Object arg1, Object arg2);
193 
194     /**
195      * This method is similar to {@link #trace(String, Object...)}
196      * method except that the marker data is also taken into
197      * consideration.
198      *
199      * @param marker   the marker data specific to this log statement
200      * @param format   the format string
201      * @param argArray an array of arguments
202      * @since 1.4
203      */
204     public void trace(Marker marker, String format, Object... argArray);
205 
206     /**
207      * This method is similar to {@link #trace(String, Throwable)} method except that the
208      * marker data is also taken into consideration.
209      *
210      * @param marker the marker data specific to this log statement
211      * @param msg    the message accompanying the exception
212      * @param t      the exception (throwable) to log
213      * @since 1.4
214      */
215     public void trace(Marker marker, String msg, Throwable t);
216 
217     /**
218      * Is the logger instance enabled for the DEBUG level?
219      *
220      * @return True if this Logger is enabled for the DEBUG level,
221      *         false otherwise.
222      */
223     public boolean isDebugEnabled();
224 
225     /**
226      * Log a message at the DEBUG level.
227      *
228      * @param msg the message string to be logged
229      */
230     public void debug(String msg);
231 
232     /**
233      * Log a message at the DEBUG level according to the specified format
234      * and argument.
235      * <p/>
236      * <p>This form avoids superfluous object creation when the logger
237      * is disabled for the DEBUG level. </p>
238      *
239      * @param format the format string
240      * @param arg    the argument
241      */
242     public void debug(String format, Object arg);
243 
244     /**
245      * Log a message at the DEBUG level according to the specified format
246      * and arguments.
247      * <p/>
248      * <p>This form avoids superfluous object creation when the logger
249      * is disabled for the DEBUG level. </p>
250      *
251      * @param format the format string
252      * @param arg1   the first argument
253      * @param arg2   the second argument
254      */
255     public void debug(String format, Object arg1, Object arg2);
256 
257     /**
258      * Log a message at the DEBUG level according to the specified format
259      * and arguments.
260      * <p/>
261      * <p>This form avoids superfluous string concatenation when the logger
262      * is disabled for the DEBUG level. However, this variant incurs the hidden
263      * (and relatively small) cost of creating an <code>Object[]</code> before invoking the method,
264      * even if this logger is disabled for DEBUG. The variants taking
265      * {@link #debug(String, Object) one} and {@link #debug(String, Object, Object) two}
266      * arguments exist solely in order to avoid this hidden cost.</p>
267      *
268      * @param format    the format string
269      * @param arguments a list of 3 or more arguments
270      */
271     public void debug(String format, Object... arguments);
272 
273     /**
274      * Log an exception (throwable) at the DEBUG level with an
275      * accompanying message.
276      *
277      * @param msg the message accompanying the exception
278      * @param t   the exception (throwable) to log
279      */
280     public void debug(String msg, Throwable t);
281 
282     /**
283      * Similar to {@link #isDebugEnabled()} method except that the
284      * marker data is also taken into account.
285      *
286      * @param marker The marker data to take into consideration
287      * @return True if this Logger is enabled for the DEBUG level,
288      *         false otherwise. 
289      */
290     public boolean isDebugEnabled(Marker marker);
291 
292     /**
293      * Log a message with the specific Marker at the DEBUG level.
294      *
295      * @param marker the marker data specific to this log statement
296      * @param msg    the message string to be logged
297      */
298     public void debug(Marker marker, String msg);
299 
300     /**
301      * This method is similar to {@link #debug(String, Object)} method except that the
302      * marker data is also taken into consideration.
303      *
304      * @param marker the marker data specific to this log statement
305      * @param format the format string
306      * @param arg    the argument
307      */
308     public void debug(Marker marker, String format, Object arg);
309 
310     /**
311      * This method is similar to {@link #debug(String, Object, Object)}
312      * method except that the marker data is also taken into
313      * consideration.
314      *
315      * @param marker the marker data specific to this log statement
316      * @param format the format string
317      * @param arg1   the first argument
318      * @param arg2   the second argument
319      */
320     public void debug(Marker marker, String format, Object arg1, Object arg2);
321 
322     /**
323      * This method is similar to {@link #debug(String, Object...)}
324      * method except that the marker data is also taken into
325      * consideration.
326      *
327      * @param marker    the marker data specific to this log statement
328      * @param format    the format string
329      * @param arguments a list of 3 or more arguments
330      */
331     public void debug(Marker marker, String format, Object... arguments);
332 
333     /**
334      * This method is similar to {@link #debug(String, Throwable)} method except that the
335      * marker data is also taken into consideration.
336      *
337      * @param marker the marker data specific to this log statement
338      * @param msg    the message accompanying the exception
339      * @param t      the exception (throwable) to log
340      */
341     public void debug(Marker marker, String msg, Throwable t);
342 
343     /**
344      * Is the logger instance enabled for the INFO level?
345      *
346      * @return True if this Logger is enabled for the INFO level,
347      *         false otherwise.
348      */
349     public boolean isInfoEnabled();
350 
351     /**
352      * Log a message at the INFO level.
353      *
354      * @param msg the message string to be logged
355      */
356     public void info(String msg);
357 
358     /**
359      * Log a message at the INFO level according to the specified format
360      * and argument.
361      * <p/>
362      * <p>This form avoids superfluous object creation when the logger
363      * is disabled for the INFO level. </p>
364      *
365      * @param format the format string
366      * @param arg    the argument
367      */
368     public void info(String format, Object arg);
369 
370     /**
371      * Log a message at the INFO level according to the specified format
372      * and arguments.
373      * <p/>
374      * <p>This form avoids superfluous object creation when the logger
375      * is disabled for the INFO level. </p>
376      *
377      * @param format the format string
378      * @param arg1   the first argument
379      * @param arg2   the second argument
380      */
381     public void info(String format, Object arg1, Object arg2);
382 
383     /**
384      * Log a message at the INFO level according to the specified format
385      * and arguments.
386      * <p/>
387      * <p>This form avoids superfluous string concatenation when the logger
388      * is disabled for the INFO level. However, this variant incurs the hidden
389      * (and relatively small) cost of creating an <code>Object[]</code> before invoking the method,
390      * even if this logger is disabled for INFO. The variants taking
391      * {@link #info(String, Object) one} and {@link #info(String, Object, Object) two}
392      * arguments exist solely in order to avoid this hidden cost.</p>
393      *
394      * @param format    the format string
395      * @param arguments a list of 3 or more arguments
396      */
397     public void info(String format, Object... arguments);
398 
399     /**
400      * Log an exception (throwable) at the INFO level with an
401      * accompanying message.
402      *
403      * @param msg the message accompanying the exception
404      * @param t   the exception (throwable) to log
405      */
406     public void info(String msg, Throwable t);
407 
408     /**
409      * Similar to {@link #isInfoEnabled()} method except that the marker
410      * data is also taken into consideration.
411      *
412      * @param marker The marker data to take into consideration
413      * @return true if this logger is warn enabled, false otherwise 
414      */
415     public boolean isInfoEnabled(Marker marker);
416 
417     /**
418      * Log a message with the specific Marker at the INFO level.
419      *
420      * @param marker The marker specific to this log statement
421      * @param msg    the message string to be logged
422      */
423     public void info(Marker marker, String msg);
424 
425     /**
426      * This method is similar to {@link #info(String, Object)} method except that the
427      * marker data is also taken into consideration.
428      *
429      * @param marker the marker data specific to this log statement
430      * @param format the format string
431      * @param arg    the argument
432      */
433     public void info(Marker marker, String format, Object arg);
434 
435     /**
436      * This method is similar to {@link #info(String, Object, Object)}
437      * method except that the marker data is also taken into
438      * consideration.
439      *
440      * @param marker the marker data specific to this log statement
441      * @param format the format string
442      * @param arg1   the first argument
443      * @param arg2   the second argument
444      */
445     public void info(Marker marker, String format, Object arg1, Object arg2);
446 
447     /**
448      * This method is similar to {@link #info(String, Object...)}
449      * method except that the marker data is also taken into
450      * consideration.
451      *
452      * @param marker    the marker data specific to this log statement
453      * @param format    the format string
454      * @param arguments a list of 3 or more arguments
455      */
456     public void info(Marker marker, String format, Object... arguments);
457 
458     /**
459      * This method is similar to {@link #info(String, Throwable)} method
460      * except that the marker data is also taken into consideration.
461      *
462      * @param marker the marker data for this log statement
463      * @param msg    the message accompanying the exception
464      * @param t      the exception (throwable) to log
465      */
466     public void info(Marker marker, String msg, Throwable t);
467 
468     /**
469      * Is the logger instance enabled for the WARN level?
470      *
471      * @return True if this Logger is enabled for the WARN level,
472      *         false otherwise.
473      */
474     public boolean isWarnEnabled();
475 
476     /**
477      * Log a message at the WARN level.
478      *
479      * @param msg the message string to be logged
480      */
481     public void warn(String msg);
482 
483     /**
484      * Log a message at the WARN level according to the specified format
485      * and argument.
486      * <p/>
487      * <p>This form avoids superfluous object creation when the logger
488      * is disabled for the WARN level. </p>
489      *
490      * @param format the format string
491      * @param arg    the argument
492      */
493     public void warn(String format, Object arg);
494 
495     /**
496      * Log a message at the WARN level according to the specified format
497      * and arguments.
498      * <p/>
499      * <p>This form avoids superfluous string concatenation when the logger
500      * is disabled for the WARN level. However, this variant incurs the hidden
501      * (and relatively small) cost of creating an <code>Object[]</code> before invoking the method,
502      * even if this logger is disabled for WARN. The variants taking
503      * {@link #warn(String, Object) one} and {@link #warn(String, Object, Object) two}
504      * arguments exist solely in order to avoid this hidden cost.</p>
505      *
506      * @param format    the format string
507      * @param arguments a list of 3 or more arguments
508      */
509     public void warn(String format, Object... arguments);
510 
511     /**
512      * Log a message at the WARN level according to the specified format
513      * and arguments.
514      * <p/>
515      * <p>This form avoids superfluous object creation when the logger
516      * is disabled for the WARN level. </p>
517      *
518      * @param format the format string
519      * @param arg1   the first argument
520      * @param arg2   the second argument
521      */
522     public void warn(String format, Object arg1, Object arg2);
523 
524     /**
525      * Log an exception (throwable) at the WARN level with an
526      * accompanying message.
527      *
528      * @param msg the message accompanying the exception
529      * @param t   the exception (throwable) to log
530      */
531     public void warn(String msg, Throwable t);
532 
533     /**
534      * Similar to {@link #isWarnEnabled()} method except that the marker
535      * data is also taken into consideration.
536      *
537      * @param marker The marker data to take into consideration
538      * @return True if this Logger is enabled for the WARN level,
539      *         false otherwise.
540      */
541     public boolean isWarnEnabled(Marker marker);
542 
543     /**
544      * Log a message with the specific Marker at the WARN level.
545      *
546      * @param marker The marker specific to this log statement
547      * @param msg    the message string to be logged
548      */
549     public void warn(Marker marker, String msg);
550 
551     /**
552      * This method is similar to {@link #warn(String, Object)} method except that the
553      * marker data is also taken into consideration.
554      *
555      * @param marker the marker data specific to this log statement
556      * @param format the format string
557      * @param arg    the argument
558      */
559     public void warn(Marker marker, String format, Object arg);
560 
561     /**
562      * This method is similar to {@link #warn(String, Object, Object)}
563      * method except that the marker data is also taken into
564      * consideration.
565      *
566      * @param marker the marker data specific to this log statement
567      * @param format the format string
568      * @param arg1   the first argument
569      * @param arg2   the second argument
570      */
571     public void warn(Marker marker, String format, Object arg1, Object arg2);
572 
573     /**
574      * This method is similar to {@link #warn(String, Object...)}
575      * method except that the marker data is also taken into
576      * consideration.
577      *
578      * @param marker    the marker data specific to this log statement
579      * @param format    the format string
580      * @param arguments a list of 3 or more arguments
581      */
582     public void warn(Marker marker, String format, Object... arguments);
583 
584     /**
585      * This method is similar to {@link #warn(String, Throwable)} method
586      * except that the marker data is also taken into consideration.
587      *
588      * @param marker the marker data for this log statement
589      * @param msg    the message accompanying the exception
590      * @param t      the exception (throwable) to log
591      */
592     public void warn(Marker marker, String msg, Throwable t);
593 
594     /**
595      * Is the logger instance enabled for the ERROR level?
596      *
597      * @return True if this Logger is enabled for the ERROR level,
598      *         false otherwise.
599      */
600     public boolean isErrorEnabled();
601 
602     /**
603      * Log a message at the ERROR level.
604      *
605      * @param msg the message string to be logged
606      */
607     public void error(String msg);
608 
609     /**
610      * Log a message at the ERROR level according to the specified format
611      * and argument.
612      * <p/>
613      * <p>This form avoids superfluous object creation when the logger
614      * is disabled for the ERROR level. </p>
615      *
616      * @param format the format string
617      * @param arg    the argument
618      */
619     public void error(String format, Object arg);
620 
621     /**
622      * Log a message at the ERROR level according to the specified format
623      * and arguments.
624      * <p/>
625      * <p>This form avoids superfluous object creation when the logger
626      * is disabled for the ERROR level. </p>
627      *
628      * @param format the format string
629      * @param arg1   the first argument
630      * @param arg2   the second argument
631      */
632     public void error(String format, Object arg1, Object arg2);
633 
634     /**
635      * Log a message at the ERROR level according to the specified format
636      * and arguments.
637      * <p/>
638      * <p>This form avoids superfluous string concatenation when the logger
639      * is disabled for the ERROR level. However, this variant incurs the hidden
640      * (and relatively small) cost of creating an <code>Object[]</code> before invoking the method,
641      * even if this logger is disabled for ERROR. The variants taking
642      * {@link #error(String, Object) one} and {@link #error(String, Object, Object) two}
643      * arguments exist solely in order to avoid this hidden cost.</p>
644      *
645      * @param format    the format string
646      * @param arguments a list of 3 or more arguments
647      */
648     public void error(String format, Object... arguments);
649 
650     /**
651      * Log an exception (throwable) at the ERROR level with an
652      * accompanying message.
653      *
654      * @param msg the message accompanying the exception
655      * @param t   the exception (throwable) to log
656      */
657     public void error(String msg, Throwable t);
658 
659     /**
660      * Similar to {@link #isErrorEnabled()} method except that the
661      * marker data is also taken into consideration.
662      *
663      * @param marker The marker data to take into consideration
664      * @return True if this Logger is enabled for the ERROR level,
665      *         false otherwise.
666      */
667     public boolean isErrorEnabled(Marker marker);
668 
669     /**
670      * Log a message with the specific Marker at the ERROR level.
671      *
672      * @param marker The marker specific to this log statement
673      * @param msg    the message string to be logged
674      */
675     public void error(Marker marker, String msg);
676 
677     /**
678      * This method is similar to {@link #error(String, Object)} method except that the
679      * marker data is also taken into consideration.
680      *
681      * @param marker the marker data specific to this log statement
682      * @param format the format string
683      * @param arg    the argument
684      */
685     public void error(Marker marker, String format, Object arg);
686 
687     /**
688      * This method is similar to {@link #error(String, Object, Object)}
689      * method except that the marker data is also taken into
690      * consideration.
691      *
692      * @param marker the marker data specific to this log statement
693      * @param format the format string
694      * @param arg1   the first argument
695      * @param arg2   the second argument
696      */
697     public void error(Marker marker, String format, Object arg1, Object arg2);
698 
699     /**
700      * This method is similar to {@link #error(String, Object...)}
701      * method except that the marker data is also taken into
702      * consideration.
703      *
704      * @param marker    the marker data specific to this log statement
705      * @param format    the format string
706      * @param arguments a list of 3 or more arguments
707      */
708     public void error(Marker marker, String format, Object... arguments);
709 
710     /**
711      * This method is similar to {@link #error(String, Throwable)}
712      * method except that the marker data is also taken into
713      * consideration.
714      *
715      * @param marker the marker data specific to this log statement
716      * @param msg    the message accompanying the exception
717      * @param t      the exception (throwable) to log
718      */
719     public void error(Marker marker, String msg, Throwable t);
720 
721 }