The Support Authority: Using Jakarta Commons Logging (JCL) with WebSphere Application Server

Learn how to use the Jakarta Commons Logging (JCL) framework as a wrapper for delegating log and trace routines to different underlying logging implementations used by applications deployed to IBM® WebSphere® Application Server. Also, get news on new IBM WebSphere products and troubleshooting tools. This content is part of the IBM WebSphere Developer Technical Journal.

Mike Casile (mcasile@us.ibm.com), WebSphere Serviceability Architect , IBM

Mike Casile is a WebSphere Serviceability architect and Team Leader. His team supports Reliability and Serviceability, Class Loader Viewer, First Failure Data Capture, RAS Diagnostic Providers, and other WebSphere runtime components that focus on Serviceability. The team also contributes to the IBM Support Assistant (ISA) and other key tooling in ISA such as MDD4J, Dump Analyzer, Log Analyzer, and WebSphere Data Collections.



Russell Wright (rbwright@us.ibm.com), WebSphere Serviceability Development, IBM

Russell Wright has several years of experience developing and supporting data communications and middleware software including WebSphere Application Server. He currently manages the deployment of troubleshooting tools for the IBM Support Assistant and is a developer for the IBM Guided Activity Assistant.



10 December 2008

Also available in Japanese

In each column, The Support Authority discusses resources, tools, and other elements of IBM® Technical Support that are available for WebSphere® products, plus techniques and new ideas that can further enhance your IBM support experience.

This just in...

As always, we begin with some new items of interest for the WebSphere community at large:

Continue to monitor the various support-related Web sites, as well as this column, for news about other tools as we encounter them.

And now, on to our main topic...


What is Jakarta Commons Logging (JCL)?

The February 2008 edition of The Support Authority featured a developer’s guide to WebSphere Application Server logging, which presented an introduction to logging and tracing and a summary of the various APIs you can leverage in your WebSphere Application Server applications. This article focuses on how to use the Jakarta Commons Logging (JCL) framework as a wrapper for delegating log and trace routines to different underlying logging implementations used by applications deployed to WebSphere Application Server.

JCL is an Apache project that aims to provide a wrapper API to which you can write. Unlike other logging APIs, JCL delegates logging calls at run time to a concrete logging implementation that is appropriate to the containing environment. In WebSphere Application Server, for example, events from JCL are sent to the WebSphere Application Server log and trace facilities. In other environments, it is not uncommon to send JCL output to Log4J. The key point here is that JCL is not a standards-based API, but rather a framework that lets developers "not care" where their trace output goes. JCL predates a standard API.

JCL's key strength is that it enables code to be instrumented with logging calls independent of any consideration about what logging facilities exist in the runtime, or what runtimes the code will ultimately run on.

JCL is integrated and packaged with WebSphere Application Server. Applications that bundle their own copy of the JCL JAR and want to send output to destinations other than the IBM-provided defaults will need to take extreme care to avoid class loading conflicts with the version of JCL included in the application server runtime. This article explains how to configure your applications to prevent class loading conflicts.


When should I use JCL?

With the common availability of java.util.logging (JUL) in all J2SE 1.4 and later JVMs, the need for JCL as a portable logging wrapper has diminished. As such, you should not use JCL in any new application code.

However, your applications might already use JCL, or they might use vendor software or other stack products that do use JCL. In these cases, it is generally undesirable to rewrite thousands of lines of code and risk introducing problems simply to follow the recommended logging solutions for new applications.

If your applications use a version of JCL that is different from what is provided with WebSphere Application Server, which is V1.0.3, then you can use the information in this article to configure your environment.


Configuring your environment for JCL

The process for configuring JCL differs depending on the version of WebSphere Application Server and the version of JCL that you’re using.

JCL V1.0.3

Newer versions of some software that use JCL require newer versions of JCL. If your application has software that uses JCL, and JCL 1.0.3 is sufficient, then there are two simple solutions:

  • JCL routing to default WebSphere Application Server logging

    If routing the JCL logging into WebSphere Application Server logs with JDK logging is acceptable, then no action is necessary. The runtime provides the libraries needed to route JCL through the JDK loggers and out to the WebSphere Application Server logs. This is the default behavior.

  • JCL routing through Log4J

    If you prefer to use Log4J to handle the logging done with JCL 1.0.3, then some simple configuration is necessary:

    1. Include the Log4J JAR and JCL 1.0.3 JAR in your application’s WEB-INF/lib directory.
    2. Create a file called org.apache.commons.logging.LogFactory in your application’s META-INF/services directory. This file contains just one line of text:

      org.apache.commons.logging.impl.Log4jFactory

JCL V1.1 or higher

