View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.apache.commons.logging;
19  
20  /**
21   * 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.
25   * <p>
26   * The six logging levels used by {@code Log} 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 implementation should ensure, though, that this ordering behaves
38   * as expected.
39   * <p>
40   * 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).
44   * <p>
45   * For example,
46   * <pre>
47   *    if (log.isDebugEnabled()) {
48   *        ... do something expensive ...
49   *        log.debug(theResult);
50   *    }
51   * </pre>
52   * <p>
53   * Configuration of the underlying logging system will generally be done
54   * external to the Logging APIs, through whatever mechanism is supported by
55   * that system.
56   */
57  public interface Log {
58  
59      /**
60       * Logs a message with debug log level.
61       *
62       * @param message log this message
63       */
64      void debug(Object message);
65  
66      /**
67       * Logs an error with debug log level.
68       *
69       * @param message log this message
70       * @param t log this cause
71       */
72      void debug(Object message, Throwable t);
73  
74      /**
75       * Logs a message with error log level.
76       *
77       * @param message log this message
78       */
79      void error(Object message);
80  
81      /**
82       * Logs an error with error log level.
83       *
84       * @param message log this message
85       * @param t log this cause
86       */
87      void error(Object message, Throwable t);
88  
89      /**
90       * Logs a message with fatal log level.
91       *
92       * @param message log this message
93       */
94      void fatal(Object message);
95  
96      /**
97       * Logs an error with fatal log level.
98       *
99       * @param message log this message
100      * @param t log this cause
101      */
102     void fatal(Object message, Throwable t);
103 
104     /**
105      * Logs a message with info log level.
106      *
107      * @param message log this message
108      */
109     void info(Object message);
110 
111     /**
112      * Logs an error with info log level.
113      *
114      * @param message log this message
115      * @param t log this cause
116      */
117     void info(Object message, Throwable t);
118 
119     /**
120      * Is debug logging currently enabled?
121      * <p>
122      * Call this method to prevent having to perform expensive operations
123      * (for example, {@code String} concatenation)
124      * when the log level is more than debug.
125      *
126      * @return true if debug is enabled in the underlying logger.
127      */
128     boolean isDebugEnabled();
129 
130     /**
131      * Is error logging currently enabled?
132      * <p>
133      * Call this method to prevent having to perform expensive operations
134      * (for example, {@code String} concatenation)
135      * when the log level is more than error.
136      *
137      * @return true if error is enabled in the underlying logger.
138      */
139     boolean isErrorEnabled();
140 
141     /**
142      * Is fatal logging currently enabled?
143      * <p>
144      * Call this method to prevent having to perform expensive operations
145      * (for example, {@code String} concatenation)
146      * when the log level is more than fatal.
147      *
148      * @return true if fatal is enabled in the underlying logger.
149      */
150     boolean isFatalEnabled();
151 
152     /**
153      * Is info logging currently enabled?
154      * <p>
155      * Call this method to prevent having to perform expensive operations
156      * (for example, {@code String} concatenation)
157      * when the log level is more than info.
158      *
159      * @return true if info is enabled in the underlying logger.
160      */
161     boolean isInfoEnabled();
162 
163     /**
164      * Is trace logging currently enabled?
165      * <p>
166      * Call this method to prevent having to perform expensive operations
167      * (for example, {@code String} concatenation)
168      * when the log level is more than trace.
169      *
170      * @return true if trace is enabled in the underlying logger.
171      */
172     boolean isTraceEnabled();
173 
174     /**
175      * Is warn logging currently enabled?
176      * <p>
177      * Call this method to prevent having to perform expensive operations
178      * (for example, {@code String} concatenation)
179      * when the log level is more than warn.
180      *
181      * @return true if warn is enabled in the underlying logger.
182      */
183     boolean isWarnEnabled();
184 
185     /**
186      * Logs a message with trace log level.
187      *
188      * @param message log this message
189      */
190     void trace(Object message);
191 
192     /**
193      * Logs an error with trace log level.
194      *
195      * @param message log this message
196      * @param t log this cause
197      */
198     void trace(Object message, Throwable t);
199 
200     /**
201      * Logs a message with warn log level.
202      *
203      * @param message log this message
204      */
205     void warn(Object message);
206 
207     /**
208      * Logs an error with warn log level.
209      *
210      * @param message log this message
211      * @param t log this cause
212      */
213     void warn(Object message, Throwable t);
214 }