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 package org.apache.logging.log4j;
18
19 import org.apache.logging.log4j.message.Message;
20 import org.apache.logging.log4j.message.MessageFactory;
21
22 /**
23 * This is the central interface in the log4j package. Most logging operations, except configuration, are done through
24 * this interface.
25 *
26 * <p>
27 * The canonical way to obtain a Logger for a class is through {@link LogManager#getLogger()}. Typically, each class
28 * gets its own Logger named after its fully qualified class name (the default Logger name when obtained through the
29 * {@link LogManager#getLogger()} method). Thus, the simplest way to use this would be like so:
30 * </p>
31 *
32 * <pre>
33 * public class MyClass {
34 * private static final Logger LOGGER = LogManager.getLogger();
35 * // ...
36 * }
37 * </pre>
38 * <p>
39 * For ease of filtering, searching, sorting, etc., it is generally a good idea to create Loggers for each class rather
40 * than sharing Loggers. Instead, {@link Marker Markers} should be used for shared, filterable identification.
41 * </p>
42 * <p>
43 * For service provider implementations, it is recommended to extend the
44 * {@link org.apache.logging.log4j.spi.AbstractLogger} class rather than implementing this interface directly.
45 * </p>
46 */
47 public interface LevelLogger {
48
49 /**
50 * Logs an exception or error that has been caught. Normally, one may wish to provide additional information with an
51 * exception while logging it; in these cases, one would not use this method. In other cases where simply logging
52 * the fact that an exception was swallowed somewhere (e.g., at the top of the stack trace in a {@code main()}
53 * method), this method is ideal for it.
54 *
55 * @param t
56 * The Throwable.
57 */
58 void catching(Throwable t);
59
60 /**
61 * Logs entry to a method. Used when the method in question has no parameters or when the parameters should not be
62 * logged.
63 */
64 void entry();
65
66 /**
67 * Logs entry to a method along with its parameters. For example,
68 *
69 * <pre>
70 * public void doSomething(String foo, int bar) {
71 * LOGGER.entry(foo, bar);
72 * // do something
73 * }
74 * </pre>
75 * <p>
76 * The use of methods such as this are more effective when combined with aspect-oriented programming or other
77 * bytecode manipulation tools. It can be rather tedious (and messy) to use this type of method manually.
78 * </p>
79 *
80 * @param params
81 * The parameters to the method. TODO Use of varargs results in array creation which can be a substantial
82 * portion of no-op case. LogMF/LogSF provides several overrides to avoid vararg except in edge cases. (RG)
83 * LogMF and LogSF implement these in LogXF which calls logger.callAppenders. callAppenders is part of the
84 * implementation and cannot be used by the API. Adding more methods here and in AbstractLogger is
85 * sufficient.
86 */
87 void entry(Object... params);
88
89 /**
90 * Logs exit from a method. Used for methods that do not return anything.
91 */
92 void exit();
93
94 /**
95 * Logs exiting from a method with the result. This may be coded as:
96 *
97 * <pre>
98 * return LOGGER.exit(myResult);
99 * </pre>
100 *
101 * @param <R>
102 * The type of the parameter and object being returned.
103 * @param result
104 * The result being returned from the method call.
105 * @return the result.
106 */
107 <R> R exit(R result);
108
109 /**
110 * Gets the Level associated with the Logger.
111 *
112 * @return the Level associate with the Logger.
113 */
114 Level getLevel();
115
116 /**
117 * Gets the message factory used to convert message Objects and Strings into actual log Messages.
118 *
119 * @return the message factory.
120 */
121 MessageFactory getMessageFactory();
122
123 /**
124 * Gets the logger name.
125 *
126 * @return the logger name.
127 */
128 String getName();
129
130 /**
131 * Checks whether this Logger is enabled for the {@link Level#DEBUG DEBUG} Level.
132 *
133 * @return boolean - {@code true} if this Logger is enabled for level DEBUG, {@code false} otherwise.
134 */
135 boolean isDebugEnabled();
136
137 /**
138 * Checks whether this Logger is enabled for the {@link Level#DEBUG DEBUG} Level.
139 *
140 * @param marker
141 * The marker data specific to this log statement.
142 * @return boolean - {@code true} if this Logger is enabled for level DEBUG, {@code false} otherwise.
143 */
144 boolean isDebugEnabled(Marker marker);
145
146 /**
147 * Checks whether this Logger is enabled for the the given Level.
148 * <p>
149 * Note that passing in {@link Level#OFF OFF} always returns {@code true}.
150 * </p>
151 *
152 * @return boolean - {@code true} if this Logger is enabled for level, {@code false} otherwise.
153 */
154 boolean isEnabled(Level level);
155
156 /**
157 * Checks whether this logger is enabled at the specified level and an optional Marker.
158 *
159 * @param marker
160 * The marker data specific to this log statement.
161 * @return boolean - {@code true} if this Logger is enabled for level {@link Level#WARN WARN}, {@code false}
162 * otherwise.
163 */
164 boolean isEnabled(Marker marker);
165
166 /**
167 * Checks whether this Logger is enabled for the {@link Level#ERROR ERROR} Level.
168 *
169 * @return boolean - {@code true} if this Logger is enabled for level {@link Level#ERROR ERROR}, {@code false}
170 * otherwise.
171 */
172 boolean isErrorEnabled();
173
174 /**
175 * Checks whether this Logger is enabled for the {@link Level#ERROR ERROR} Level.
176 *
177 * @param marker
178 * The marker data specific to this log statement.
179 * @return boolean - {@code true} if this Logger is enabled for level {@link Level#ERROR ERROR}, {@code false}
180 * otherwise.
181 */
182 boolean isErrorEnabled(Marker marker);
183
184 /**
185 * Checks whether this Logger is enabled for the {@link Level#FATAL FATAL} Level.
186 *
187 * @return boolean - {@code true} if this Logger is enabled for level {@link Level#FATAL FATAL}, {@code false}
188 * otherwise.
189 */
190 boolean isFatalEnabled();
191
192 /**
193 * Checks whether this Logger is enabled for the {@link Level#FATAL FATAL} Level.
194 *
195 * @param marker
196 * The marker data specific to this log statement.
197 * @return boolean - {@code true} if this Logger is enabled for level {@link Level#FATAL FATAL}, {@code false}
198 * otherwise.
199 */
200 boolean isFatalEnabled(Marker marker);
201
202 /**
203 * Checks whether this Logger is enabled for the {@link Level#INFO INFO} Level.
204 *
205 * @return boolean - {@code true} if this Logger is enabled for level INFO, {@code false} otherwise.
206 */
207 boolean isInfoEnabled();
208
209 /**
210 * Checks whether this Logger is enabled for the {@link Level#INFO INFO} Level.
211 *
212 * @param marker
213 * The marker data specific to this log statement.
214 * @return boolean - {@code true} if this Logger is enabled for level INFO, {@code false} otherwise.
215 */
216 boolean isInfoEnabled(Marker marker);
217
218 /**
219 * Checks whether this Logger is enabled for the {@link Level#TRACE TRACE} level.
220 *
221 * @return boolean - {@code true} if this Logger is enabled for level TRACE, {@code false} otherwise.
222 */
223 boolean isTraceEnabled();
224
225 /**
226 * Checks whether this Logger is enabled for the {@link Level#TRACE TRACE} level.
227 *
228 * @param marker
229 * The marker data specific to this log statement.
230 * @return boolean - {@code true} if this Logger is enabled for level TRACE, {@code false} otherwise.
231 */
232 boolean isTraceEnabled(Marker marker);
233
234 /**
235 * Checks whether this Logger is enabled for the {@link Level#WARN WARN} Level.
236 *
237 * @return boolean - {@code true} if this Logger is enabled for level {@link Level#WARN WARN}, {@code false}
238 * otherwise.
239 */
240 boolean isWarnEnabled();
241
242 /**
243 * Checks whether this Logger is enabled for the {@link Level#WARN WARN} Level.
244 *
245 * @param marker
246 * The marker data specific to this log statement.
247 * @return boolean - {@code true} if this Logger is enabled for level {@link Level#WARN WARN}, {@code false}
248 * otherwise.
249 */
250 boolean isWarnEnabled(Marker marker);
251
252 /**
253 * Logs a message with the specific Marker at the given level.
254 *
255 *
256 * @param marker
257 * the marker data specific to this log statement
258 * @param msg
259 * the message string to be logged
260 */
261 void log(Marker marker, Message msg);
262
263 /**
264 * Logs a message with the specific Marker at the given level.
265 *
266 * @param marker
267 * the marker data specific to this log statement
268 * @param msg
269 * the message string to be logged
270 * @param t
271 * A Throwable or null.
272 */
273 void log(Marker marker, Message msg, Throwable t);
274
275 /**
276 * Logs a message object with the given level.
277 *
278 * @param marker
279 * the marker data specific to this log statement
280 * @param message
281 * the message object to log.
282 */
283 void log(Marker marker, Object message);
284
285 /**
286 * Logs a message at the given level including the stack trace of the {@link Throwable} <code>t</code> passed as
287 * parameter.
288 *
289 * @param marker
290 * the marker data specific to this log statement
291 * @param message
292 * the message to log.
293 * @param t
294 * the exception to log, including its stack trace.
295 */
296 void log(Marker marker, Object message, Throwable t);
297
298 /**
299 * Logs a message object with the given level.
300 *
301 *
302 * @param marker
303 * the marker data specific to this log statement
304 * @param message
305 * the message object to log.
306 */
307 void log(Marker marker, String message);
308
309 /**
310 * Logs a message with parameters at the given level.
311 *
312 * @param marker
313 * the marker data specific to this log statement
314 * @param message
315 * the message to log; the format depends on the message factory.
316 * @param params
317 * parameters to the message.
318 * @see #getMessageFactory()
319 */
320 void log(Marker marker, String message, Object... params);
321
322 /**
323 * Logs a message at the given level including the stack trace of the {@link Throwable} <code>t</code> passed as
324 * parameter.
325 *
326 * @param marker
327 * the marker data specific to this log statement
328 * @param message
329 * the message to log.
330 * @param t
331 * the exception to log, including its stack trace.
332 */
333 void log(Marker marker, String message, Throwable t);
334
335 /**
336 * Logs a message with the specific Marker at the given level.
337 *
338 * @param msg
339 * the message string to be logged
340 */
341 void log(Message msg);
342
343 /**
344 * Logs a message with the specific Marker at the given level.
345 *
346 * @param msg
347 * the message string to be logged
348 * @param t
349 * A Throwable or null.
350 */
351 void log(Message msg, Throwable t);
352
353 /**
354 * Logs a message object with the given level.
355 *
356 * @param message
357 * the message object to log.
358 */
359 void log(Object message);
360
361 /**
362 * Logs a message at the given level including the stack trace of the {@link Throwable} <code>t</code> passed as
363 * parameter.
364 *
365 * @param message
366 * the message to log.
367 * @param t
368 * the exception to log, including its stack trace.
369 */
370 void log(Object message, Throwable t);
371
372 /**
373 * Logs a message object with the given level.
374 *
375 * @param message
376 * the message string to log.
377 */
378 void log(String message);
379
380 /**
381 * Logs a message with parameters at the given level.
382 *
383 *
384 * @param message
385 * the message to log; the format depends on the message factory.
386 * @param params
387 * parameters to the message.
388 * @see #getMessageFactory()
389 */
390 void log(String message, Object... params);
391
392 /**
393 * Logs a message at the given level including the stack trace of the {@link Throwable} <code>t</code> passed as
394 * parameter.
395 *
396 *
397 * @param message
398 * the message to log.
399 * @param t
400 * the exception to log, including its stack trace.
401 */
402 void log(String message, Throwable t);
403
404 /**
405 * Logs a formatted message using the specified format string and arguments.
406 *
407 *
408 * @param marker
409 * the marker data specific to this log statement.
410 * @param format
411 * The format String.
412 * @param params
413 * Arguments specified by the format.
414 */
415 void printf(Marker marker, String format, Object... params);
416
417 /**
418 * Logs a formatted message using the specified format string and arguments.
419 *
420 *
421 * @param format
422 * The format String.
423 * @param params
424 * Arguments specified by the format.
425 */
426 void printf(String format, Object... params);
427
428 /**
429 * Logs an exception or error to be thrown. This may be coded as:
430 *
431 * <pre>
432 * throw logger.throwing(myException);
433 * </pre>
434 *
435 * @param <T>
436 * the Throwable type.
437 * @param t
438 * The Throwable.
439 * @return the Throwable.
440 */
441 <T extends Throwable> T throwing(T t);
442 }