If your application requires a newer version of JCL, then you must provide that library in your application’s WEB-INF/lib directory and make configuration changes. The following options assume you are planning to use Log4J (the most common case), but they apply to other types as well. These samples refer to the 1.1.1 version of the JAR, but any 1.1 or higher version can be used.

  • ParentLast class loading

    The simple solution is to use ParentLast class loading in your application and module. Provide the appropriate level of JCL and Log4J in your application’s WEB-INF/lib directory and follow these instructions to configure ParentLast class loading for your application:

    1. Open the WebSphere Application Server administrative console and navigate to Applications => Enterprise Applications => <your application> => Manage Modules => <your module>.
    2. Set the class loader order to Classes loaded with application class loader first (Figure 1).
      Figure 1. Setting ParentLast class loading for an application
      Figure 1. Setting ParentLast class loading for an application

    The result of these steps is that the JARs and configurations supplied in your application will be used before anything provided by WebSphere Application Server.

  • Shared library and server-scoped class loader

    To configure WebSphere Application Server V6 or higher applications to use JCL 1.1 or higher, you need to create a shared library that is attached to the server, create a class loader that references only that shared library, and use a ParentLast class loading policy:

    1. Move the logging properties and JAR files into a single directory.

      Move the commons-logging-1.1.1.jar, the log4j JAR, and commons-logging.properties file into a single directory with no other files in it. These JAR files are available as open source software, and a sample configuration is explained below. Figure 2 shows a Windows Explorer view of this directory containing only these three files.

      Figure 2. Two JARs and one properties file in a single directory
      Figure 2. Two JARs and one properties file in a single directory
      In this scenario, the commons-logging.properties file looks like this:
      priority=1
      org.apache.commons.logging.LogFactory=org.apache.commons.logging.impl.LogFactoryImpl
      org.apache.commons.logging.Log=org.apache.commons.logging.impl.Log4JLogger

      Notice that priority is a new parameter in JCL 1.1 and that the default is 0. The properties file with the highest priority found in the classpath will be used.

    2. Create the shared library.

      To create the shared library using the WebSphere Application Server admin console, select Environment => Shared Libraries. From this panel, select the server scope (on the right), and select the New button (Figure 3). Shared libraries can be defined at server, node, or cell scope. When defining a shared library at cell scope, it might be beneficial to use variables in the name and override those variables at the node level.

      Figure 3. Create shared library
      Figure 3. Create shared library
      In the new Shared Libraries panel (Figure 4):
      1. Provide a Name, for example jcl111. This will be referenced in a later step.
      2. Optionally, provide a Description.
      3. For Classpath, specify the directory that you created earlier that contains two JAR files and one properties file.
      4. Leave Native Library Path empty and select OK.
      Figure 4 shows the WebSphere Application Server V6.1 panel filled in as described. Save the configuration.
      Figure 4. Configure shared library
      Figure 4. Configure shared library
  • Create the server-scoped class loader.
    1. In the admin console, select Servers => Application Servers, then select the server that contains your application (Figure 5).
      Figure 5. Create class loader, step a
      Figure 5. Create class loader, step a
    2. When your server configuration is displayed, expand Java and Process Management and select Class loader (Figure 6).
      Figure 6. Create class loader, step b
      Figure 6. Create class loader, step b
    3. On the next panel, select New. In the Configuration General Properties section (Figure 7), select Classes loaded with application class loader first (that is, application class loading) and press OK.
      Figure 7. Create class loader, step c
      Figure 7. Create class loader, step c
    4. Select the class loader you just created (Figure 8).
      Figure 8. Create class loader, step d
      Figure 8. Create class loader, step d
    5. After selecting the class loader, you will see the panel shown in Figure 9. Select Shared library references.
      Figure 9. Create class loader, step e
      Figure 9. Create class loader, step e
    6. Select the name of the library you created in step 2 (Figure 4).
  • Isolated shared library (WebSphere Application Server V7 and higher only)

    WebSphere Application Server V7 has a new facility called isolated shared libraries, which makes it easier to configure JCL. When you create the shared library in WebSphere Application Server V7, there is a checkbox at the bottom of the panel to choose an isolated class loader (Figure 10).

    Figure 10. WebSphere Application Server V7 isolated shared libraries
    Figure 10. WebSphere Application Server V7 isolated shared libraries

    When you select that option, you do not need to create a new class loader. This isolated shared library can then be added as a shared library reference to your application and modules by selecting: Applications => Application Types => WebSphere Enterprise Applications => <your application>. From the resulting panel, select Shared Library References under the References section, which will display the panel shown in Figure 11. Simply select the application, then click the Reference shared libraries button.

    Figure 11. Shared library references
    Figure 11. Shared library references

    Figure 12 shows the available shared libraries. Simply select those you want to add, select the right arrow, press OK, and save your changes. Do this for the application and the module.

    Figure 12. Add and remove shared library references
    Figure 12. Add and remove shared library references

Summary

If Jakarta Commons Logging 1.0.3 is sufficient for your needs, then using it with the default (jdk14logger) implementation or Log4J is a relatively simple process. It is also relatively simple to use your own version if you can use ParentLast class loading in your application.

If neither of these is true, then the best technique is to create a shared library containing JCL, Log4J, and your properties file, then create a class loader that is server-scoped and references your shared library. WebSphere Application Server V7 greatly simplifies this process with the introduction of isolated shared libraries.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=366944
ArticleTitle=The Support Authority: Using Jakarta Commons Logging (JCL) with WebSphere Application Server
publish-date=12102008