JWhich

JWhich: Find Java Resources

By Mitch Stuart
Copyright © 2005 FullSpan Software - Usage subject to license
Software Version: 1.0 - Document Version: $Revision: 1.1 $, $Date: 2005/12/26 06:03:42 $

Introduction

JWhich is a program to find Java resources such as class files or property files. Just as the Unix which command finds executable files by searching the PATH, JWhich finds Java classes by searching the CLASSPATH.

Typical uses for JWhich are:

You have Java code that is importing/using a class, and you are not sure where the class is being loaded from (for example, which .jar file it resides in). JWhich will show you where the class exists on your CLASSPATH.
You are importing/using a class, but your code seems to be picking up the incorrect version of the class. You suspect that there may be multiple versions of the class on your CLASSPATH. JWhich shows all of the locations of the class, so you can adjust your CLASSPATH to use the proper version of the class.

Getting JWhich

Download a package including binary JAR files, source code, and documentation: [jwhich.zip] [jwhich.tar.gz]
Browse the JavaDoc (generated with the -linksource option which allows you to also browse the source code)

Installing and Running JWhich

To install JWhich, simply expand the distribution archive (.zip or .tar.gz file) into a directory of your choice. For the remainder of this document, we'll refer to this installation directory as JWHICH_DIR.

Before running JWhich, ensure that JWHICH_DIR/build/lib/jwhich.jar is on the CLASSPATH.

To run JWhich, use this command line syntax (shown on multiple lines for clarity):

  java com.fullspan.jwhich.JWhich classOrResourceName1
    classOrResourceName2 . . .

JWhich can search for 1, 2, or more resources in a single run - just specify all the class or other resource names on the command line.

For example (command and output shown on multiple lines for clarity):

  java com.fullspan.jwhich.JWhich javax/servlet/http/HttpServletRequest.class
    java/lang/String.class
  javax/servlet/http/HttpServletRequest.class: jar:file:/home/mitch/prod/
    jakarta-tomcat-4.1.30/common/lib/servlet.jar!/javax/servlet/http/
    HttpServletRequest.class
  java/lang/String.class: jar:file:/usr/java/jdk1.5.0_06/
    jre/lib/rt.jar!/java/lang/String.class

Important: The JWhich program (class com.fullspan.jwhich.JWhich) is packaged into a JAR file for convenience. However, the Main-Class attribute has not been set for the JAR file, so you will not be able to use the -jar switch to run JWhich like this:

  java -jar JWHICH_DIR/build/lib/jwhich.jar className

The reason is, as described in the java command documentation, with the -jar switch "the JAR file is the source of all user classes, and other user class path settings are ignored". Since the whole point of JWhich is to search the CLASSPATH, it wouldn't make any sense to enable the use of the -jar switch.

Setting the CLASSPATH for JWhich

The most important factor in using JWhich is setting the CLASSPATH properly before running it. Let's say you are running a program (we'll call it the "target program") and having an issue with class loading, so you want to use JWhich to diagnose the problem. There are various ways to determine how to set the CLASSPATH:

If your system CLASSPATH already includes all the entries needed to run the target program, then you don't need to add anything.
If the target program has a launcher script or batch file, you can get the CLASSPATH from that.
Some target programs, like application servers, will display the CLASSPATH they are using in their log file.
If you have access to the target program source code, you can print out System.getProperty("java.class.path").

Listing JAR Files

It is common for Java software distributions to incude library directories containing .jar and/or .zip files. The target program will usually include a script or built-in code to add all of these JAR files to the CLASSPATH. When running standalone programs such JWhich, it is tedious to manually construct the CLASSPATH containing all of the library files.

JWhich includes a shell script to help with the task of adding a directory of .jar and/or .zip files to the CLASSPATH: listJarsForClasspath.sh (you can view the script here). This is a bash script that can be run under Linux, or under the Cygwin shell in Windows (or wherever else a bash shell is available).

Run listJarsForClasspath.shwith no parameters to view the help message:

  Usage (to display jar files):
    listJarsForClasspath.sh directory1 directory2 ...

  Usage (to add jar files to CLASSPATH):
    CLASSPATH=$CLASSPATH:$(listJarsForClasspath.sh directory1 directory2 ...)

  For each directory on the command line, this script lists all of the .jar
  and .zip files in that directory.  The file names are separated by the
  path separator character (: or ; depending on platform).

ClassLoader Issues

The discussion so far has been treating the CLASSPATH as a universal entity. But the fact is, different ClassLoaders can have different CLASSPATHs. For example, in an application server, there may be one ClassLoader for the overall server, and a separate ClassLoader for each web application.

A full discussion of ClassLoader issues is beyond the scope of this document. You can find more information through web searching, or by consutling a resource such as Stuart Halloway's Component Development for the Java Platform.

Building JWhich

To build JWhich using Ant, change to the top-level JWhich directory and run ant. This will use the build.xml build file in that directory.

To build JWhich using Eclipse, import the top-level JWhich directory as an Eclipse project.