Java user class path

Page Index

Classpath - When do I need it, and how do I use it?
Classes in the default package
Classes in packages
Classes in Jars
Comments

Classpath - When do I need it, and how do I use it?

The intent of this article is to show you how and when to use the Java user class path.

The Java user class path is where the Java compiler and Java launcher look for user Java class files. The Java class files can be individual files or stored in a .jar file.

You need to specify a Java user class path if you keep your class files in a directory different from the current directory or, in .jar files. There is one exception to this rule, well one exception and one qualification.

If you put your library .jar files into your JDK/lib/ext or JRE/lib/ext directories, you do not need to specify a class path. The ext directories are automatically searched by the compiler and launcher respectively.
The qualification is that if you put your program into a .jar file - any library .jar files cannot be specified on the commannd line, and instead must be specified in the .jar file's manifest.

To specify a Java user class path you can either use the -classpath or -cp command line option or set the CLASSPATH environment variable. The class path may either be a relative path or an absolute path. If you don't specify a Java user class path then the default class path is the current directory.

With Java version 1.6, specifying a class path that ends with an * will cause all .jar files to be included in the class path.

All of the examples below use the Windows path separator, \. The / may also be substituted as the path separator under Windows. A drive may also be specified (eg. C:\com\mydomain\test is equivalent to C:/com/mydomain/test). Under Unix type OS you need to use the / as the path separator.

Classpath Debug Utility

Use this program to list out all the classes in your classpath.

Classes in the default package

In \com\mydomain\test there is the source file, Test.java

public class Test {
    public static void main(String[] args) {
        System.out.println("Test.main()");
        Class1.info();
    }
}

In \com\mydomain\classes there is the source file, Class1.java

public class Class1 {
    public static void info() {
        System.out.println("Class1.info()");
    }
}

Change to the com\mydomain\classes directory and compile the Class1.java file. Then change to the com\mydomain\test directory and compile the Test.java file. You need to specify the class path so that the compiler and launcher will be able to find the Class1.class file.

C:\com\mydomain\classes>javac Class1.java
C:\com\mydomain\classes>cd ..\test
C:\com\mydomain\test>javac -cp ..\classes Test.java
C:\com\mydomain\test>java -cp .;..\classes Test
Test.main()
Class1.info()

The "." is needed in the launcher's class path so that the Test.class file is accessible too.

Classes in packages

In the previous example the the files were not in a package. Let's put them in a package and see how that changes what we are doing.

package com.mydomain.test;

public class Test {
    public static void main(String[] args) {
        System.out.println("Test.main()");
        com.mydomain.classes.Class1.info();
    }
}

package com.mydomain.classes;

public class Class1 {
    public static void info() {
        System.out.println("Class1.info()");
    }
}

C:\com\mydomain\classes>javac Class1.java
C:\com\mydomain\classes>cd ..\test
C:\com\mydomain\test>javac -cp \ Test.java
C:\com\mydomain\test>java -cp \ com.mydomain.test.Test
Test.main()
Class1.info()

Notice that the class path is \, the root of the package directories. If the package directories had been mydomain\test and mydomain\classes instead of com\mydomain\test and com\mydomain\classes the class path would need to be com. This seems counter intuitive but com is the root of the package directories.

Classes in Jars

Now let's put the Class1.class file into a jar file, classes.jar.

C:\>cd \com\mydomain\classes
C:\com\mydomain\classes>javac Class1.java
C:\com\mydomain\classes>cd \
C:\>jar cvf com\mydomain\classes\classes.jar com\mydomain\classes\Class1.class
added manifest
adding: com/mydomain/classes/Class1.class(in = 415) (out= 290)(deflated 30%)
C:\>cd com\mydomain\classes
C:\com\mydomain\classes>erase *.class
C:\com\mydomain\classes>cd ..\test
C:\com\mydomain\test>javac -cp ..\classes\classes.jar Test.java
C:\com\mydomain\test>java -cp \;..\classes\classes.jar com.mydomain.test.Test
Test.main()
Class1.info()

The \ in the class path is required to find the Test.class file. Even though you are in the directory with the Test.class file, without the \ in the class path, com.mydomain.test.Test.class file will not be found by the launcher. One important thing to see here is the jar command. We need to change directories to the domain root before we jar the class files so that the path name in the .jar file record will be correct.

Now we want to put the Test.class file into a jar file. This requires the addition of a manifest file with the Class-Path option. The following two lines are in the test.man manifest file.

Main-Class: com.mydomain.test.Test
Class-Path: classes.jar

C:\com\mydomain\test>cd \
C:\>jar cvfm com\mydomain\test\test.jar com\mydomain\test\test.man com\mydomain\test\Test.class
added manifest
adding: com/mydomain/test/Test.class(in = 481) (out= 321)(deflated 33%)
C:\>cd com\mydomain\test
C:\com\mydomain\test>copy ..\classes\classes.jar
        1 file(s) copied.
C:\com\mydomain\test>java -jar Test.jar
Test.main()
Class1.info()

Notice that we copied the classes.jar file into the com\mydomain\test directory. The Class-Path option specified in the manifest file has a relative reference to the classes.jar file.

Comments

Please email any comments, corrections or suggestions to classpath at www dot knutejohnson dot com