Logger xref

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 }