    001/**
    002 * Copyright (c) 2004-2011 QOS.ch
    003 * All rights reserved.
    004 *
    005 * Permission is hereby granted, free  of charge, to any person obtaining
    006 * a  copy  of this  software  and  associated  documentation files  (the
    007 * "Software"), to  deal in  the Software without  restriction, including
    008 * without limitation  the rights to  use, copy, modify,  merge, publish,
    009 * distribute,  sublicense, and/or sell  copies of  the Software,  and to
    010 * permit persons to whom the Software  is furnished to do so, subject to
    011 * the following conditions:
    012 *
    013 * The  above  copyright  notice  and  this permission  notice  shall  be
    014 * included in all copies or substantial portions of the Software.
    015 *
    016 * THE  SOFTWARE IS  PROVIDED  "AS  IS", WITHOUT  WARRANTY  OF ANY  KIND,
    017 * EXPRESS OR  IMPLIED, INCLUDING  BUT NOT LIMITED  TO THE  WARRANTIES OF
    018 * MERCHANTABILITY,    FITNESS    FOR    A   PARTICULAR    PURPOSE    AND
    019 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
    020 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
    021 * OF CONTRACT, TORT OR OTHERWISE,  ARISING FROM, OUT OF OR IN CONNECTION
    022 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
    023 *
    024 */
    025
    026package org.slf4j;
    027
    028/**
    029 * The org.slf4j.Logger interface is the main user entry point of SLF4J API.
    030 * It is expected that logging takes place through concrete implementations
    031 * of this interface.
    032 * <p/>
    033 * <h3>Typical usage pattern:</h3>
    034 * <pre>
    035 * import org.slf4j.Logger;
    036 * import org.slf4j.LoggerFactory;
    037 *
    038 * public class Wombat {
    039 *
    040 *   <span style="color:green">final static Logger logger = LoggerFactory.getLogger(Wombat.class);</span>
    041 *   Integer t;
    042 *   Integer oldT;
    043 *
    044 *   public void setTemperature(Integer temperature) {
    045 *     oldT = t;
    046 *     t = temperature;
    047 *     <span style="color:green">logger.debug("Temperature set to {}. Old temperature was {}.", t, oldT);</span>
    048 *     if(temperature.intValue() > 50) {
    049 *       <span style="color:green">logger.info("Temperature has risen above 50 degrees.");</span>
    050 *     }
    051 *   }
    052 * }
    053 * </pre>
    054 *
    055 * Be sure to read the FAQ entry relating to <a href="../../../faq.html#logging_performance">parameterized
    056 * logging</a>. Note that logging statements can be parameterized in
    057 * <a href="../../../faq.html#paramException">presence of an exception/throwable</a>.
    058 *
    059 * <p>Once you are comfortable using loggers, i.e. instances of this interface, consider using
    060 * <a href="MDC.html">MDC</a> as well as <a href="Marker.html">Markers</a>.</p>
    061 *
    062 * @author Ceki G&uuml;lc&uuml;
    063 */
    064public interface Logger {
    065
    066    /**
    067     * Case insensitive String constant used to retrieve the name of the root logger.
    068     *
    069     * @since 1.3
    070     */
    071    final public String ROOT_LOGGER_NAME = "ROOT";
    072
    073    /**
    074     * Return the name of this <code>Logger</code> instance.
    075     * @return name of this logger instance
    076     */
    077    public String getName();
    078
    079    /**
    080     * Is the logger instance enabled for the TRACE level?
    081     *
    082     * @return True if this Logger is enabled for the TRACE level,
    083     *         false otherwise.
    084     * @since 1.4
    085     */
    086    public boolean isTraceEnabled();
    087
    088    /**
    089     * Log a message at the TRACE level.
    090     *
    091     * @param msg the message string to be logged
    092     * @since 1.4
    093     */
    094    public void trace(String msg);
    095
    096    /**
    097     * Log a message at the TRACE level according to the specified format
    098     * and argument.
    099     * <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}