The class path is the path that the Java runtime environment
searches for classes and other resource files. The class search
path (more commonly known by the shorter name, "class path")
can be set using either the -classpath option when
calling a JDK tool (the preferred method) or by setting the
CLASSPATH environment variable. The
-classpath option is preferred because you can set
it individually for each application without affecting other
applications and without other applications modifying its
value.
% sdkTool -classpath
classpath1:classpath2...
-or-
% setenv CLASSPATH
classpath1:classpath2...
where:
java,
javac, javadoc, or
apt. For a listing, see JDK Tools.:classpath2Multiple path entries are separated by colons.
The default class path is the current directory. Setting
the CLASSPATH variable or using the
-classpath command-line option overrides that
default, so if you want to include the current directory in
the search path, you must include "." in the new
settings.
Classpath entries that are neither directories nor archives (.zip or .jar files) nor * are ignored.
The class path tells the JDK tools and applications where to find third-party and user-defined classes -- that is, classes that are not extensions or part of the Java platform. The class path needs to find any classes you've compiled with the javac compiler -- its default is the current directory to conveniently enable those classes to be found.
The JDK, the JVM and other JDK tools find classes by searching the Java platform (bootstrap) classes, any extension classes, and the class path, in that order. (For details on the search strategy, see How Classes Are Found.) Class libraries for most applications will want to take advantage of the extensions mechanism. You only need to set the class path when you want to load a class that's (a) not in the current directory or in any of its subdirectories, and (b) not in a location specified by the extensions mechanism.
If you are upgrading from an older version of the JDK, your
startup settings may include CLASSPATH settings
that are no longer needed. You should remove any settings that
are not application-specific, such as classes.zip.
Some third-party applications that use the Java Virtual Machine
may modify your CLASSPATH environment variable to
include the libaries they use. Such settings can remain.
You can change the class path by using the JDK tools'
-classpath option when you invoke the
JVM or other JDK tools or by using the CLASSPATH environment variable.
Using the -classpath option is preferred over
setting CLASSPATH environment variable because you
can set it individually for each application without affecting
other applications and without other applications modifying its
value.
Classes can be stored either in directories (folders) or in
archive files. The Java platform classes are stored in
rt.jar. For more details on archives and
information on how the class path works, see Understanding the class path and package
names near the end of this document.
Important Note: Some older versions of the JDK
software included a
<jdk-dir>/classes
entry in the default class path. That directory exists for
use by the JDK software, and should not be used for
application classes. Application classes should be placed in
a directory outside of the JDK direcotry hierarchy. That way,
installing a new JDK does not force you to reinstall
application classes. For compatibility with older versions,
applications that use the
<jdk-dir>/classes
directory as a class library will run in the current version,
but there is no guarantee that they will run in future
versions.
The Java tools java, jdb, javac, and
javah have a
-classpath option which replaces the path
or paths specified by the CLASSPATH environment
variable while the tool runs. This is the recommended option
for changing class path settings, because each application can
have the class path it needs without interfering with any other
application.
The runtime tool java has a
-cp option, as well. This option is an
abbreviation for -classpath.
For very special cases, both java and javac have options that let you change the path they use to find their own class libraries. The vast majority of users will never to need to use those options, however.
In general, you will want to use the -classpath
command-line option, as explained in the previous section. This
section shows you how to set the CLASSPATH
environment variable if you want to do that, or clear settings
left over from a previous installation.
In csh, the CLASSPATH environment variable is
modified with the setenv command. The
format is:
setenv CLASSPATH
path1:path2
In sh, the CLASSPATH environment variable can
be modified with these commands:
CLASSPATH =
path1:path2:...
export CLASSPATH
If your CLASSPATH environment variable has been
set to a value that is not correct, or if your startup file or
script is setting an incorrect path, you can unset
CLASSPATH in csh by using:
unsetenv CLASSPATH
In sh, you would use:
unset CLASSPATH
These commands unset CLASSPATH for the current
shell only. You should also delete or modify your startup
settings to ensure that you have the right
CLASSPATH settings in future sessions.
If the CLASSPATH variable is set at system startup, the place to look for it depends on the shell you are running:
| Shell | Startup Script |
|---|---|
| csh, tcsh | Examine your .cshrc file for the
setenv command. |
| sh, ksh | Examine your .profile file for the
export command. |
Class path entries can contain the basename wildcard character *, which
is considered equivalent to specifying a list of all the files in the
directory with the extension .jar or .JAR. For
example, the class path entry foo/* specifies all JAR files
in the directory named foo. A classpath entry consisting
simply of * expands to a list of all the jar files in the current
directory. Files will be considered regardless of whether or not they are
hidden (that is, have names beginning with '.').
A class path entry that contains * will not match class files. To
match both classes and JAR files in a single directory foo,
use either foo:foo/* or foo/*:foo. The order
chosen determines whether the classes and resources in foo
are loaded before JAR files in foo, or vice versa.
Subdirectories are not searched recursively. For example,
foo/* looks for JAR files only in foo, not in
foo/bar, foo/baz, etc.
The order in which the JAR files in a directory are enumerated in the expanded class path is not specified and may vary from platform to platform and even from moment to moment on the same machine. A well-constructed application should not depend upon any particular order. If a specific order is required then the JAR files can be enumerated explicitly in the class path.
Expansion of wildcards is done early, prior to the invocation of a
program's main method, rather than late, during the
class-loading process itself. Each element of the input class path
containing a wildcard is replaced by the (possibly empty) sequence of
elements generated by enumerating the JAR files in the named directory.
For example, if the directory foo contains
a.jar, b.jar, and c.jar, then the
class path foo/* is expanded into
foo/a.jar:foo/b.jar:foo/c.jar, and that string would be the
value of the system property java.class.path.
The CLASSPATH environment variable is not treated any
differently from the -classpath (or -cp)
command-line option. That is, wildcards are honored in all these cases.
However, class path wildcards are not honored in the
Class-Path jar-manifest header.
Java classes are organized into packages which are mapped to
directories in the file system. But, unlike the file system,
whenever you specify a package name, you specify the
whole package name -- never part of it. For example, the
package name for java.awt.Button is always
specified as java.awt.
For example, suppose you want the Java runtime to find a
class named Cool.class in the package
utility.myapp. If the path to that directory is
/java/MyClasses/utility/myapp, you would set the
class path so that it contains
/java/MyClasses.
To run that app, you could use the following JVM command:
% java -classpath /java/MyClasses
utility.myapp.Cool
When the app runs, the JVM uses the class path settings to
find any other classes defined in the
utility.myapp package that are used by the
Cool class.
Note that the entire package name is specified in the
command. It is not possible, for example, to set the class path
so it contains /java/MyClasses/utility and use the
command java myapp.Cool. The class would not be
found.
(You may be wondering what defines the package name for a class. The answer is that the package name is part of the class and cannot be modified, except by recompiling the class.)
Note: An interesting consequence of the package specification mechanism is that files which are part of the same package may actually exist in different directories. The package name will be the same for each class, but the path to each file may start from a different directory in the class path.
When classes are stored in a directory (folder), like
/java/MyClasses/utility/myapp, then the class path
entry points to the directory that contains the first element
of the package name. (in this case,
/java/MyClasses, since the package name is
utility.myapp.)
But when classes are stored in an archive file (a .zip or .jar file) the class path entry is the path to and including the .zip or .jar file. For example, to use a class library that is in a .jar file, the command would look something like this:
% java -classpath
/java/MyClasses/myclasses.jar utility.myapp.Cool
To find class files in the directory
/java/MyClasses as well as classes in
/java/OtherClasses, you would set the class path
to:
% java -classpath
/java/MyClasses:/java/OtherClasses ...
Note that the two paths are separated by a colon.
The order in which you specify multiple class path entries
is important. The Java interpreter will look for classes in the
directories in the order they appear in the class path
variable. In the example above, the Java interpreter will first
look for a needed class in the directory
/java/MyClasses. Only if it doesn't find a class
with the proper name in that directory will the interpreter
look in the /java/OtherClasses directory.