Configuration of JDK 1.2 Software under Win32

Files and Directories
Setting Environment Variables
How the Java Launcher Finds User Classes
How the Java Launcher Finds Bootstrap Classes
How the Java Launcher Finds Extension Classes
Search Order for Classes
How the Oldjava Launcher Finds Classes
Loading Classes
How Javac and Javadoc Find Classes
See Also

FILES AND DIRECTORIES

The directories containing demos, sample source code, C header files, and documentation are not required to run the JDK software. This section describes the files and directories that are required. The following chart gives the most important directories:

Assuming the JDK software is installed at c:\jdk1.2beta4, here are the crucial directories and why they are important:

c:\jdk1.2beta4
The root directory of the JDK software installation. Contains copyright, license, and README files.

c:\jdk1.2beta4\bin
The executable files for the development tools. The PATH environment variable should contain an entry for this directory.

c:\jdk1.2beta4\lib
Files used by the development tools. These include tools.jar, which contains classes and resources required to run the development tools.

c:\jdk1.2beta4\jre
The root directory of the "private" Java runtime environment used by the JDK development tools. The runtime environment is an implementation of the Java 1.2 platform.

c:\jdk1.2beta4\jre\bin
Executable files for the java and rmiregistry tools and .dll libraries used by the Java platform. The files java.exe and rmiregistry.exe are identical to files in c:\jdk1.2beta4\bin. Here, the java launcher tool serves as a deployment launcher, in place of the old jre tool. This directory does not need to be in the PATH environment variable.

c:\jdk1.2beta4\jre\bin\classic
Files that implement a "classic" Java virtual machine.

c:\jdk1.2beta4\jre\lib
Code ibraries, property settings, and resource files used by the Java runtime environment. These include rt.jar, which contains the bootstrap classes. Aside from the ext subdirectory (described below) there are several resource subdirectories not described here.

c:\jdk1.2beta4\jre\lib\ext
Default installation directory for Extensions.

c:\jdk1.2beta4\jre\lib\security
Contains files used for security management. These include the security policy (java.policy) and security properties (java.security) files.

In previous releases, a single archive, classes.zip, contained both tool classes and bootstrap classes. These classes are now divided between tool.jar and rt.jar.

SETTING ENVIRONMENT VARIABLES

There are three ways to set Win32 environment variables:

A set command entered in a Command Prompt or MS-DOS Prompt window. Environment settings only affect commands run from the same window and are lost when the window is closed.
A set command included in a batch or command file. Commands included in \autoexec.bat on your boot drive are executed every time you reboot -- but only when you reboot. On Windows 95, permanent environment settings should go in c:\autoexec.bat.
(Windows NT only.) In the Control Panel, choose the System Properties icon and the Environment tab. On Windows NT, use this dialog for permanent settings.

Here's a set command example setting the CLASSPATH environment variable:

    set CLASSPATH=c:\myclasses;.

Never put spaces directly before or after the equals sign:

    set CLASSPATH = c:\myclasses;.

These spaces will be interpreted as part of the variable name or value!

For a summary of environment variables used by JDK software, see Installation and Configuration. For specifics on the CLASSPATH environment variable, see the next section.

HOW THE JAVA LAUNCHER FINDS USER CLASSES

User classes are classes which build on the Java platform. To find user classes, the launcher refers to the user class path, a list of directories, JAR archives, and ZIP archives containing class files.

A class file has a subpath name that reflects the class's full-qualified name. For example, suppose the class com.mypackage.MyClass is stored under c:\myclasses, and c:\myclasses is in the user class path. Then the class file must be c:\myclasses\com\mypackage\MyClass.class. If this same class is defined in an archive named myclasses.jar, then myclasses.jar must be in the user class path, and the class file must be stored in the archive as com\mypackage\MyClass.class.

On Win32, the user class path is specified as a string, with a semicolon (;) separating the class path entries. The java launcher puts the user class path string in the java.class.path system property. The possible sources of this value are, in increasing order of precedence:

The default value, ".", meaning that all user class files are under the current directory.
The value of the CLASSPATH environment variable, which overrides the default value.
The value of the -cp or -classpath command line option, which overrides both the default and the CLASSPATH values.
If the -jar option is used, all user classes come from the specified JAR archive.

