    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *      http://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017
    018package org.apache.commons.logging;
    019
    020/**
    021 * A simple logging interface abstracting logging APIs.  In order to be
    022 * instantiated successfully by {@link LogFactory}, classes that implement
    023 * this interface must have a constructor that takes a single String
    024 * parameter representing the "name" of this Log.
    025 * <p>
    026 * The six logging levels used by {@code Log} are (in order):
    027 * <ol>
    028 * <li>trace (the least serious)</li>
    029 * <li>debug</li>
    030 * <li>info</li>
    031 * <li>warn</li>
    032 * <li>error</li>
    033 * <li>fatal (the most serious)</li>
    034 * </ol>
    035 * The mapping of these log levels to the concepts used by the underlying
    036 * logging system is implementation dependent.
    037 * The implementation should ensure, though, that this ordering behaves
    038 * as expected.
    039 * <p>
    040 * Performance is often a logging concern.
    041 * By examining the appropriate property,
    042 * a component can avoid expensive operations (producing information
    043 * to be logged).
    044 * <p>
    045 * For example,
    046 * <pre>
    047 *    if (log.isDebugEnabled()) {
    048 *        ... do something expensive ...
    049 *        log.debug(theResult);
    050 *    }
    051 * </pre>
    052 * <p>
    053 * Configuration of the underlying logging system will generally be done
    054 * external to the Logging APIs, through whatever mechanism is supported by
    055 * that system.
    056 */
    057public interface Log {
    058
    059    /**
    060     * Logs a message with debug log level.
    061     *
    062     * @param message log this message
    063     */
    064    void debug(Object message);
    065
    066    /**
    067     * Logs an error with debug log level.
    068     *
    069     * @param message log this message
    070     * @param t log this cause
    071     */
    072    void debug(Object message, Throwable t);
    073
    074    /**
    075     * Logs a message with error log level.
    076     *
    077     * @param message log this message
    078     */
    079    void error(Object message);
    080
    081    /**
    082     * Logs an error with error log level.
    083     *
    084     * @param message log this message
    085     * @param t log this cause
    086     */
    087    void error(Object message, Throwable t);
    088
    089    /**
    090     * Logs a message with fatal log level.
    091     *
    092     * @param message log this message
    093     */
    094    void fatal(Object message);
    095
    096    /**
    097     * Logs an error with fatal log level.
    098     *
    099     * @param message log this message
    100     * @param t log this cause
    101     */
    102    void fatal(Object message, Throwable t);
    103
    104    /**
    105     * Logs a message with info log level.
    106     *
    107     * @param message log this message
    108     */
    109    void info(Object message);
    110
    111    /**
    112     * Logs an error with info log level.
    113     *
    114     * @param message log this message
    115     * @param t log this cause
    116     */
    117    void info(Object message, Throwable t);
    118
    119    /**
    120     * Is debug logging currently enabled?
    121     * <p>
    122     * Call this method to prevent having to perform expensive operations
    123     * (for example, {@code String} concatenation)
    124     * when the log level is more than debug.
    125     *
    126     * @return true if debug is enabled in the underlying logger.
    127     */
    128    boolean isDebugEnabled();
    129
    130    /**
    131     * Is error logging currently enabled?
    132     * <p>
    133     * Call this method to prevent having to perform expensive operations
    134     * (for example, {@code String} concatenation)
    135     * when the log level is more than error.
    136     *
    137     * @return true if error is enabled in the underlying logger.
    138     */
    139    boolean isErrorEnabled();
    140
    141    /**
    142     * Is fatal logging currently enabled?
    143     * <p>
    144     * Call this method to prevent having to perform expensive operations
    145     * (for example, {@code String} concatenation)
    146     * when the log level is more than fatal.
    147     *
    148     * @return true if fatal is enabled in the underlying logger.
    149     */
    150    boolean isFatalEnabled();
    151
    152    /**
    153     * Is info logging currently enabled?
    154     * <p>
    155     * Call this method to prevent having to perform expensive operations
    156     * (for example, {@code String} concatenation)
    157     * when the log level is more than info.
    158     *
    159     * @return true if info is enabled in the underlying logger.
    160     */
    161    boolean isInfoEnabled();
    162
    163    /**
    164     * Is trace logging currently enabled?
    165     * <p>
    166     * Call this method to prevent having to perform expensive operations
    167     * (for example, {@code String} concatenation)
    168     * when the log level is more than trace.
    169     *
    170     * @return true if trace is enabled in the underlying logger.
    171     */
    172    boolean isTraceEnabled();
    173
    174    /**
    175     * Is warn logging currently enabled?
    176     * <p>
    177     * Call this method to prevent having to perform expensive operations
    178     * (for example, {@code String} concatenation)
    179     * when the log level is more than warn.
    180     *
    181     * @return true if warn is enabled in the underlying logger.
    182     */
    183    boolean isWarnEnabled();
    184
    185    /**
    186     * Logs a message with trace log level.
    187     *
    188     * @param message log this message
    189     */
    190    void trace(Object message);
    191
    192    /**
    193     * Logs an error with trace log level.
    194     *
    195     * @param message log this message
    196     * @param t log this cause
    197     */
    198    void trace(Object message, Throwable t);
    199
    200    /**
    201     * Logs a message with warn log level.
    202     *
    203     * @param message log this message
    204     */
    205    void warn(Object message);
    206
    207    /**
    208     * Logs an error with warn log level.
    209     *
    210     * @param message log this message
    211     * @param t log this cause
    212     */
    213    void warn(Object message, Throwable t);
    214}