The K-Zone: Mastering the Java CLASSPATH

The significance of the class search path

An understanding of the class search path is important for all Java developers. However, the widespread use of integrated development tools has concealed the technicalities for so long that there is a widespread lack of comprehension, even among experienced developers. The problem is particularly acute with development of distributed applications, as the system which will run the application is likely to be configured rather differently from the one on which development takes place.

This article describes in detail how the Java compiler and the JVM use the class search path to locate classes when they are referenced by other Java code. It does this with reference to a very simple example, which uses two classes in the same package. We will see how various operations to compile these two classes succeed and fail, depending on the class path setting.

To make things absolutely clear, we will use only simple command-line tools to carry out the compile operations. Interactive development tools have their own ways of manipulating the class path, which vary from product to product.

There is no fundamental difference between the way that the Java compiler searches for classes, and the way that the JVM does it at run time. However, the compiler has the ability to compile classes from source code, where the JVM does not. In the examples below we will use the compiler, but similar issues apply at run time.

The example

This example has two trivial classes: com.web_tomorrow.CPTest1 and com.web_tomorrow.CPTest2, which are listed below.

package com.web_tomorrow;
public class CPTest1
{
public static void main(String[] args)
  {
  System.out.println ("Run CPTest1.main()");
  }
}

package com.web_tomorrow;
public class CPTest2
{
public static void main(String[] args)
  {
  System.out.println ("Run CPTest2.main()");
  CPTest1 cpt1 = new CPTest1();
  }
}

One of the most fundamental rules of Java code organization is that `package name = directory name'. We will begin by setting up a directory structure that matches the package assignment of these two classes. The classes are in a package com.web_tomorrow, so we must create the directory com/web_tomorrow to contain the source code.

[root]
  com
    web_tomorrow
      CPTest1.java
      CPTest2.java

In this document I will use the notation `[root]' to mean `whatever directory contains the structure described above', that is, the root of the directory layout. This will vary, of course, according to how you install the files.

Basic principles

Let's try to compile CPTest1.java on its own using the command-line javac program. To disable the class search path completely (so any existing setting does not interfere with the example), we can run javac with the option `-classpath ""'.

As a first attempt, let's change directory to the location of CPTest1.java, and try to compile it by specifying its name on the javac command line.

cd [root]/com/web_tomorrow
javac -classpath "" CPTest1.java

This operation succeeds, because the compiler is able to find CPTest1.java (it is in the working directory), and because CPTest1 does not reference any other classes. The output file, CPTest1.class ends up in the same directory as CPTest1.java because, again, you haven't given the compiler information to do anything else. So far so good. Now let's try the same thing with CPTest2. Still in the `web_tomorrow' directory, execute this command:

javac -classpath "" CPTest2.java

This operation should fail, even though the directory is the same as the previous step, and CPTest1 and CPTest2 are in the same package. The error message will be something like this:

PTest2.java:7: cannot resolve symbol
symbol  : class CPTest1  
location: class com.web_tomorrow.CPTest2
  CPTest1 cpt1 = new CPTest1();
  ^

The difference between this case and the previous, successful, one is that CPTest2 contains a reference to CPTest1:

  CPTest1 cpt1 = new CPTest1();

What is going on here? When the compiler encounters the reference to CP1Test here, it assumes that this is a class in the same package as CP2Test that is is currently compiling. This is a correct assumption. So the compiler needs to find com.web_tomorrow.CP1Test. But it has nowhere to look, as we have explicitly set the class search path to "" (i.e., nothing).

You might think this problem can be resolved by telling the compiler to look in the current directory. The standard symbol for `current directory' is a single period (.) in both Unix and Windows systems. So try something like this:

javac -classpath "." CPTest2.java

This fails in exactly the same way as the previous example. The problem now is that although CPTest1.java is in the current directory, the class that it implements is not just CPTest1, but com.web_tomorrow.CPTest1. The compiler will look for a directory com/web_tomorrow below the current directory. So, overall, it is looking for a Java source or class file in the directory [home]/com/web_tomorrow/com/web_tomorrow which, of course, does not exist.

To make this compile operation work, we need to make the class search path reference not the directory containing CPTest1, but a directory root from which CPTest1 can be located by the compiler following the standard Java `package name = directory name' rule. This should work, although it's rather ugly:

javac -classpath "../.." CPTest2.java

Before seeing how we can make this less ugly, consider this example (still in the same directory):

javac -classpath "" CPTest1.java CPTest2.java

This also works, even though the class path is empty. This is because the Java compiler will look for references between any source code explicitly listed on the command line. If there are many classes, all in the same directory, we can simplify this to:

javac -classpath "" *.java

The `*.java' expands to a list of all the .java files in the current directory. This explains why compiling many files in one operation often succeeds where attempts to compile a single file fails.

A more convenient way to compile CPTest2 on its own is like this:

cd [root]
javac -classpath "." com/web_tomorrow/CPTest2.java

