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 }