Section B.1. Jakarta Commons Logging (JCL) API


B.1. Jakarta Commons Logging (JCL) API

The Jakarta Commons Logging (JCL) package from the Apache Jakarta project provides a standard interface to the various logging libraries, hiding the details of the logging implementation from an application. Many logging APIs are available, and at some point an application may need to change to another logging technology. The main benefit of the JCL is that it enables developers to switch between logging implementations without impacting their code.

B.1.1. Using the Apache JCL

Example B-1 is an example from the JAW Motors InitServlet that uses the JCL to print out a log message.

Example B-1. InitServlet.java
 ... import org.apache.commons.logging.*; ... public class InitServlet extends GenericServlet {     private Log log = LogFactory.getLog(InitServlet.class);     private ServletContext servletContext;     public void init(  ) {         ...         log.info("Testing Logging Setup ...");     } } 

The call to LogFactory.getLog( ) creates a concrete implementation of the org.apache.commons.logging.Log interface so we can log messages. The init( ) method then uses the Log instance to log a debug message by calling log.debug( )this method then does the real work of logging the message to its destination. See the next section for more information about org.apache.commons.logging.Log interface. See the Initialization Servlet section for more information on the InitServlet.

B.1.2. Using a Logging Implementation

A logging package must implement the Log interface to work with the JCL, which comes bundled with four usable concrete logger instances that encapsulate the underlying logging package:


Log4JLogger

Delegates to a Log4J Logger


Jdk14Logger

Wraps the standard logger that comes with the J2SE


LogKitLogger

Encapsulates the Avalon logkit logger


SimpleLogger

The default logger that dumps all messages to System.err

Several options logging implementations are available, but we chose Log4J for the JAW Motors application because of Log4J's widespread use and robust features. Each logger implements the JCL's Log interface so the caller doesn't know about the logger that JCL uses. The JCL uses the following algorithm to determine which logger to use:

 If the org.apache.commons.logging.Log property was set, THEN     Instantiate the logger defined by the org.apache.commons.logging.Log property. ELSE IF Log4J is available (on the CLASSPATH) THEN     Use Log4JLogger. ELSE IF JDK 1.4 or later is available THEN     Use Jdk14Logger. ELSE     Use SimpleLogger. 

B.1.3. Property File

The Commons Logging package uses a property file, commons-logging.properties (which resides in the appb project's common/conf sub-directory), to configure and instantiate the underlying logging mechanism to use. The JAW Motors application places this properties file in the base directory of its Common JAR file so that Apache Commons Logging can find the file on the CLASSPATH and configure itself properly (for more details see the "Logging Deployment" section). In Example B-2, Log4J is the logging implementation.

Example B-2. commons-logging.properties
 org.apache.commons.logging.Log=org.apache.commons.logging.impl.Log4JLogger 

B.1.4. Logging Levels

Logging levels have no intrinsic universally accepted meaning. On each project, system personnel and developers need to determine what logging levels are meaningful and how to use to them. JCL's Log interface has six logging levels (in ascending order). Here's how we use them in the JAW Motors application:


trace

This is the least serious/lowest level, and we don't see a need for trace because we use debug instead.


debug

We use debug when we're debugging an application or to leave some bread crumbs when running an application. These messages are typically sent to a log file.


info

The JCL development group recommends using info messages to log events that occur at system startup or shutdown.


warn

This level represents minor errors. We feel that it is a bit too fine-grained, so we use the error logging level instead.


error

This represents runtime failures in the application due to system failures or programming errors. The most common problems we've seen include: JNDI lookup failure, database is inaccessible, and NullPointerException. You usually want to log the error and notify system personnel with an email or pager message.


fatal

This is the most serious/highest level, and it represents errors that cause an application to terminate abnormally. On our projects, we haven't seen any of these kinds of problems in the code. We've seen exceptions that terminate the deployment process show up in the JBoss console. So, we don't use fatal messages in the JAW Motors application.

Of course, if you want to apply different meanings and actions to these logging levels, do what works for your application. Although each logging API manages its logging levels in an implementation-specific manner, each logging system must work in an expected way. For example. if the debug level logging is enabled, the logging package logs debug and higher level messages, and ignores trace level messages.



JBoss at Work. A Practical Guide
JBoss at Work: A Practical Guide
ISBN: 0596007345
EAN: 2147483647
Year: 2004
Pages: 197

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net