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