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:

• Would you like to collaborate with other users of WebSphere Software and Service Oriented Architecture (SOA)? Consider joining the WebSphere Global User Group Community. You can collaborate with more than 28,000 WebSphere users around the world, join a local user group, get discounts on IBM Press books, IBM events, and education classes, plus give feedback to IBM.
• Try out the new features and improvements offered in these diagnostic tools available on the IBM Support Assistant:
  • Memory Dump Diagnostic for Java (MDD4J) V3.0 Beta
    • Comparative analysis is back.
    • New views of data structures on the heap.
    • New heap health reports.
    • New algorithm for detecting leak suspects.
  • Log Analyzer and Symptom Editor V4.5
    • Support of new IBM products and their logs.
    • Support of logs in new versions of IBM products already supported.
    • Support of new symptom catalogs.
    • Improved usability for importing logs.
    • Improved usability of filters for importing and viewing logs.
• Want to learn more about the HTTP protocol? Check out these new WebSphere Technical Exchange webcast replays that discuss HTTP protocol request and response headers and common status codes:
  • HTTP Protocol – Breakdown Request Headers
  • HTTP Protocol – Breakdown Response Headers
  • HTTP Protocol – Understanding Common Status Codes
• If you use WebSphere Application Server V7 for z/OS, then try out the new MODIFY commands from the MVS console to quickly gather diagnostic information. In particular, the MODIFY (Control Region Job Name), JAVACORE and HEAPDUMP commands can produce Javacore TXT files and Heapdump PHD files, respectively, onto HFS/ZFS. Javacore files are small snapshots of a JVM, take only a few seconds to run, are small in size (approximately 2 MB), and are useful during health checks, hangs, and performance problems. Heapdump files are larger snapshots of a JVM's Java memory, are much larger in size, and are useful for analyzing memory leaks.
• If you use WebSphere Portal and Web Content Management then be sure to see these important news items:
  • WebSphere Portal and WCM 6.1 Information Center Highlights Webcast
  • Updated featured documents for IBM WebSphere Portal and Web Content Management
  • Updated MustGather for IBM WebSphere Portal. Read this information first before opening a PMR.
• Announcing the availability of V6.2 of these IBM BPM products:
  • WebSphere Integration Developer, WebSphere Process Server, and WebSphere Enterprise Service Bus: Enable dynamic processes and flexible connectivity for agile business solutions.
  • WebSphere Business Modeler products: Brings your BPM solutions to life from process modeling to deployment.
  • WebSphere Business Monitor: Helps business users anticipate and respond proactively to situations for better business results.
  • WebSphere Business Services Fabric: Enables businesses to rapidly assemble SOA-based business processes while reusing and sharing IT assets.
  • WebSphere Dynamic Process Edition: Helps you rapidly adapt to changing market demands.
• If you use WebSphere Process Server or WebSphere Enterprise Bus Service, then you must migrate to Version 6.2. See the document titled Migration to WebSphere Process Server and WebSphere Enterprise Bus 6.2 – Mandatory Reading for more information. While you’re migrating, you might also want to read these new articles that have tips for preventing problems:
  • IBM WebSphere Process Server Best Practices in Error Prevention Strategies and Solution Recovery
  • Repairing processes with WebSphere Process Server.

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...

Back to top

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.

Back to top

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.

Back to top

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
     
     
     

  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
     
     
     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
     
     
     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
     
     
     
• 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
     
     
     
  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
     
     
     
  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
     
     
     
  4. Select the class loader you just created (Figure 8).
     
     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
     
     
     
  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
  
  
  

  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 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
  
  
  

Back to top

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

• Creating shared libraries in WebSphere 6.1
  
  
• The Support Authority: If you need help with WebSphere products, there are many ways to get it
  
  
• IBM Software product Information Centers
  
  
• IBM Software Support Web site
  
  
• IBM Education Assistant
  
  
• IBM developerWorks
  
  
• IBM Redbooks
  
  

Get products and technologies

• IBM Support Assistant
  
  

Discuss

• Forums and newsgroups
  
  

About the authors

Rate this article

Comments

Back to top

Table of contents

• This just in...
• What is Jakarta Commons Logging (JCL)?
• When should I use JCL?
• Configuring your environment for JCL
• Summary
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: WebSphere Application Server
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: WebSphere Application Server

Dig deeper into WebSphere on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers