[
https://issues.apache.org/jira/browse/LOG4J2-519?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Remko Popma updated LOG4J2-519:
-------------------------------
Attachment: Generate.java
Attached a first attempt at a source code generator (Generate.java).
Usage:
Command to generate a wrapper that extends AbstractLoggerWrapper:
{{java org.apache.logging.log4j.util.Generate$ExtendedLogger
com.mycomp.ExtLogger DIAG=350 NOTICE=450 VERBOSE=550}}
Command to generate a wrapper that only provides convenience methods for the
specified custom levels (and hides the convenience methods for the built-in
levels):
{{java org.apache.logging.log4j.util.Generate$CustomLogger com.mycomp.MyLogger
DEFCON1=350 DEFCON2=450 DEFCON3=550}}
Example generated source:
{code}
package com.mycomp;
import org.apache.logging.log4j.Level;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import org.apache.logging.log4j.Marker;
import org.apache.logging.log4j.message.Message;
import org.apache.logging.log4j.message.MessageFactory;
import org.apache.logging.log4j.spi.AbstractLogger;
import org.apache.logging.log4j.spi.AbstractLoggerWrapper;
/**
* Extended Logger interface with convenience methods for
* the DIAG, NOTICE and VERBOSE custom log levels.
*/
public final class ExtLogger extends AbstractLoggerWrapper {
private static final long serialVersionUID = 216489351472874L;
private static final Level DIAG = Level.getOrCreateLevel("DIAG", 350);
private static final Level NOTICE = Level.getOrCreateLevel("NOTICE", 450);
private static final Level VERBOSE = Level.getOrCreateLevel("VERBOSE", 550);
private ExtLogger(final Logger logger) {
super((AbstractLogger) logger, logger.getName(),
logger.getMessageFactory());
}
/**
* Returns a custom Logger with the name of the calling class.
*
* @return The custom Logger for the calling class.
*/
public static ExtLogger create() {
final Logger wrapped = LogManager.getLogger();
return new ExtLogger(wrapped);
}
/**
* Returns a custom Logger using the fully qualified name of the Class as
* the Logger name.
*
* @param loggerName The Class whose name should be used as the Logger name.
* If null it will default to the calling class.
* @return The custom Logger.
*/
public static ExtLogger create(final Class<?> loggerName) {
final Logger wrapped = LogManager.getLogger(loggerName);
return new ExtLogger(wrapped);
}
/**
* Returns a custom Logger using the fully qualified name of the Class as
* the Logger name.
*
* @param loggerName The Class whose name should be used as the Logger name.
* If null it will default to the calling class.
* @param messageFactory The message factory is used only when creating a
* logger, subsequent use does not change the logger but will log
* a warning if mismatched.
* @return The custom Logger.
*/
public static ExtLogger create(final Class<?> loggerName, final
MessageFactory factory) {
final Logger wrapped = LogManager.getLogger(loggerName, factory);
return new ExtLogger(wrapped);
}
/**
* Returns a custom Logger using the fully qualified class name of the value
* as the Logger name.
*
* @param value The value whose class name should be used as the Logger
* name. If null the name of the calling class will be used as
* the logger name.
* @return The custom Logger.
*/
public static ExtLogger create(final Object value) {
final Logger wrapped = LogManager.getLogger(value);
return new ExtLogger(wrapped);
}
/**
* Returns a custom Logger using the fully qualified class name of the value
* as the Logger name.
*
* @param value The value whose class name should be used as the Logger
* name. If null the name of the calling class will be used as
* the logger name.
* @param messageFactory The message factory is used only when creating a
* logger, subsequent use does not change the logger but will log
* a warning if mismatched.
* @return The custom Logger.
*/
public static ExtLogger create(final Object value, final MessageFactory
factory) {
final Logger wrapped = LogManager.getLogger(value, factory);
return new ExtLogger(wrapped);
}
/**
* Returns a custom Logger with the specified name.
*
* @param name The logger name. If null the name of the calling class will
* be used.
* @return The custom Logger.
*/
public static ExtLogger create(final String name) {
final Logger wrapped = LogManager.getLogger(name);
return new ExtLogger(wrapped);
}
/**
* Returns a custom Logger with the specified name.
*
* @param name The logger name. If null the name of the calling class will
* be used.
* @param messageFactory The message factory is used only when creating a
* logger, subsequent use does not change the logger but will log
* a warning if mismatched.
* @return The custom Logger.
*/
public static ExtLogger create(final String name, final MessageFactory
factory) {
final Logger wrapped = LogManager.getLogger(name, factory);
return new ExtLogger(wrapped);
}
/**
* Logs a message with the specific Marker at the {@code DIAG} level.
*
* @param marker the marker data specific to this log statement
* @param msg the message string to be logged
*/
public void diag(final Marker marker, final Message msg) {
logger.log(DIAG, marker, msg);
}
/**
* Logs a message with the specific Marker at the {@code DIAG} 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.
*/
public void diag(final Marker marker, final Message msg, final Throwable t)
{
logger.log(DIAG, marker, msg, t);
}
/**
* Logs a message object with the {@code DIAG} level.
*
* @param marker the marker data specific to this log statement
* @param message the message object to log.
*/
public void diag(final Marker marker, final Object message) {
logger.log(DIAG, marker, message);
}
/**
* Logs a message at the {@code DIAG} level including the stack trace of
* the {@link Throwable} {@code 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.
*/
public void diag(final Marker marker, final Object message, final Throwable
t) {
logger.log(DIAG, marker, message, t);
}
/**
* Logs a message object with the {@code DIAG} level.
*
* @param marker the marker data specific to this log statement
* @param message the message object to log.
*/
public void diag(final Marker marker, final String message) {
logger.log(DIAG, marker, message);
}
/**
* Logs a message with parameters at the {@code DIAG} 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()
*/
public void diag(final Marker marker, final String message, final Object...
params) {
logger.log(DIAG, marker, message, params);
}
/**
* Logs a message at the {@code DIAG} level including the stack trace of
* the {@link Throwable} {@code 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.
*/
public void diag(final Marker marker, final String message, final Throwable
t) {
logger.log(DIAG, marker, message, t);
}
/**
* Logs a message with the specific Marker at the {@code DIAG} level.
*
* @param msg the message string to be logged
*/
public void diag(final Message msg) {
logger.log(DIAG, msg);
}
/**
* Logs a message with the specific Marker at the {@code DIAG} level.
*
* @param msg the message string to be logged
* @param t A Throwable or null.
*/
public void diag(final Message msg, final Throwable t) {
logger.log(DIAG, msg, t);
}
/**
* Logs a message object with the {@code DIAG} level.
*
* @param message the message object to log.
*/
public void diag(final Object message) {
logger.log(DIAG, message);
}
/**
* Logs a message at the {@code DIAG} level including the stack trace of
* the {@link Throwable} {@code t} passed as parameter.
*
* @param message the message to log.
* @param t the exception to log, including its stack trace.
*/
public void diag(final Object message, final Throwable t) {
logger.log(DIAG, message, t);
}
/**
* Logs a message object with the {@code DIAG} level.
*
* @param message the message object to log.
*/
public void diag(final String message) {
logger.log(DIAG, message);
}
/**
* Logs a message with parameters at the {@code DIAG} level.
*
* @param message the message to log; the format depends on the message
factory.
* @param params parameters to the message.
* @see #getMessageFactory()
*/
public void diag(final String message, final Object... params) {
logger.log(DIAG, message, params);
}
/**
* Logs a message at the {@code DIAG} level including the stack trace of
* the {@link Throwable} {@code t} passed as parameter.
*
* @param message the message to log.
* @param t the exception to log, including its stack trace.
*/
public void diag(final String message, final Throwable t) {
logger.log(DIAG, message, t);
}
/**
* Logs a message with the specific Marker at the {@code NOTICE} level.
*
* @param marker the marker data specific to this log statement
* @param msg the message string to be logged
*/
public void notice(final Marker marker, final Message msg) {
logger.log(NOTICE, marker, msg);
}
/**
* Logs a message with the specific Marker at the {@code NOTICE} 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.
*/
public void notice(final Marker marker, final Message msg, final Throwable
t) {
logger.log(NOTICE, marker, msg, t);
}
/**
* Logs a message object with the {@code NOTICE} level.
*
* @param marker the marker data specific to this log statement
* @param message the message object to log.
*/
public void notice(final Marker marker, final Object message) {
logger.log(NOTICE, marker, message);
}
/**
* Logs a message at the {@code NOTICE} level including the stack trace of
* the {@link Throwable} {@code 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.
*/
public void notice(final Marker marker, final Object message, final
Throwable t) {
logger.log(NOTICE, marker, message, t);
}
/**
* Logs a message object with the {@code NOTICE} level.
*
* @param marker the marker data specific to this log statement
* @param message the message object to log.
*/
public void notice(final Marker marker, final String message) {
logger.log(NOTICE, marker, message);
}
/**
* Logs a message with parameters at the {@code NOTICE} 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()
*/
public void notice(final Marker marker, final String message, final
Object... params) {
logger.log(NOTICE, marker, message, params);
}
/**
* Logs a message at the {@code NOTICE} level including the stack trace of
* the {@link Throwable} {@code 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.
*/
public void notice(final Marker marker, final String message, final
Throwable t) {
logger.log(NOTICE, marker, message, t);
}
/**
* Logs a message with the specific Marker at the {@code NOTICE} level.
*
* @param msg the message string to be logged
*/
public void notice(final Message msg) {
logger.log(NOTICE, msg);
}
/**
* Logs a message with the specific Marker at the {@code NOTICE} level.
*
* @param msg the message string to be logged
* @param t A Throwable or null.
*/
public void notice(final Message msg, final Throwable t) {
logger.log(NOTICE, msg, t);
}
/**
* Logs a message object with the {@code NOTICE} level.
*
* @param message the message object to log.
*/
public void notice(final Object message) {
logger.log(NOTICE, message);
}
/**
* Logs a message at the {@code NOTICE} level including the stack trace of
* the {@link Throwable} {@code t} passed as parameter.
*
* @param message the message to log.
* @param t the exception to log, including its stack trace.
*/
public void notice(final Object message, final Throwable t) {
logger.log(NOTICE, message, t);
}
/**
* Logs a message object with the {@code NOTICE} level.
*
* @param message the message object to log.
*/
public void notice(final String message) {
logger.log(NOTICE, message);
}
/**
* Logs a message with parameters at the {@code NOTICE} level.
*
* @param message the message to log; the format depends on the message
factory.
* @param params parameters to the message.
* @see #getMessageFactory()
*/
public void notice(final String message, final Object... params) {
logger.log(NOTICE, message, params);
}
/**
* Logs a message at the {@code NOTICE} level including the stack trace of
* the {@link Throwable} {@code t} passed as parameter.
*
* @param message the message to log.
* @param t the exception to log, including its stack trace.
*/
public void notice(final String message, final Throwable t) {
logger.log(NOTICE, message, t);
}
/**
* Logs a message with the specific Marker at the {@code VERBOSE} level.
*
* @param marker the marker data specific to this log statement
* @param msg the message string to be logged
*/
public void verbose(final Marker marker, final Message msg) {
logger.log(VERBOSE, marker, msg);
}
/**
* Logs a message with the specific Marker at the {@code VERBOSE} 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.
*/
public void verbose(final Marker marker, final Message msg, final Throwable
t) {
logger.log(VERBOSE, marker, msg, t);
}
/**
* Logs a message object with the {@code VERBOSE} level.
*
* @param marker the marker data specific to this log statement
* @param message the message object to log.
*/
public void verbose(final Marker marker, final Object message) {
logger.log(VERBOSE, marker, message);
}
/**
* Logs a message at the {@code VERBOSE} level including the stack trace of
* the {@link Throwable} {@code 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.
*/
public void verbose(final Marker marker, final Object message, final
Throwable t) {
logger.log(VERBOSE, marker, message, t);
}
/**
* Logs a message object with the {@code VERBOSE} level.
*
* @param marker the marker data specific to this log statement
* @param message the message object to log.
*/
public void verbose(final Marker marker, final String message) {
logger.log(VERBOSE, marker, message);
}
/**
* Logs a message with parameters at the {@code VERBOSE} 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()
*/
public void verbose(final Marker marker, final String message, final
Object... params) {
logger.log(VERBOSE, marker, message, params);
}
/**
* Logs a message at the {@code VERBOSE} level including the stack trace of
* the {@link Throwable} {@code 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.
*/
public void verbose(final Marker marker, final String message, final
Throwable t) {
logger.log(VERBOSE, marker, message, t);
}
/**
* Logs a message with the specific Marker at the {@code VERBOSE} level.
*
* @param msg the message string to be logged
*/
public void verbose(final Message msg) {
logger.log(VERBOSE, msg);
}
/**
* Logs a message with the specific Marker at the {@code VERBOSE} level.
*
* @param msg the message string to be logged
* @param t A Throwable or null.
*/
public void verbose(final Message msg, final Throwable t) {
logger.log(VERBOSE, msg, t);
}
/**
* Logs a message object with the {@code VERBOSE} level.
*
* @param message the message object to log.
*/
public void verbose(final Object message) {
logger.log(VERBOSE, message);
}
/**
* Logs a message at the {@code VERBOSE} level including the stack trace of
* the {@link Throwable} {@code t} passed as parameter.
*
* @param message the message to log.
* @param t the exception to log, including its stack trace.
*/
public void verbose(final Object message, final Throwable t) {
logger.log(VERBOSE, message, t);
}
/**
* Logs a message object with the {@code VERBOSE} level.
*
* @param message the message object to log.
*/
public void verbose(final String message) {
logger.log(VERBOSE, message);
}
/**
* Logs a message with parameters at the {@code VERBOSE} level.
*
* @param message the message to log; the format depends on the message
factory.
* @param params parameters to the message.
* @see #getMessageFactory()
*/
public void verbose(final String message, final Object... params) {
logger.log(VERBOSE, message, params);
}
/**
* Logs a message at the {@code VERBOSE} level including the stack trace of
* the {@link Throwable} {@code t} passed as parameter.
*
* @param message the message to log.
* @param t the exception to log, including its stack trace.
*/
public void verbose(final String message, final Throwable t) {
logger.log(VERBOSE, message, t);
}
}
{code}
> Custom/Extended Loggers
> -----------------------
>
> Key: LOG4J2-519
> URL: https://issues.apache.org/jira/browse/LOG4J2-519
> Project: Log4j 2
> Issue Type: New Feature
> Components: API
> Affects Versions: 2.0-rc1
> Reporter: Remko Popma
> Attachments: Generate.java
>
>
> *Extending the Logger interface*
> LOG4J2-41 added support for custom log Levels. Users can now log messages at
> the new custom level by passing the custom level to the {{Logger.log()}}
> method:
> {code}
> final Logger logger = LogManager.getLogger();
> final Level VERBOSE = Level.getOrCreateLevel("VERBOSE", 550);
> logger.log(VERBOSE, "a verbose message");
> logger.log(VERBOSE, "another message");
> {code}
> However, custom levels are not as easy to use as the built-in levels: one
> needs to call the generic {{log()}} method and pass a {{Level}} parameter.
> Built-in levels on the other hand have a set of convenience methods on the
> Logger interface. For example, the Logger interface has 14 debug methods that
> support the DEBUG level:
> {code}
> debug(Marker, Message)
> debug(Marker, Message, Throwable)
> debug(Marker, Object)
> debug(Marker, Object, Throwable)
> debug(Marker, String)
> debug(Marker, String, Object...)
> debug(Marker, String, Throwable)
> debug(Message)
> debug(Message, Throwable)
> debug(Object)
> debug(Object, Throwable)
> debug(String)
> debug(String, Object...)
> debug(String, Throwable)
> {code}
> Similar method sets exist for the other built-in levels.
> Several people have expressed the desire to have the same ease of use with
> custom levels, so after declaring a custom VERBOSE level, we would like to be
> able to use code like this:
> {code}
> logger.verbose("a verbose message"); // no need to pass the VERBOSE level as
> a parameter
> logger.verbose("another message");
> {code}
> *Customizing the Logger interface*
> In the above use case, convenience methods were _added_ to the Logger
> interface, in addition to the existing {{trace()}}, {{debug()}}, {{info()}},
> ... methods for the built-in log levels.
> There is another use case, Domain Specific Language loggers, where we want to
> _replace_ the existing {{trace()}}, {{debug()}}, {{info()}}, ... methods with
> all-custom methods.
> For example, for medical devices we could have only {{critical()}},
> {{warning()}}, and {{advisory()}} methods. Another example could be a game
> that has only {{defcon1()}}, {{defcon2()}}, and {{defcon3()}} levels.
> Finally, if it were possible to hide existing log levels, users could
> customize the Logger interface to match their requirements. Some people may
> not want to have a {{FATAL}} or a {{TRACE}} level, for example. They would
> like to be able to create a custom Logger that only has {{debug()}},
> {{info()}}, {{warn()}} and {{error()}} methods.
> *Proposal: Generate source code for a Logger wrapper*
> Common log4j usage is to get an instance of the {{Logger}} interface from the
> {{LogManager}} and call the methods on this interface. This makes it hard to
> achieve the above customization; especially taking away existing methods is
> not possible.
> An alternative is for the user to create a wrapper class that exposes only
> the convenience methods for the desired log levels. When _extending_ the
> {{Logger}} API (_adding_ methods), this wrapper class could subclass
> {{org.apache.logging.log4j.spi.AbstractLoggerWrapper}}. When _customizing_
> the {{Logger}} API (_removing_ built-in methods), the wrapper class would
> simply not extend AbstractLoggerWrapper, so the only public methods would be
> the methods for the custom log levels.
> As the custom log Levels are not known in advance, Log4J cannot provide
> pre-built wrapper classes for these custom log Levels. However, we don't want
> to ask the users to hand-code such a wrapper class: this is cumbersome and
> error-prone: there are 14 methods for each built-in level. To provide
> comparable functionality for custom log Levels one would need to provide 14
> methods for each custom log Level.
> The proposal is to solve this by providing a tool that generates the source
> code for a wrapper class. The user can specify:
> * the fully qualified name of the class to generate
> * the list of custom levels to support and their {{intLevel}} relative
> strength
> * whether to extend {{Logger}} (and keep the existing built-in methods) or
> have only methods for the custom log levels
> and the tool generates the source code for the wrapper class that has exactly
> the required methods. Users would include this source code in the project
> where they want to use custom log levels.
> Note that no Log4J API changes are required to support this functionality.
> Users would create instances of the wrapper by calling a factory method on
> the wrapper class, instead of calling the {{LogManager.getLogger()}} methods.
> For example, instead of writing:
> {code}
> import org.apache.logging.log4j.Level;
> import org.apache.logging.log4j.LogManager;
> import org.apache.logging.log4j.Logger;
> final Logger logger = LogManager.getLogger(MyClass.class); // standard log4j
> logger
> final Level VERBOSE = Level.getOrCreateLevel("VERBOSE", 550);
> logger.log(VERBOSE, "a verbose message");
> {code}
> users would instead write:
> {code}
> // MyLogger is a generated customized logger wrapper
> import com.mycompany.myproject.MyLogger;
> final MyLogger logger = MyLogger.create(MyClass.class);
> logger.verbose("a verbose message");
> {code}
> Creating an extended or customized Logger is as easy as creating a standard
> Logger (one line of code). Extended Loggers are drop-in replacements for
> standard Loggers - they only add more convenience methods.
--
This message was sent by Atlassian JIRA
(v6.1.5#6160)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
