How Classes are Found

SDK Tools

• How the Java Launcher Finds Classes
  • How the Java Launcher Finds Bootstrap Classes
  • How the Java Launcher Finds Extension Classes
  • How the Java Launcher Finds User Classes
  • How the Java Launcher Finds JAR-class-path Classes
• How Javac and Javadoc Find Classes
• Class Loading and Security Policies

How the Java Launcher Finds Classes

The Java launcher, java, initiates the Java virtual machine. The virtual machine searches for and loads classes in this order:

• Bootstrap classes - Classes that comprise the Java platform, including the classes inrt.jarand several other important jar files.

• Extension classes - Classes that use the Java Extension mechanism. These are bundled as.jarfiles located in the extensions directory.

• User classes - Classes defined by developers and third parties that do not take advantage of the extension mechanism. You identify the location of these classes using the -classpathoption on the command linethe preferred method) or by using the CLASSPATH environment variable. (SeeSetting the Classpath forWindows or Solaris.)

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

• It is relatively difficult to accidentally"hide" or omit the bootstrap classes.

• In general, you only have to specify the location of user classes. Bootstrap classes and extension classes are found "automatically".

• The tools classes are now in a separate archive (tools.jar) and can only be used if included in the user class path (to be explained shortly).

How the Java Launcher Finds Bootstrap Classes

Bootstrap classes are the classes that implement the Java2 Platform. Bootstrap classes are in thert.jarand several other jar files injre/lib directory. These archives are specified bythe value of the bootstrap class path which is stored in thesun.boot.class.path system property. This systemproperty is for reference only, and should not be directlymodified.

It is very unlikely that you will need to redefine thebootstrap class path. The nonstandard option,-Xbootclasspath, allows you to do so in those rarecicrcumstances in which it is necessary to use a different setof core classes.

Note that the classes which implement the Java 2 SDKtools are in separate archive from the bootstrap classes. Thetools archive is the SDK's/lib/tools.jar file. Thedevelopment tools add this archive to the user class path wheninvoking the launcher. However, this augmented user class pathis only used to execute the tool. The tools that processsource code,javac andjavadoc, use the originalclass path, not the augmented version. (For more information,seeHow Javac and Javadoc FindClasses, below.)

How the Java Launcher Finds Extension Classes

Extension classes are classes whichextend the Java platform. Every .jar file in theextension directory,jre/lib/ext, is assumed to be an extension and is loaded using theJava Extension Framework. Loose class files in the extension directory will not be found. They must be contained in a.jar file (or.zip file). There is no option provided for changing the location of the extension directory.

If the jre/lib/ext directory contains multiple .jar files, and those files contain classes with the same name, such as:

smart-extension1_0.jar contains class smart.extension.Smart
smart-extension1_1.jar contains class smart.extension.Smart


the class that actually gets loaded is undefined.

How the Java Launcher Finds User Classes

User classes are classes which build on the Javaplatform. To find user classes, the launcher refers to theuser class path -- a list of directories, JAR archives,and ZIP archives which contain class files.

A class file has a subpath name that reflects the class'sfull-qualified name. For example, if the classcom.mypackage.MyClass is stored under/myclasses, then/myclasses must bein the user class path and the full path to the class filemust be/myclasses/com/mypackage/MyClass.class. If theclass is stored in an archive namedmyclasses.jar, thenmyclasses.jarmust be in the user class path, and the class file must bestored in the archive ascom/mypackage/MyClass.class.

The user class path is specified as a string,with a colon (:) separating the class pathentries on Solaris, and a semi-colon (;) separating entries on Microsoft Windows systems. Thejava launcher puts the user class pathstring in the java.class.path systemproperty. The possible sources of this value are:

• The default value, ".",meaning that user class files are all class files in thecurrent directory (or under it, if in a package).

• The value of the CLASSPATH environment variable,which overrides the default value.

• The value of the -cp or -classpath commandline option, which overrides both the default value and theCLASSPATH value.

• The JAR archive specified by the -jar option, whichoverrides all other values. If this option is used, all userclasses come from the specified archive.

How the Java Launcher Finds JAR-class-path Classes

A JAR file usually contains a "manifest" -- a file which lists the contents of the JAR. The manifest can define a JAR-class-path, which further extends the class path (but only while loading classesfrom that JAR). Classes accessed by a JAR-class-path are found in the following order:

• In general, classes referenced by a JAR-class-path entry are found as though they were part of the JAR file. The JAR files that appear in the JAR-class-path are searched after any earlier class path entries, and before any entries that appear later in the class path.

• However, if the JAR-class-path points to a JAR file that was already searched (for example, an extension, or a JAR file that was listed earlier in the class path) then that JAR file will not be searched again. (This optimization improves efficiency and prevents circular searches.) Such a JAR file is searched at the point that it appears, earlier in the class path.

• If a JAR file is installed as an extension in the SDK's ext subdirectory, then any JAR-class-path it defines is ignored. All the classes required by an extension are presumed to be part of the SDK or to have themselves been installed as extensions.

How Javac and JavaDoc Find Classes

The javac and javadoc tools use class filesin two distinct ways:

• Like any Java application, javac and javadocmust load various class files in order to run.

• To process the source code they operate on, javacand javadoc must obtain information on object typesused in the source code.

The class files used to resolve source code references aremostly the same class files used to runjavac andjavadoc. But there are some important exceptions:

• Both javac and javadoc often resolvereferences to classes and interfaces that having nothing to dowith the implementation ofjavac orjavadoc. Information on referenced user classes andinterfaces may be present in the form of class files, sourcecode files, or both.

• The tools classes in tools.jar are only usedto run javac andjavadoc. The tools classes arenot used to resolve source code references unlesstool.jar is in the user class path.

• A programmer may want to resolve boot class or extensionclass references using an alternative Java platformimplementation. Bothjavac andjavadoc supportthis with their -bootclasspath and-extdirsoptions. Use of these options does not modify the set of classfiles used to run thejavac orjavadoc toolsthemselves.

If a referenced class is defined in both a class file andsource file, javadoc always uses the source file(javadoc never compiles source files). In the same situationjavac uses class files, but automatically recompilesany class files it determines to be out of date. The rules forautomatic recompilation are documented in the javacdocument for Windows or Solaris.

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

Class Loading and Security Policies

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

A program canload a class or interface by calling the loadClassmethod of a class loader object. But usually a program loads aclass or interface simply by referring to it. This invokes aninternal class loader, which can apply a security policy toextension and user classes. If the security policy has notbeen enabled, all classes are "trusted". Even if thesecurity policy is enabled, it does not apply to bootstrapclasses, which are always "trusted."

Whenenabled, security policy is configured by system and userpolicy files. The Java 2 SDK includes a system policy filethat grants "trusted" status to extension classesand places basic restrictions on user classes.

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

Note: Some security programming techniques thatworked with the Java 1.1 platform are incompatible with theclass loading model of the Java 2 Platform.