HOW THE JAVA LAUNCHER FINDS BOOTSTRAP CLASSES

Bootstrap classes are the classes that implement the Java 1.2 platform. In the example JDK software installation described above, the bootstrap classes are in two archives in c:\jdk1.2beta4\jre\lib: rt.jar, i18n.jar. To find the system classes, the runtime refers to a bootstrap class path, similar to the the user class Path described above. The value of the bootstrap class path is stored in the sun.boot.class.path system property. This system property is for reference only, and should not be directly modified.

It is very unlikely that you will need to redefine the bootstrap class path. The nonstandard option, -Xbootclasspath, allows you to do this.

Note that the classes which implement the JDK development tools are in separate archive from the bootstrap classes. (In the above example, the tools archive is c:\jdk1.2beta4\lib\tools.jar.) The development tools add tools.jar to the user class path when invoking the launcher. However, this augmented user class path is only used to execute the tool. The tools that process source code, javac and javadoc refer to the original user class path. See How Javac and Javadoc Find Classes, below.

HOW THE JAVA LAUNCHER FINDS EXTENSION CLASSES

Every .jar file in the extension directory is assumed to be a Extension and loaded using the Java Extension Framework. There is no option provided for changing the location of the extension directory.

SEARCH ORDER FOR CLASSES

When resolving a class name, the runtime searches first in the bootstrap class Path, then each Extension, then in the user class path.

In effect, these three parts are joined to form a simple class path. This is similar to the "flat" class path previously used. The current model has some important differences:

It is relatively difficult to accidentally "hide" or omit the bootstrap classes.
The tools classes are now in a separate archive, and can only be used if included in the user class path.

HOW THE OLDJAVA LAUNCHER FINDS CLASSES

The oldjava launcher combines the bootstrap and user classes in a single class path. (The oldjava launcher does not support the Java Extensions Framework.) There are two ways to specify a class path with oldjava:

Specify a user class path in the CLASSPATH environment variable. The user class path is appended to the pre-defined bootstrap class path.
Specify a complete class path with the -cp or -classpath command line option. Both the value of CLASSPATH and the pre-defined bootstrap class path are ignored.

The combined class path is stored in the java.class.path system property.

LOADING CLASSES

To be used, a class or interface must be loaded by a class loader. Use of a particular class loader determines a security policy associated with the class loader.

A program can load a class or interface by calling the loadClass method of a class loader object. But usually a program loads a class or interface simply by referring to it. This invokes an internal class loader, which can apply a security policy to extension and user classes. If the security policy has not been enabled, all classes are "trusted". Even if the security policy is enabled, it does not apply to bootstrap classes, which are always "trusted."

When enabled, security policy is configured by system and user policy files. The JDK software includes a system policy file that grants "trusted" status to extension classes and places basic restrictions on user classes.

To enable or configure the security policy, refer to Security Features.

Some security programming techniques that worked with the Java 1.1 platform are incompatible with the 1.2 class loading model. To provide temporary support for existing code, this release includes the oldjava launcher, which uses the 1.1 class loading model.

HOW JAVAC AND JAVADOC FIND CLASSES

The javac and javadoc tools use class files in two distinct ways:

Like any Java application, javac and javadoc must load various class files in order to run.
In order to process Java programming language source code, javac and javadoc must obtain information on object types used in the source code.

The class files used to resolve source code references are mostly the same class files used to run javac and javadoc. But there are some important exceptions:

Both javac and javadoc often resolve references to classes and interfaces that having nothing to do with the implementation of javac or javadoc. Information on referenced user classes and interfaces may be present in the form of class files, source code files, or both.
The tools classes in tools.jar are only used to run javac and javadoc. The tools classes are not used to resolve source code references unless tool.jar is in the user class path.
A programmer may want to resolve boot class or extension class references using an alternative Java platform implementation. Both javac and javadoc support this with their -bootclasspath and -extdirs options. Use of these options does not modify the set of class files used to run the javac or javadoc tools themselves.

If a referenced class is defined in both a class file and source file, javadoc always uses the source file. In the same situation javac uses class files, but automatically recompiles any class files it determines to be out of date. The rules for automatic recompilation are documented in the Javac Tool Document.

By default, javac and javadoc search the user class path for both class files and source code files. If the -sourcepath option is specified, javac and javadoc search only the specified source file path.