| # Optional Packages - An Overview

## Contents

- What an optional package is
- Installed optional packages
- Download optional packages

## What an optional package is

Note: Optional packages were formerly known as standard extensions or just extensions.

Optional packages are packages of Java classes and associated native code that application developers can use to extend the functionality of the core platform. The extension mechanism allows the Java virtual machine (VM) to use the optional-package classes in much the same way as the VM uses bootstrap classes. (Bootstrap classes are those implementing the core platform, contained in `jre/lib/rt.jar` and `jre/lib/i18n.jar`. These include classes of the public API such as `java.lang`, `java.io`, etc., and classes supporting the platform's internationalization/localization features.). Like bootstrap classes, classes in optional packages do not have to be placed on the class path. The extension mechanism also provides a way for needed optional packages to be retrieved from specified URLs when they are not already installed in the Java 2 Runtime Environment or Java 2 SDK.

Optional packages are embodied in JAR files, and every JAR file is a potential optional package. A JAR file can be made to play the role of an optional package in two ways:

- by being placed in a special location in the Java 2 Runtime Environment or Java 2 SDK directory structure - in which case it is an installed optional package.
- by being referenced in a specified way from the manifest of the JAR file of an applet or application - in which case it is a download optional package.

When the VM is searching for a class of a particular name, it will first look among the bootstrap classes. If it fails to find the desired class there, it will next look for the class among any installed optional packages. If it doesn't find the class among either the bootstrap classes or the installed optional packages, the VM will search among any download optional packages referenced by the application or applet. The VM only searches the class path if it fails to find a class among the bootstrap classes or optional package classes.

## Installed optional packages

Installed optional packages are JAR files in the directory

>     lib/ext       [in the Java 2 Runtime Environment]
>     jre/lib/ext   [in the Java 2 SDK]

Classes within JAR files in this directory can be used by applets and applications much as if they were part of the set of bootstrap classes, without having to explicitly include them in the class path.

An installed optional package's native code binaries, if any, are placed in

>     jre\bin         [Win32]
>     jre/lib/<arch>  [Solaris]

where `<arch>` is the Solaris processor architecture, either `sparc` or `x86`. Native libraries may also be placed in `jre/lib/ext/<arch>` for both Win32 and Solaris, where `<arch>` will be `x86` on Win32 systems. The `jre/lib/ext/<arch>` directory is searched after `jre\bin` (win32) or `jre/lib/<arch>` (Solaris).

When the Java VM encounters a class name, it looks first for the class in the runtime environment. If it fails to find the desired class among the classes that are part of the standard runtime environment, the VM will search for the class in any JAR files in the optional packages directory.

Note that there is nothing special about any particular JAR file itself or the classes it contains that makes it an installed optional package. It is an installed optional package by virtue of its location in `jre/lib/ext`.

The manifest of an installed optional package's JAR file should contain version and vendor information for use by applets that need to use the optional packages classes. The attributes that specify the version and vendor information are described in Optional Package Versioning. Here is an example of what such a manifest might look like:

>     Manifest-version: 1.0
>     Extension-Name: javax.extension
>     Specification-Version: 1.0
>     Specification Vendor: Sun Microsystems, Inc.
>     Implementation-Vendor: Sun Microsystems, Inc.
>     Implementation-Vendor-Id: com.sun
>     Sealed: true

This version and vendor information can be used by the Java Plug-in when running an applet to see if optional packages needed by the applet are installed, are up to date, and are from the vendor requested by the applet. If not, the Java Plug-in can prompt the applet user to download the proper optional package. See Optional Package Versioning for more information.

If a class is not found after searching both the system classes and the classes in the installed optional packages, the extension mechanism will search for the class in a download optional package....

## Download optional packages

A download optional package is a JAR files that is specified in the `Class-Path` header field in the manifest of another JAR files. Classes in download optional packages may be used by classes in the referencing JAR file. In a typical situation, an applet will be bundled in a JAR file whose manifest references a JAR file (or several JAR files) that will serve as an optional package for the purposes of that applet. Optional packages may reference each other in the same way.

A `Class-Path` header might look like this, for example:

>     Class-Path: servlet.jar infobus.jar acme/beans.jar

This specifies that the classes in the files `servlet.jar`, `infobus.jar`, and `acme/beans.jar` will serve as optional pakcages for purposes of the classes in the JAR file whose manifest contains this header. The URLs in the Class-Path field are given relative to the URL of the JAR file of the applet or application.

Unlike the case of installed optional packages, the location of the JAR files that serve as download optional packages is irrelevent. A download optional package is an optional package because it is specified as the value of the `Class-Path` header in another JAR file's manifest, not because it has any particular location.

Another difference between installed and download optional packages is that only applets and applications bundled in a JAR file can make use of download optional packages. Applets and applications not bundled in a JAR file don't have a manifest from which to reference download optional packages.

When searching for a class, the VM first searches among the classes in the system classes and in any installed optional packages. If the class is not found in either the system classes or in the installed optional packages, the VM will search for the class in any download optional packages referenced by the manifest of the application or applet. A download optional package will not be downloaded if a desired class is found among the installed optional packages, even if the download optional package is referenced by the manifest file of the applet or application.

The extension mechanism will not install a download optional package in the Java 2 Runtime Environment or Java 2 SDK directory structure. Download optional packages do not become installed extentions after they have once been downloaded.

Unlike installed optional packages, download optional packages cannot have any native code.

Copyright © 1997, 1998 Sun Microsystems, Inc. All Rights Reserved. | Java Software