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ülcü
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 }