org.apache.log4j.jul
Class JULAppender

java.lang.Object
  org.apache.log4j.AppenderSkeleton
      org.apache.log4j.jul.JULAppender

All Implemented Interfaces:

org.apache.log4j.Appender, org.apache.log4j.spi.OptionHandler

public class JULAppender
extends org.apache.log4j.AppenderSkeleton

A Log4j appender for Java Logging API (aka JUL). This appender allows existing log4j-enabled applications running inside a JUL-enabled environment (like an application server) to correctly log events in the proper log level and JUL format.

The need for this appender comes from several facts:

1. JUL alone does not provide features like layouts, patterns, NDC, etc; so using JUL takes away important features from developers.

2. Log4j alone does not correctly map Log4j log levels to JUL levels. The best one can do at the moment is use the all-purpose ConsoleAppender, which causes all log4j events to appear as either INFO or WARNING, depending on the appender's target (out/err) and NOT depending on the logging method (debug/trace/error/etc). Proper mapping to JUL levels (INFO, FINE, FINEST, etc) is expected to depend on the logging method being called.

3. The fact that there is no appropriate log4j-JUL level mapping also means that the JUL environment mistreats events generated by the application; for example, the administrator's level-dependent rules may mistreat log4j events, or a simple query for all FATAL-level events using standard JUL interfaces would not show log4j events, making maintenance and troubleshooting difficult.

This appender effectively satisfies those needs:

1. It fully supports layouts like ConsoleAppender

2. It appropriately maps Log4j-levels to JUL levels, depending on the logging method being called. The mapping is as follows (log4j --> JUL):
all --> ALL
trace --> FINER
debug --> FINE
info --> INFO
warn --> WARNING
error --> SEVERE
fatal --> SEVERE

Note: there is no *standard* JUL level between WARNING and SEVERE, so both error and fatal log4j events are mapped to SEVERE.

Usage and configuration is identical to using the ConsoleAppener. Any application currently configured to use the ConsoleAppender, and wishes to switch to JulAppender simply has to replace "ConsoleAppender" with "JulAppender" in its log4j configuration; for example:

log4j.appender.julAppender=org.apache.log4j.JulAppender log4j.appender.julAppender.layout=org.apache.log4j.PatternLayout log4j.appender.julAppender.layout.ConversionPattern=%d %-5p %c - %m%n

It may even be sensible to reduce the number of elements in the pattern since JUL usually provides some context information for each logged event (JUL implementation dependent).

Other features:

1. Automatic mapping between log4j logger hierarchy and JUL logger hierarchy; For example, a log4j logger for class com.mycompany.service.MyWebService will automatically log JUL events as if it is a JUL logger by the same name, using the respective JUL configuration and rules for that logger. If such a JUL logger is not available by the JUL environment, it will attempt to log as if it is the JUL logger com.mycompany.service, and so on.

2. If a log4j event is being dropped by the JUL environment because its level is too fine, a warning will be sent to LogLog, indicating a mismatch between log4j configuration and JUL configuration.

3. If, for some reason, the appropriate JUL logger cannot be obtained (usually because of a JUL-environment issue), a warning will be sent to LogLog.

Author:

Sagi Mann (sagimann@gmail.com), psmith

Field Summary

Fields inherited from class org.apache.log4j.AppenderSkeleton

closed, errorHandler, headFilter, layout, name, tailFilter, threshold

Constructor Summary

JULAppender()
Creates a new appender with no special layout

JULAppender(org.apache.log4j.Layout layout)
Creates a new appender with the specified layout

Method Summary

void	activateOptions()
protected void	append(org.apache.log4j.spi.LoggingEvent loggingEvent) Append a log event at the appropriate JUL level, depending on the log4j level.
void	close()
java.lang.String	getCustomLevelConverterClass() Returns the customized JULLevelConverter implementation class that will be used in place of the default.
boolean	requiresLayout() This appender requires a layout.
void	setCustomLevelConverterClass(java.lang.String customLevelConverterClass) Sets the name of the customized JULLevelConverter class implementation that will be used to map log4j and JUL Logging Levels.

Methods inherited from class org.apache.log4j.AppenderSkeleton

addFilter, clearFilters, doAppend, finalize, getErrorHandler, getFilter, getFirstFilter, getLayout, getName, getThreshold, isAsSevereAsThreshold, setErrorHandler, setLayout, setName, setThreshold

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JULAppender

public JULAppender()

Creates a new appender with no special layout

JULAppender

public JULAppender(org.apache.log4j.Layout layout)

Creates a new appender with the specified layout

Method Detail

activateOptions

public void activateOptions()

Specified by:

activateOptions in interface org.apache.log4j.spi.OptionHandler

Overrides:

activateOptions in class org.apache.log4j.AppenderSkeleton

requiresLayout

public boolean requiresLayout()

This appender requires a layout. However, if the appender is created programatically without a layout, it will simply log the event as-is.

close

public void close()

append

protected void append(org.apache.log4j.spi.LoggingEvent loggingEvent)

Append a log event at the appropriate JUL level, depending on the log4j level.

Specified by:

append in class org.apache.log4j.AppenderSkeleton

getCustomLevelConverterClass

public final java.lang.String getCustomLevelConverterClass()

Returns the customized JULLevelConverter implementation class that will be used in place of the default.

Returns:

setCustomLevelConverterClass

public final void setCustomLevelConverterClass(java.lang.String customLevelConverterClass)

Sets the name of the customized JULLevelConverter class implementation that will be used to map log4j and JUL Logging Levels. A non-null value will indicate a custom implementation, otherwise a default is chosen (see JULLog4jEventConverter.

Parameters:

customLevelConverterClass -