org.apache.logging.log4j.LevelLogger Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache license, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the license for the specific language governing permissions and
* limitations under the license.
*/
package org.apache.logging.log4j;
import org.apache.logging.log4j.message.Message;
import org.apache.logging.log4j.message.MessageFactory;
/**
* This is the central interface in the log4j package. Most logging operations, except configuration, are done through
* this interface.
*
*
* The canonical way to obtain a Logger for a class is through {@link LogManager#getLogger()}. Typically, each class
* gets its own Logger named after its fully qualified class name (the default Logger name when obtained through the
* {@link LogManager#getLogger()} method). Thus, the simplest way to use this would be like so:
*
*
*
* public class MyClass {
* private static final Logger LOGGER = LogManager.getLogger();
* // ...
* }
*
*
* For ease of filtering, searching, sorting, etc., it is generally a good idea to create Loggers for each class rather
* than sharing Loggers. Instead, {@link Marker Markers} should be used for shared, filterable identification.
*
*
* For service provider implementations, it is recommended to extend the
* {@link org.apache.logging.log4j.spi.AbstractLogger} class rather than implementing this interface directly.
*
*/
public interface LevelLogger {
/**
* Logs an exception or error that has been caught. Normally, one may wish to provide additional information with an
* exception while logging it; in these cases, one would not use this method. In other cases where simply logging
* the fact that an exception was swallowed somewhere (e.g., at the top of the stack trace in a {@code main()}
* method), this method is ideal for it.
*
* @param t
* The Throwable.
*/
void catching(Throwable t);
/**
* Logs entry to a method. Used when the method in question has no parameters or when the parameters should not be
* logged.
*/
void entry();
/**
* Logs entry to a method along with its parameters. For example,
*
*
* public void doSomething(String foo, int bar) {
* LOGGER.entry(foo, bar);
* // do something
* }
*
*
* The use of methods such as this are more effective when combined with aspect-oriented programming or other
* bytecode manipulation tools. It can be rather tedious (and messy) to use this type of method manually.
*
*
* @param params
* The parameters to the method. TODO Use of varargs results in array creation which can be a substantial
* portion of no-op case. LogMF/LogSF provides several overrides to avoid vararg except in edge cases. (RG)
* LogMF and LogSF implement these in LogXF which calls logger.callAppenders. callAppenders is part of the
* implementation and cannot be used by the API. Adding more methods here and in AbstractLogger is
* sufficient.
*/
void entry(Object... params);
/**
* Logs exit from a method. Used for methods that do not return anything.
*/
void exit();
/**
* Logs exiting from a method with the result. This may be coded as:
*
*
* return LOGGER.exit(myResult);
*
*
* @param
* The type of the parameter and object being returned.
* @param result
* The result being returned from the method call.
* @return the result.
*/
R exit(R result);
/**
* Gets the Level associated with the Logger.
*
* @return the Level associate with the Logger.
*/
Level getLevel();
/**
* Gets the message factory used to convert message Objects and Strings into actual log Messages.
*
* @return the message factory.
*/
MessageFactory getMessageFactory();
/**
* Gets the logger name.
*
* @return the logger name.
*/
String getName();
/**
* Checks whether this Logger is enabled for the {@link Level#DEBUG DEBUG} Level.
*
* @return boolean - {@code true} if this Logger is enabled for level DEBUG, {@code false} otherwise.
*/
boolean isDebugEnabled();
/**
* Checks whether this Logger is enabled for the {@link Level#DEBUG DEBUG} Level.
*
* @param marker
* The marker data specific to this log statement.
* @return boolean - {@code true} if this Logger is enabled for level DEBUG, {@code false} otherwise.
*/
boolean isDebugEnabled(Marker marker);
/**
* Checks whether this Logger is enabled for the the given Level.
*
* Note that passing in {@link Level#OFF OFF} always returns {@code true}.
*
*
* @return boolean - {@code true} if this Logger is enabled for level, {@code false} otherwise.
*/
boolean isEnabled(Level level);
/**
* Checks whether this logger is enabled at the specified level and an optional Marker.
*
* @param marker
* The marker data specific to this log statement.
* @return boolean - {@code true} if this Logger is enabled for level {@link Level#WARN WARN}, {@code false}
* otherwise.
*/
boolean isEnabled(Marker marker);
/**
* Checks whether this Logger is enabled for the {@link Level#ERROR ERROR} Level.
*
* @return boolean - {@code true} if this Logger is enabled for level {@link Level#ERROR ERROR}, {@code false}
* otherwise.
*/
boolean isErrorEnabled();
/**
* Checks whether this Logger is enabled for the {@link Level#ERROR ERROR} Level.
*
* @param marker
* The marker data specific to this log statement.
* @return boolean - {@code true} if this Logger is enabled for level {@link Level#ERROR ERROR}, {@code false}
* otherwise.
*/
boolean isErrorEnabled(Marker marker);
/**
* Checks whether this Logger is enabled for the {@link Level#FATAL FATAL} Level.
*
* @return boolean - {@code true} if this Logger is enabled for level {@link Level#FATAL FATAL}, {@code false}
* otherwise.
*/
boolean isFatalEnabled();
/**
* Checks whether this Logger is enabled for the {@link Level#FATAL FATAL} Level.
*
* @param marker
* The marker data specific to this log statement.
* @return boolean - {@code true} if this Logger is enabled for level {@link Level#FATAL FATAL}, {@code false}
* otherwise.
*/
boolean isFatalEnabled(Marker marker);
/**
* Checks whether this Logger is enabled for the {@link Level#INFO INFO} Level.
*
* @return boolean - {@code true} if this Logger is enabled for level INFO, {@code false} otherwise.
*/
boolean isInfoEnabled();
/**
* Checks whether this Logger is enabled for the {@link Level#INFO INFO} Level.
*
* @param marker
* The marker data specific to this log statement.
* @return boolean - {@code true} if this Logger is enabled for level INFO, {@code false} otherwise.
*/
boolean isInfoEnabled(Marker marker);
/**
* Checks whether this Logger is enabled for the {@link Level#TRACE TRACE} level.
*
* @return boolean - {@code true} if this Logger is enabled for level TRACE, {@code false} otherwise.
*/
boolean isTraceEnabled();
/**
* Checks whether this Logger is enabled for the {@link Level#TRACE TRACE} level.
*
* @param marker
* The marker data specific to this log statement.
* @return boolean - {@code true} if this Logger is enabled for level TRACE, {@code false} otherwise.
*/
boolean isTraceEnabled(Marker marker);
/**
* Checks whether this Logger is enabled for the {@link Level#WARN WARN} Level.
*
* @return boolean - {@code true} if this Logger is enabled for level {@link Level#WARN WARN}, {@code false}
* otherwise.
*/
boolean isWarnEnabled();
/**
* Checks whether this Logger is enabled for the {@link Level#WARN WARN} Level.
*
* @param marker
* The marker data specific to this log statement.
* @return boolean - {@code true} if this Logger is enabled for level {@link Level#WARN WARN}, {@code false}
* otherwise.
*/
boolean isWarnEnabled(Marker marker);
/**
* Logs a message with the specific Marker at the given level.
*
*
* @param marker
* the marker data specific to this log statement
* @param msg
* the message string to be logged
*/
void log(Marker marker, Message msg);
/**
* Logs a message with the specific Marker at the given level.
*
* @param marker
* the marker data specific to this log statement
* @param msg
* the message string to be logged
* @param t
* A Throwable or null.
*/
void log(Marker marker, Message msg, Throwable t);
/**
* Logs a message object with the given level.
*
* @param marker
* the marker data specific to this log statement
* @param message
* the message object to log.
*/
void log(Marker marker, Object message);
/**
* Logs a message at the given level including the stack trace of the {@link Throwable} t passed as
* parameter.
*
* @param marker
* the marker data specific to this log statement
* @param message
* the message to log.
* @param t
* the exception to log, including its stack trace.
*/
void log(Marker marker, Object message, Throwable t);
/**
* Logs a message object with the given level.
*
*
* @param marker
* the marker data specific to this log statement
* @param message
* the message object to log.
*/
void log(Marker marker, String message);
/**
* Logs a message with parameters at the given level.
*
* @param marker
* the marker data specific to this log statement
* @param message
* the message to log; the format depends on the message factory.
* @param params
* parameters to the message.
* @see #getMessageFactory()
*/
void log(Marker marker, String message, Object... params);
/**
* Logs a message at the given level including the stack trace of the {@link Throwable} t passed as
* parameter.
*
* @param marker
* the marker data specific to this log statement
* @param message
* the message to log.
* @param t
* the exception to log, including its stack trace.
*/
void log(Marker marker, String message, Throwable t);
/**
* Logs a message with the specific Marker at the given level.
*
* @param msg
* the message string to be logged
*/
void log(Message msg);
/**
* Logs a message with the specific Marker at the given level.
*
* @param msg
* the message string to be logged
* @param t
* A Throwable or null.
*/
void log(Message msg, Throwable t);
/**
* Logs a message object with the given level.
*
* @param message
* the message object to log.
*/
void log(Object message);
/**
* Logs a message at the given level including the stack trace of the {@link Throwable} t passed as
* parameter.
*
* @param message
* the message to log.
* @param t
* the exception to log, including its stack trace.
*/
void log(Object message, Throwable t);
/**
* Logs a message object with the given level.
*
* @param message
* the message string to log.
*/
void log(String message);
/**
* Logs a message with parameters at the given level.
*
*
* @param message
* the message to log; the format depends on the message factory.
* @param params
* parameters to the message.
* @see #getMessageFactory()
*/
void log(String message, Object... params);
/**
* Logs a message at the given level including the stack trace of the {@link Throwable} t passed as
* parameter.
*
*
* @param message
* the message to log.
* @param t
* the exception to log, including its stack trace.
*/
void log(String message, Throwable t);
/**
* Logs a formatted message using the specified format string and arguments.
*
*
* @param marker
* the marker data specific to this log statement.
* @param format
* The format String.
* @param params
* Arguments specified by the format.
*/
void printf(Marker marker, String format, Object... params);
/**
* Logs a formatted message using the specified format string and arguments.
*
*
* @param format
* The format String.
* @param params
* Arguments specified by the format.
*/
void printf(String format, Object... params);
/**
* Logs an exception or error to be thrown. This may be coded as:
*
*
* throw logger.throwing(myException);
*
*
* @param
* the Throwable type.
* @param t
* The Throwable.
* @return the Throwable.
*/
T throwing(T t);
}