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   
18  package 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   * <p style="color: #E40; font-weight: bold;">Please note that this interface is identical to that found in JCL 1.0.4.</p>
59   * 
60   * @author <a href="mailto:sanders@apache.org">Scott Sanders</a>
61   * @author Rod Waldhoff
62   * @version $Id: Log.java,v 1.19 2004/06/06 21:16:04 rdonkin Exp $
63   */
64  public interface Log {
65  
66  
67      // ----------------------------------------------------- Logging Properties
68  
69  
70      /**
71       * <p> Is debug logging currently enabled? </p>
72       *
73       * <p> Call this method to prevent having to perform expensive operations
74       * (for example, <code>String</code> concatenation)
75       * when the log level is more than debug. </p>
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      public boolean isErrorEnabled();
88  
89  
90      /**
91       * <p> Is fatal logging currently enabled? </p>
92       *
93       * <p> Call this method to prevent having to perform expensive operations
94       * (for example, <code>String</code> concatenation)
95       * when the log level is more than fatal. </p>
96       */
97      public boolean isFatalEnabled();
98  
99  
100     /**
101      * <p> Is info logging currently enabled? </p>
102      *
103      * <p> Call this method to prevent having to perform expensive operations
104      * (for example, <code>String</code> concatenation)
105      * when the log level is more than info. </p>
106      */
107     public boolean isInfoEnabled();
108 
109 
110     /**
111      * <p> Is trace logging currently enabled? </p>
112      *
113      * <p> Call this method to prevent having to perform expensive operations
114      * (for example, <code>String</code> concatenation)
115      * when the log level is more than trace. </p>
116      */
117     public boolean isTraceEnabled();
118 
119 
120     /**
121      * <p> Is warn logging currently enabled? </p>
122      *
123      * <p> Call this method to prevent having to perform expensive operations
124      * (for example, <code>String</code> concatenation)
125      * when the log level is more than warn. </p>
126      */
127     public boolean isWarnEnabled();
128 
129 
130     // -------------------------------------------------------- Logging Methods
131 
132 
133     /**
134      * <p> Log a message with trace log level. </p>
135      *
136      * @param message log this message
137      */
138     public void trace(Object message);
139 
140 
141     /**
142      * <p> Log an error with trace log level. </p>
143      *
144      * @param message log this message
145      * @param t log this cause
146      */
147     public void trace(Object message, Throwable t);
148 
149 
150     /**
151      * <p> Log a message with debug log level. </p>
152      *
153      * @param message log this message
154      */
155     public void debug(Object message);
156 
157 
158     /**
159      * <p> Log an error with debug log level. </p>
160      *
161      * @param message log this message
162      * @param t log this cause
163      */
164     public void debug(Object message, Throwable t);
165 
166 
167     /**
168      * <p> Log a message with info log level. </p>
169      *
170      * @param message log this message
171      */
172     public void info(Object message);
173 
174 
175     /**
176      * <p> Log an error with info log level. </p>
177      *
178      * @param message log this message
179      * @param t log this cause
180      */
181     public void info(Object message, Throwable t);
182 
183 
184     /**
185      * <p> Log a message with warn log level. </p>
186      *
187      * @param message log this message
188      */
189     public void warn(Object message);
190 
191 
192     /**
193      * <p> Log an error with warn log level. </p>
194      *
195      * @param message log this message
196      * @param t log this cause
197      */
198     public void warn(Object message, Throwable t);
199 
200 
201     /**
202      * <p> Log a message with error log level. </p>
203      *
204      * @param message log this message
205      */
206     public void error(Object message);
207 
208 
209     /**
210      * <p> Log an error with error log level. </p>
211      *
212      * @param message log this message
213      * @param t log this cause
214      */
215     public void error(Object message, Throwable t);
216 
217 
218     /**
219      * <p> Log a message with fatal log level. </p>
220      *
221      * @param message log this message
222      */
223     public void fatal(Object message);
224 
225 
226     /**
227      * <p> Log an error with fatal log level. </p>
228      *
229      * @param message log this message
230      * @param t log this cause
231      */
232     public void fatal(Object message, Throwable t);
233 
234 
235 }