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