Users Guide : Jakarta Commons Logging

1.0 Version

Table of Contents

Introduction
Developers
  Best Practices
Integration
  Mechanism
  Configuring the Logger Implementation
Frequently Asked Questions
  Is JCL Thread Safe?

Introduction

The Jakarta Commons Logging (JCL) provides a Log interface that is intended to be both light-weight and independent of numerous logging toolkits. It provides the middleware/tooling developer a simple logging abstraction, that allows the user (application developer) to plug in a specific logging implementation.

Familiarity with high-level details of various Logging implementations is presumed.

The Jakarta Commons Logging provides a Log interface with thin-wrapper implementations for other logging tools, including Log4J, Avalon LogKit, and JDK 1.4. The interface maps closely to Log4J and LogKit.

Developers

To use the JCL SPI from a Java class, include the following import statements:

Note that some components using commons-logging may either extend Log, or provide a component-specific LogFactory implementation. Review the component documentation for guidelines on how commons-logging should be used in such components.

For each class definition, declare and initialize a log attribute as follows:

Messages are logged to a logger, such as log by invoking a method corresponding to priority. The org.apache.commons.logging.Log interface defines the following methods for use in writing log/trace messages to the log:

Semantics for these methods are such that it is expected that the severity, from highest to lowest, of messages is ordered as above.

In addition to the logging methods, the following are provided for code guards:

Best Practices

Best practices for programming/planning are presented in two categories: General and Enterprise. The general principles are fairly clear. Enterprise practices are a bit more involved and it is not always as clear as to why they are important.

Enterprise best-practice principles apply to middleware components and tooling that is expected to execute in an "Enterprise" level environment. These issues relate to Logging as Internationalization, and fault detection. Enterprise requires more effort and planning, but are strongly encouraged (if not required) in production level systems. Different corporate enterprises/environments have different requirements, so being flexible always helps.

General - Code Guards

Code guards are typically used to guard code that only needs to execute in support of logging, that otherwise introduces undesirable runtime overhead in the general case (logging disabled). Examples are multiple parameters, or expressions (i.e. string + " more") for parameters. Use the guard methods of the form log.is<Priority>() to verify that logging should be performed, before incurring the overhead of the logging method call. Yes, the logging methods will perform the same check, but only after resolving parameters.

General - Message Priorities/Levels

It is important to ensure that log message are appropriate in content and severity. The following guidelines are suggested:

General - Default Message Priority/Level

By default the message priority should be no lower than info. That is, by default debug message should not be seen in the logs.

Enterprise - Logging Exceptions

The general rule in dealing with exceptions is to assume that the user (developer using a tooling/middleware API) isn't going to follow the rules. Since any problems that result are going to be assigned to you, it's in your best interest to be prepared with the proactive tools necessary to demonstrate that your component works correctly, or at worst that the problem analyzed from your logs. For this discussion, we must make a distinction between different types of exceptions based on what kind of boundaries they cross:
Why info level instead of debug?
You want to have exception/problem information available for first-pass problem determination in a production level enterprise application without turning on debug as a default log level. There is simply too much information in debug to be appropriate for day-to-day operations.
More Control of Enterprise Exception Logging

If more control is desired for the level of detail of these 'enterprise' exceptions, then consider creating a special logger just for these exceptions:

This allows the 'enterprise' level information to be turned on/off explicitly by most logger implementations.

Enterprise - National Language Support - Internationalization

NLS internationalization involves looking up messages from a message file by a message key, and using that message for logging. There are various tools in Java, and provided by other components, for working with NLS messages.

NLS enabled components are particularly appreciated (thats an open-source-correct term for 'required by corporate end-users' :-) for tooling and middleware components.

NLS internationalization SHOULD be strongly considered for used for fatal, error, warn, and info messages. It is generally considered optional for debug and trace messages.

Perhaps more direct support for internationalizing log messages can be introduced in a future or alternate version of the Log interface.

Integration

The minimum requirement to integrate with another logger is to provide an implementation of the org.apache.commons.logging.Log interface. In addition, an implementation of the org.apache.commons.logging.LogFactory interface can be provided to meet specific requirements for connecting to, or instantiating, a logger.

Mechanism

Configuring the Logger Implementation

The Jakarta Commons Logging (JCL) SPI can be configured to use different logging toolkits.

Configuration of the behavior of the JCL ultimately depends upon the logging toolkit being used. The JCL SPI uses Log4J by default if it is available (in the CLASSPATH).

Log4J

As Log4J is the default logger, a few details are presented herein to get the developer/integrator going.

Configure Log4J using system properties and/or a properties file:

Frequently Asked Questions

Is JCL Thread Safe?

JCL doesn't (and cannot) impose any requirement on thread safety on the underlying implementation and thus its SPI contract doesn't guarantee thread safety. However, JCL can be safely used a multi-threaded environment as long as the underlying implementation is thread-safe.

It would be very unusual for a logging system to be thread unsafe. Certainly, JCL is thread safe when used with the distributed Log implementations.