    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 *      https://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 * </p>
    028 * <ol>
    029 * <li>trace (the least serious)</li>
    030 * <li>debug</li>
    031 * <li>info</li>
    032 * <li>warn</li>
    033 * <li>error</li>
    034 * <li>fatal (the most serious)</li>
    035 * </ol>
    036 * <p>
    037 * The mapping of these log levels to the concepts used by the underlying
    038 * logging system is implementation dependent.
    039 * The implementation should ensure, though, that this ordering behaves
    040 * as expected.
    041 * </p>
    042 * <p>
    043 * Performance is often a logging concern.
    044 * By examining the appropriate property,
    045 * a component can avoid expensive operations (producing information
    046 * to be logged).
    047 * </p>
    048 * <p>
    049 * For example:
    050 * </p>
    051 * <pre>
    052 *    if (log.isDebugEnabled()) {
    053 *        ... do something expensive ...
    054 *        log.debug(theResult);
    055 *    }
    056 * </pre>
    057 * <p>
    058 * Configuration of the underlying logging system will generally be done
    059 * external to the Logging APIs, through whatever mechanism is supported by
    060 * that system.
    061 * </p>
    062 */
    063public interface Log {
    064
    065    /**
    066     * Logs a message with debug log level.
    067     *
    068     * @param message log this message
    069     */
    070    void debug(Object message);
    071
    072    /**
    073     * Logs an error with debug log level.
    074     *
    075     * @param message log this message
    076     * @param t log this cause
    077     */
    078    void debug(Object message, Throwable t);
    079
    080    /**
    081     * Logs a message with error log level.
    082     *
    083     * @param message log this message
    084     */
    085    void error(Object message);
    086
    087    /**
    088     * Logs an error with error log level.
    089     *
    090     * @param message log this message
    091     * @param t log this cause
    092     */
    093    void error(Object message, Throwable t);
    094
    095    /**
    096     * Logs a message with fatal log level.
    097     *
    098     * @param message log this message
    099     */
    100    void fatal(Object message);
    101
    102    /**
    103     * Logs an error with fatal log level.
    104     *
    105     * @param message log this message
    106     * @param t log this cause
    107     */
    108    void fatal(Object message, Throwable t);
    109
    110    /**
    111     * Logs a message with info log level.
    112     *
    113     * @param message log this message
    114     */
    115    void info(Object message);
    116
    117    /**
    118     * Logs an error with info log level.
    119     *
    120     * @param message log this message
    121     * @param t log this cause
    122     */
    123    void info(Object message, Throwable t);
    124
    125    /**
    126     * Is debug logging currently enabled?
    127     * <p>
    128     * Call this method to prevent having to perform expensive operations
    129     * (for example, {@code String} concatenation)
    130     * when the log level is more than debug.
    131     *
    132     * @return true if debug is enabled in the underlying logger.
    133     */
    134    boolean isDebugEnabled();
    135
    136    /**
    137     * Is error logging currently enabled?
    138     * <p>
    139     * Call this method to prevent having to perform expensive operations
    140     * (for example, {@code String} concatenation)
    141     * when the log level is more than error.
    142     *
    143     * @return true if error is enabled in the underlying logger.
    144     */
    145    boolean isErrorEnabled();
    146
    147    /**
    148     * Is fatal logging currently enabled?
    149     * <p>
    150     * Call this method to prevent having to perform expensive operations
    151     * (for example, {@code String} concatenation)
    152     * when the log level is more than fatal.
    153     *
    154     * @return true if fatal is enabled in the underlying logger.
    155     */
    156    boolean isFatalEnabled();
    157
    158    /**
    159     * Is info logging currently enabled?
    160     * <p>
    161     * Call this method to prevent having to perform expensive operations
    162     * (for example, {@code String} concatenation)
    163     * when the log level is more than info.
    164     *
    165     * @return true if info is enabled in the underlying logger.
    166     */
    167    boolean isInfoEnabled();
    168
    169    /**
    170     * Is trace logging currently enabled?
    171     * <p>
    172     * Call this method to prevent having to perform expensive operations
    173     * (for example, {@code String} concatenation)
    174     * when the log level is more than trace.
    175     *
    176     * @return true if trace is enabled in the underlying logger.
    177     */
    178    boolean isTraceEnabled();
    179
    180    /**
    181     * Is warn logging currently enabled?
    182     * <p>
    183     * Call this method to prevent having to perform expensive operations
    184     * (for example, {@code String} concatenation)
    185     * when the log level is more than warn.
    186     *
    187     * @return true if warn is enabled in the underlying logger.
    188     */
    189    boolean isWarnEnabled();
    190
    191    /**
    192     * Logs a message with trace log level.
    193     *
    194     * @param message log this message
    195     */
    196    void trace(Object message);
    197
    198    /**
    199     * Logs an error with trace log level.
    200     *
    201     * @param message log this message
    202     * @param t log this cause
    203     */
    204    void trace(Object message, Throwable t);
    205
    206    /**
    207     * Logs a message with warn log level.
    208     *
    209     * @param message log this message
    210     */
    211    void warn(Object message);
    212
    213    /**
    214     * Logs an error with warn log level.
    215     *
    216     * @param message log this message
    217     * @param t log this cause
    218     */
    219    void warn(Object message, Throwable t);
    220}