Friday, January 05, 2007

The Java Classpath


Many developers who are new to Java often have trouble with the CLASSPATH. It may seem complex, but once you understand the underlying concept, it is not difficult at all. 

If you have programmed in C++, you will probably know that the PATH environment variable is used to locate dependencies. However, Java uses the CLASSPATH environment variable to locate dependencies. Take a look at the program below.

1 public class StudentRegistrationSystem {
2   public static void main(String args[ ]) {
3     ...
4     edu.scit.studentreg.Student st =
5       new edu.scit.studentreg.Student();
6     ...
7   }
8 }


Notice that this program needs a class called 'Student'. The compiler as well as the runtime will need the Student class. The question is, how do they find it? They use the CLASSPATH environment variable.

The CLASSPATH is a list of directories, zip files or jar files.

Let us now understand how a JVM locates a class using the CLASSPATH. The Java runtime iterates through all entries in the CLASSPATH and searches for the class file in every directory, zip or jar file until the class is found. If it is not found, a ClassNotFoundException is thrown. If we put a class file in a directory not listed in the CLASSPATH, then as far as the Java runtime is concerned, it does not exist.

But wait, this is not the full story. Given a particular directory in the CLASSPATH, how does the JVM locate a class that it is searching for? Does it look for the class only in that directory, or does it look for the class in all sub-directories also? To help the JVM, we must follow certain conventions. I am assuming that you are familiar with the concept of packages in Java. If you are not, then you can read a simple explanation at The convention used is to match the directory heirarchy in which a class file is put, with the package name of the class.

Let us understand this concept with an example we have used above. Where will the runtime find the class edu.scit.studentreg.Student? When the JVM needs to locate the class edu.scit.studentreg.Student, it will look at the first entry in the classpath. Suppose it is c:/scit/classes. The JVM will now try to locate the class by zeroing in to the appropriate location based on the package name of the class. First it looks for a directory 'edu' in c:/scit/classes, if it finds the directory then it looks for 'scit' inside 'edu' and 'studentreg' inside 'scit'. Once in the 'studentreg' directory it looks for a file called Student.class. If the JVM finds the file using this algorithm, it is loaded, othewise it goes to the next entry in the classpath and tries to locate the file using the same mechanism. If the file cannot be found in any of the directories specified in the classpath, then a ClassNotFoundException is thrown.

The animation below explains how the JVM locates a class. Right click on area below and select "play" to start the animation.


So now you know, if you get a NoClassDefFoundError, it is because the Java runtime cannot locate your class file from entries in it's classpath. If the CLASSPATH variable has not been set, the current directory is used as the only classpath entry. If it contains any entries, then the current directory will not be considered part of the classpath, unless it is explicitly added.

Recommended Books:

No comments: