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 * https://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 * </p>
28 * <ol>
29 * <li>trace (the least serious)</li>
30 * <li>debug</li>
31 * <li>info</li>
32 * <li>warn</li>
33 * <li>error</li>
34 * <li>fatal (the most serious)</li>
35 * </ol>
36 * <p>
37 * The mapping of these log levels to the concepts used by the underlying
38 * logging system is implementation dependent.
39 * The implementation should ensure, though, that this ordering behaves
40 * as expected.
41 * </p>
42 * <p>
43 * Performance is often a logging concern.
44 * By examining the appropriate property,
45 * a component can avoid expensive operations (producing information
46 * to be logged).
47 * </p>
48 * <p>
49 * For example:
50 * </p>
51 * <pre>
52 * if (log.isDebugEnabled()) {
53 * ... do something expensive ...
54 * log.debug(theResult);
55 * }
56 * </pre>
57 * <p>
58 * Configuration of the underlying logging system will generally be done
59 * external to the Logging APIs, through whatever mechanism is supported by
60 * that system.
61 * </p>
62 */
63 public interface Log {
64
65 /**
66 * Logs a message with debug log level.
67 *
68 * @param message log this message
69 */
70 void debug(Object message);
71
72 /**
73 * Logs an error with debug log level.
74 *
75 * @param message log this message
76 * @param t log this cause
77 */
78 void debug(Object message, Throwable t);
79
80 /**
81 * Logs a message with error log level.
82 *
83 * @param message log this message
84 */
85 void error(Object message);
86
87 /**
88 * Logs an error with error log level.
89 *
90 * @param message log this message
91 * @param t log this cause
92 */
93 void error(Object message, Throwable t);
94
95 /**
96 * Logs a message with fatal log level.
97 *
98 * @param message log this message
99 */
100 void fatal(Object message);
101
102 /**
103 * Logs an error with fatal log level.
104 *
105 * @param message log this message
106 * @param t log this cause
107 */
108 void fatal(Object message, Throwable t);
109
110 /**
111 * Logs a message with info log level.
112 *
113 * @param message log this message
114 */
115 void info(Object message);
116
117 /**
118 * Logs an error with info log level.
119 *
120 * @param message log this message
121 * @param t log this cause
122 */
123 void info(Object message, Throwable t);
124
125 /**
126 * Is debug logging currently enabled?
127 * <p>
128 * Call this method to prevent having to perform expensive operations
129 * (for example, {@code String} concatenation)
130 * when the log level is more than debug.
131 *
132 * @return true if debug is enabled in the underlying logger.
133 */
134 boolean isDebugEnabled();
135
136 /**
137 * Is error logging currently enabled?
138 * <p>
139 * Call this method to prevent having to perform expensive operations
140 * (for example, {@code String} concatenation)
141 * when the log level is more than error.
142 *
143 * @return true if error is enabled in the underlying logger.
144 */
145 boolean isErrorEnabled();
146
147 /**
148 * Is fatal logging currently enabled?
149 * <p>
150 * Call this method to prevent having to perform expensive operations
151 * (for example, {@code String} concatenation)
152 * when the log level is more than fatal.
153 *
154 * @return true if fatal is enabled in the underlying logger.
155 */
156 boolean isFatalEnabled();
157
158 /**
159 * Is info logging currently enabled?
160 * <p>
161 * Call this method to prevent having to perform expensive operations
162 * (for example, {@code String} concatenation)
163 * when the log level is more than info.
164 *
165 * @return true if info is enabled in the underlying logger.
166 */
167 boolean isInfoEnabled();
168
169 /**
170 * Is trace logging currently enabled?
171 * <p>
172 * Call this method to prevent having to perform expensive operations
173 * (for example, {@code String} concatenation)
174 * when the log level is more than trace.
175 *
176 * @return true if trace is enabled in the underlying logger.
177 */
178 boolean isTraceEnabled();
179
180 /**
181 * Is warn logging currently enabled?
182 * <p>
183 * Call this method to prevent having to perform expensive operations
184 * (for example, {@code String} concatenation)
185 * when the log level is more than warn.
186 *
187 * @return true if warn is enabled in the underlying logger.
188 */
189 boolean isWarnEnabled();
190
191 /**
192 * Logs a message with trace log level.
193 *
194 * @param message log this message
195 */
196 void trace(Object message);
197
198 /**
199 * Logs an error with trace log level.
200 *
201 * @param message log this message
202 * @param t log this cause
203 */
204 void trace(Object message, Throwable t);
205
206 /**
207 * Logs a message with warn log level.
208 *
209 * @param message log this message
210 */
211 void warn(Object message);
212
213 /**
214 * Logs an error with warn log level.
215 *
216 * @param message log this message
217 * @param t log this cause
218 */
219 void warn(Object message, Throwable t);
220 }