View Javadoc

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   * @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   */
62  public 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 }