1/*
2 * Copyright 2001-2004 The Apache Software Foundation.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17
18package org.apache.commons.logging;
19
20/**
21 * <p>A simple logging interface abstracting logging APIs.  In order to be
22 * instantiated successfully by {@link LogFactory}, classes that implement
23 * this interface must have a constructor that takes a single String
24 * parameter representing the "name" of this Log.</p>
25 *
26 * <p> The six logging levels used by <code>Log</code> are (in order):
27 * <ol>
28 * <li>trace (the least serious)</li>
29 * <li>debug</li>
30 * <li>info</li>
31 * <li>warn</li>
32 * <li>error</li>
33 * <li>fatal (the most serious)</li>
34 * </ol>
35 * The mapping of these log levels to the concepts used by the underlying
36 * logging system is implementation dependent.
37 * The implemention should ensure, though, that this ordering behaves
38 * as expected.</p>
39 *
40 * <p>Performance is often a logging concern.
41 * By examining the appropriate property,
42 * a component can avoid expensive operations (producing information
43 * to be logged).</p>
44 *
45 * <p> For example,
46 * <code><pre>
47 *    if (log.isDebugEnabled()) {
48 *        ... do something expensive ...
49 *        log.debug(theResult);
50 *    }
51 * </pre></code>
52 * </p>
53 *
54 * <p>Configuration of the underlying logging system will generally be done
55 * external to the Logging APIs, through whatever mechanism is supported by
56 * that system.</p>
57 *
58 * @author <a href="mailto:sanders@apache.org">Scott Sanders</a>
59 * @author Rod Waldhoff
60 * @version $Id: Log.java 381838 2006-02-28 23:57:11Z skitching $
61 */
62public interface Log {
63
64
65    // ----------------------------------------------------- Logging Properties
66
67
68    /**
69     * <p> Is debug logging currently enabled? </p>
70     *
71     * <p> Call this method to prevent having to perform expensive operations
72     * (for example, <code>String</code> concatenation)
73     * when the log level is more than debug. </p>
74     *
75     * @return true if debug is enabled in the underlying logger.
76     */
77    public boolean isDebugEnabled();
78
79
80    /**
81     * <p> Is error logging currently enabled? </p>
82     *
83     * <p> Call this method to prevent having to perform expensive operations
84     * (for example, <code>String</code> concatenation)
85     * when the log level is more than error. </p>
86     *
87     * @return true if error is enabled in the underlying logger.
88     */
89    public boolean isErrorEnabled();
90
91
92    /**
93     * <p> Is fatal logging currently enabled? </p>
94     *
95     * <p> Call this method to prevent having to perform expensive operations
96     * (for example, <code>String</code> concatenation)
97     * when the log level is more than fatal. </p>
98     *
99     * @return true if fatal is enabled in the underlying logger.
100     */
101    public boolean isFatalEnabled();
102
103
104    /**
105     * <p> Is info logging currently enabled? </p>
106     *
107     * <p> Call this method to prevent having to perform expensive operations
108     * (for example, <code>String</code> concatenation)
109     * when the log level is more than info. </p>
110     *
111     * @return true if info is enabled in the underlying logger.
112     */
113    public boolean isInfoEnabled();
114
115
116    /**
117     * <p> Is trace logging currently enabled? </p>
118     *
119     * <p> Call this method to prevent having to perform expensive operations
120     * (for example, <code>String</code> concatenation)
121     * when the log level is more than trace. </p>
122     *
123     * @return true if trace is enabled in the underlying logger.
124     */
125    public boolean isTraceEnabled();
126
127
128    /**
129     * <p> Is warn logging currently enabled? </p>
130     *
131     * <p> Call this method to prevent having to perform expensive operations
132     * (for example, <code>String</code> concatenation)
133     * when the log level is more than warn. </p>
134     *
135     * @return true if warn is enabled in the underlying logger.
136     */
137    public boolean isWarnEnabled();
138
139
140    // -------------------------------------------------------- Logging Methods
141
142
143    /**
144     * <p> Log a message with trace log level. </p>
145     *
146     * @param message log this message
147     */
148    public void trace(Object message);
149
150
151    /**
152     * <p> Log an error with trace log level. </p>
153     *
154     * @param message log this message
155     * @param t log this cause
156     */
157    public void trace(Object message, Throwable t);
158
159
160    /**
161     * <p> Log a message with debug log level. </p>
162     *
163     * @param message log this message
164     */
165    public void debug(Object message);
166
167
168    /**
169     * <p> Log an error with debug log level. </p>
170     *
171     * @param message log this message
172     * @param t log this cause
173     */
174    public void debug(Object message, Throwable t);
175
176
177    /**
178     * <p> Log a message with info log level. </p>
179     *
180     * @param message log this message
181     */
182    public void info(Object message);
183
184
185    /**
186     * <p> Log an error with info log level. </p>
187     *
188     * @param message log this message
189     * @param t log this cause
190     */
191    public void info(Object message, Throwable t);
192
193
194    /**
195     * <p> Log a message with warn log level. </p>
196     *
197     * @param message log this message
198     */
199    public void warn(Object message);
200
201
202    /**
203     * <p> Log an error with warn log level. </p>
204     *
205     * @param message log this message
206     * @param t log this cause
207     */
208    public void warn(Object message, Throwable t);
209
210
211    /**
212     * <p> Log a message with error log level. </p>
213     *
214     * @param message log this message
215     */
216    public void error(Object message);
217
218
219    /**
220     * <p> Log an error with error log level. </p>
221     *
222     * @param message log this message
223     * @param t log this cause
224     */
225    public void error(Object message, Throwable t);
226
227
228    /**
229     * <p> Log a message with fatal log level. </p>
230     *
231     * @param message log this message
232     */
233    public void fatal(Object message);
234
235
236    /**
237     * <p> Log an error with fatal log level. </p>
238     *
239     * @param message log this message
240     * @param t log this cause
241     */
242    public void fatal(Object message, Throwable t);
243
244
245}
246