In this example we specify the full path to CPTest2.java, but include `.' in the -classpath option. Again, we aren't telling the compiler to look for files in the current directory, we are telling it to begin a class search from the current directory. Because the class we are looking for is com.web_tomorrow.CPTest1, the compiler will search in ./com/web_tomorrow (that is, the directory com/web_tomorrow below the current directory). This is exactly where CPTest1.java is located.

In fact, even though I only specified CPTest2 on the command line, this practice does in fact lead to the compilation of CPTest1 as well. The compiler finds the .java file in the right place, but it can't tell whether this Java source really implements the right class, so it has to compile it. But note that if we do this:

cd [root]
javac -classpath "." com/web_tomorrow/CPTest1.java

it does not cause a compilation of CPTest2.java, because the compiler does not need to know anything about CPTest2 to compile CPTest1.

.class files separate from .java files

The examples described so far, when successful, place the output .class files alongside the .java files from which they were generated. This is a simple scheme, and very widely used. However, many developers like to keep the source tree free of generated files, and must therefore tell the Java compiler to maintain separate directories for .class files. Let's see what impact this has on the class search path.

To begin we will need to delete any .class files lurking around after the previous examples. We will also contain a new directory classes to contain the generated .class files. The procedure at the command line would be something like this:

cd [root]
rm com/web_tomorrow/*.class
mkdir classes

Don't forget to swap the `/' characters for '\' if you are using a Windows system. The directory structure now looks like this.

[root]
  com
    web_tomorrow
      CPTest1.java
      CPTest2.java
  classes

Let's compile CPTest1.java, specifying classes as the destination directory (using the -d option):

cd [root]
javac -d classes -classpath "" com/web_tomorrow/CPTest1.java

This should succeed, but you should notice that the .class files have not been placed into the classes directory at all. Instead, we have a new directory structure like this:

[root]
  com
    web_tomorrow
      CPTest1.java
      CPTest2.java
  classes
    com
      web_tomorrow
        CPTest1.class

What has happened is that the compiler has created a directory structure to match the package structure. It has done this to be helpful, as we shall see. When we come to compile CPTest2.java we have two choices. First, we can compile it as described above, allowing the compiler to compile CPTest1 as part of the process. Alternatively, we can compile it and use the -classpath option to refer to the compiler to the .class file generated in the previous step. This method is superior, as we don't have to repeat the compilation of CPTest1.

cd [root]
javac -d classes -classpath classes com/web_tomorrow/CPTest2.java

By doing this, we end up with this directory structure.

[root]
  com
    web_tomorrow
      CPTest1.java
      CPTest2.java
  classes
    com
      web_tomorrow
      CPTest1.class
      CPTest2.class

Of course we could have compiled both .java files in the same command, and got the same result.

JARs on the classpath

The java compiler and run-time can search for classes not only in separate files, but also in `JAR' archives. A JAR file can maintain its own directory structure, and Java follows exactly the same rules as for searching in ordinary directories. Specifically, `directory name = package name'. Because a JAR is itself a directory, to include a JAR file in the class search path, the path must reference the JAR itself, not merely the directory that contains the JAR. This is a very common error. Suppose I have a JAR myclasses.jar in directory /myclasses. To have the Java compiler look for classes in this jar, we need to specify:

javac -classpath /myclasses/myclasses.jar ...

and not merely the directory myclasses.

Multiple class search directories

In the examples above, we have told javac to search in only one directory at a time. In practice, your class search path will contain numerous directories and JAR archives. The -classpath option to javac and java allows multiple entries to be specified, but notice that the syntax is slightly different for Unix and Windows systems.

On Unix, we would do this:

javac -classpath dir1:dir2:dir3 ...

whereas on Windows we have:

javac -classpath dir1;dir2;dir3 ...

The reason for the difference is that Windows uses the colon (:) character as part of a filename, so it can't be used as a filename separator. Naturally the directory separator character is different as well: forward slash (/) for Unix and backslash (\) for Windows.

System classpath

Rather than specifying class search path on the javac command line, we can make use of a `system' class path. This is the class path that will be used by both the Java compiler and the JVM in the absence of specific instructions to the contrary. In both Unix and Windows systems, this is done by setting an environment variable. For example, in Linux with the bash shell:

CLASSPATH=/myclasses/myclasses.jar;export CLASSPATH

and in Windows:

set CLASSPATH=c:\myclasses\myclasses.jar

This procedure is fine for short-term changes to the system CLASSPATH, but if you want these changes to be persistent you will need to arrange this yourself. Details vary from system to system. On a Linux system, for example, I would put the commands in the file .bashrc in my home directory. On Windows 2000/NT there is a `Control Panel' page for this.

Setting the system CLASSPATH is a useful procedure if you have JARs full of classes that you use all the time. For example, if I am developing Enterprise JavaBean (EJB) applications using Sun's J2EE `Reference Implementation', all the EJB-related classes are in a JAR called `j2ee.jar' that comes with the distribution. I want this JAR on the class search path all the time. In addition, most people want to ensure that the current directory is on the search path, whatever the current directory happens to be. So in my .bashrc file I have this line:

CLASSPATH=/usr/j2ee/j2ee.jar:.;export CLASSPATH

where the `.' indicates `current directory'.

It is easy to overlook that the -classpath option on the command line replaces the default, system class path; it does not add to it. So what should I do if I want to set the class path to include the default system classpath plus some other entries? I could simply use the -classpath option and list the default entries in addition to my extras. However, a better way is to reference the CLASSPATH environment variable. The syntax for this is different -- of course -- on Windows and Unix systems. On Unix:

javac -classpath $CLASSPATH:dir1:dir2 ...

where $CLASSPATH expands to the current setting of the CLASSPATH environment variable. On Windows:

javac -classpath %CLASSPATH%;dir1:dir2 ...

Finally, please note that if directories in your class search path have spaces in their names, you may have to use double-quotes on the command line to prevent the CLASSPATH being split up. For example:

javac -classpath "%CLASSPATH%";dir1:dir2 ...