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</code> 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 *
057 * @version $Id: Log.html 915605 2014-07-09 20:22:43Z tn $
058 */
059public interface Log {
060
061    /**
062     * Logs a message with debug log level.
063     *
064     * @param message log this message
065     */
066    void debug(Object message);
067
068    /**
069     * Logs an error with debug log level.
070     *
071     * @param message log this message
072     * @param t log this cause
073     */
074    void debug(Object message, Throwable t);
075
076    /**
077     * Logs a message with error log level.
078     *
079     * @param message log this message
080     */
081    void error(Object message);
082
083    /**
084     * Logs an error with error log level.
085     *
086     * @param message log this message
087     * @param t log this cause
088     */
089    void error(Object message, Throwable t);
090
091    /**
092     * Logs a message with fatal log level.
093     *
094     * @param message log this message
095     */
096    void fatal(Object message);
097
098    /**
099     * Logs an error with fatal log level.
100     *
101     * @param message log this message
102     * @param t log this cause
103     */
104    void fatal(Object message, Throwable t);
105
106    /**
107     * Logs a message with info log level.
108     *
109     * @param message log this message
110     */
111    void info(Object message);
112
113    /**
114     * Logs an error with info log level.
115     *
116     * @param message log this message
117     * @param t log this cause
118     */
119    void info(Object message, Throwable t);
120
121    /**
122     * Is debug logging currently enabled?
123     * <p>
124     * Call this method to prevent having to perform expensive operations
125     * (for example, <code>String</code> concatenation)
126     * when the log level is more than debug.
127     *
128     * @return true if debug is enabled in the underlying logger.
129     */
130    boolean isDebugEnabled();
131
132    /**
133     * Is error logging currently enabled?
134     * <p>
135     * Call this method to prevent having to perform expensive operations
136     * (for example, <code>String</code> concatenation)
137     * when the log level is more than error.
138     *
139     * @return true if error is enabled in the underlying logger.
140     */
141    boolean isErrorEnabled();
142
143    /**
144     * Is fatal logging currently enabled?
145     * <p>
146     * Call this method to prevent having to perform expensive operations
147     * (for example, <code>String</code> concatenation)
148     * when the log level is more than fatal.
149     *
150     * @return true if fatal is enabled in the underlying logger.
151     */
152    boolean isFatalEnabled();
153
154    /**
155     * Is info logging currently enabled?
156     * <p>
157     * Call this method to prevent having to perform expensive operations
158     * (for example, <code>String</code> concatenation)
159     * when the log level is more than info.
160     *
161     * @return true if info is enabled in the underlying logger.
162     */
163    boolean isInfoEnabled();
164
165    /**
166     * Is trace logging currently enabled?
167     * <p>
168     * Call this method to prevent having to perform expensive operations
169     * (for example, <code>String</code> concatenation)
170     * when the log level is more than trace.
171     *
172     * @return true if trace is enabled in the underlying logger.
173     */
174    boolean isTraceEnabled();
175
176    /**
177     * Is warn logging currently enabled?
178     * <p>
179     * Call this method to prevent having to perform expensive operations
180     * (for example, <code>String</code> concatenation)
181     * when the log level is more than warn.
182     *
183     * @return true if warn is enabled in the underlying logger.
184     */
185    boolean isWarnEnabled();
186
187    /**
188     * Logs a message with trace log level.
189     *
190     * @param message log this message
191     */
192    void trace(Object message);
193
194    /**
195     * Logs an error with trace log level.
196     *
197     * @param message log this message
198     * @param t log this cause
199     */
200    void trace(Object message, Throwable t);
201
202    /**
203     * Logs a message with warn log level.
204     *
205     * @param message log this message
206     */
207    void warn(Object message);
208
209    /**
210     * Logs an error with warn log level.
211     *
212     * @param message log this message
213     * @param t log this cause
214     */
215    void warn(Object message, Throwable t);
216}