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    
018    
019    package org.apache.commons.logging;
020    
021    /**
022     * <p>A simple logging interface abstracting logging APIs.  In order to be
023     * instantiated successfully by {@link LogFactory}, classes that implement
024     * this interface must have a constructor that takes a single String
025     * parameter representing the "name" of this Log.</p>
026     *
027     * <p> The six logging levels used by <code>Log</code> are (in order):
028     * <ol>
029     * <li>trace (the least serious)</li>
030     * <li>debug</li>
031     * <li>info</li>
032     * <li>warn</li>
033     * <li>error</li>
034     * <li>fatal (the most serious)</li>
035     * </ol>
036     * The mapping of these log levels to the concepts used by the underlying
037     * logging system is implementation dependent.
038     * The implemention should ensure, though, that this ordering behaves
039     * as expected.</p>
040     *
041     * <p>Performance is often a logging concern.
042     * By examining the appropriate property,
043     * a component can avoid expensive operations (producing information
044     * to be logged).</p>
045     *
046     * <p> For example,
047     * <code><pre>
048     *    if (log.isDebugEnabled()) {
049     *        ... do something expensive ...
050     *        log.debug(theResult);
051     *    }
052     * </pre></code>
053     * </p>
054     *
055     * <p>Configuration of the underlying logging system will generally be done
056     * external to the Logging APIs, through whatever mechanism is supported by
057     * that system.</p>
058     *
059     * @author <a href="mailto:sanders@apache.org">Scott Sanders</a>
060     * @author Rod Waldhoff
061     * @version $Id: Log.java 424107 2006-07-20 23:15:42Z skitching $
062     */
063    public interface Log {
064    
065    
066        // ----------------------------------------------------- Logging Properties
067    
068    
069        /**
070         * <p> Is debug logging currently enabled? </p>
071         *
072         * <p> Call this method to prevent having to perform expensive operations
073         * (for example, <code>String</code> concatenation)
074         * when the log level is more than debug. </p>
075         *
076         * @return true if debug is enabled in the underlying logger.
077         */
078        public boolean isDebugEnabled();
079    
080    
081        /**
082         * <p> Is error logging currently enabled? </p>
083         *
084         * <p> Call this method to prevent having to perform expensive operations
085         * (for example, <code>String</code> concatenation)
086         * when the log level is more than error. </p>
087         *
088         * @return true if error is enabled in the underlying logger.
089         */
090        public boolean isErrorEnabled();
091    
092    
093        /**
094         * <p> Is fatal logging currently enabled? </p>
095         *
096         * <p> Call this method to prevent having to perform expensive operations
097         * (for example, <code>String</code> concatenation)
098         * when the log level is more than fatal. </p>
099         *
100         * @return true if fatal is enabled in the underlying logger.
101         */
102        public boolean isFatalEnabled();
103    
104    
105        /**
106         * <p> Is info logging currently enabled? </p>
107         *
108         * <p> Call this method to prevent having to perform expensive operations
109         * (for example, <code>String</code> concatenation)
110         * when the log level is more than info. </p>
111         *
112         * @return true if info is enabled in the underlying logger.
113         */
114        public boolean isInfoEnabled();
115    
116    
117        /**
118         * <p> Is trace logging currently enabled? </p>
119         *
120         * <p> Call this method to prevent having to perform expensive operations
121         * (for example, <code>String</code> concatenation)
122         * when the log level is more than trace. </p>
123         *
124         * @return true if trace is enabled in the underlying logger.
125         */
126        public boolean isTraceEnabled();
127    
128    
129        /**
130         * <p> Is warn logging currently enabled? </p>
131         *
132         * <p> Call this method to prevent having to perform expensive operations
133         * (for example, <code>String</code> concatenation)
134         * when the log level is more than warn. </p>
135         *
136         * @return true if warn is enabled in the underlying logger.
137         */
138        public boolean isWarnEnabled();
139    
140    
141        // -------------------------------------------------------- Logging Methods
142    
143    
144        /**
145         * <p> Log a message with trace log level. </p>
146         *
147         * @param message log this message
148         */
149        public void trace(Object message);
150    
151    
152        /**
153         * <p> Log an error with trace log level. </p>
154         *
155         * @param message log this message
156         * @param t log this cause
157         */
158        public void trace(Object message, Throwable t);
159    
160    
161        /**
162         * <p> Log a message with debug log level. </p>
163         *
164         * @param message log this message
165         */
166        public void debug(Object message);
167    
168    
169        /**
170         * <p> Log an error with debug log level. </p>
171         *
172         * @param message log this message
173         * @param t log this cause
174         */
175        public void debug(Object message, Throwable t);
176    
177    
178        /**
179         * <p> Log a message with info log level. </p>
180         *
181         * @param message log this message
182         */
183        public void info(Object message);
184    
185    
186        /**
187         * <p> Log an error with info log level. </p>
188         *
189         * @param message log this message
190         * @param t log this cause
191         */
192        public void info(Object message, Throwable t);
193    
194    
195        /**
196         * <p> Log a message with warn log level. </p>
197         *
198         * @param message log this message
199         */
200        public void warn(Object message);
201    
202    
203        /**
204         * <p> Log an error with warn log level. </p>
205         *
206         * @param message log this message
207         * @param t log this cause
208         */
209        public void warn(Object message, Throwable t);
210    
211    
212        /**
213         * <p> Log a message with error log level. </p>
214         *
215         * @param message log this message
216         */
217        public void error(Object message);
218    
219    
220        /**
221         * <p> Log an error with error log level. </p>
222         *
223         * @param message log this message
224         * @param t log this cause
225         */
226        public void error(Object message, Throwable t);
227    
228    
229        /**
230         * <p> Log a message with fatal log level. </p>
231         *
232         * @param message log this message
233         */
234        public void fatal(Object message);
235    
236    
237        /**
238         * <p> Log an error with fatal log level. </p>
239         *
240         * @param message log this message
241         * @param t log this cause
242         */
243        public void fatal(Object message, Throwable t);
244    
245    
246    }