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