Java

Extensions - An Overview

Contents

What an extension is

Extensions 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 extension 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 core API such as java.lang, java.io, etc., and classes supporting the platform's internationalization/localization features.). Like bootstrap classes, classes in extensions do not have to be placed on the class path. The extension mechanism also provides a way for needed extensions to be retrieved from specified URLs when they are not already installed in the JRE or JDK software.

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

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 extensions. If it doesn't find the class among either the bootstrap classes or the installed extensions, the VM will search among any download extensions 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 extension classes.

Installed extensions

Installed extensions are JAR files in the directory
jre/lib/ext
The jre directory can be either the top-level directory of the Java Runtime Environment or the jre directory in the JDK software directory hierarchy. 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 extension'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 i386. Native libraries may also be placed in jre/lib/ext/<arch> for both Win32 and Solaris, where <arch> will be i386 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 set of bootstrap classes. If it fails to find the desired class among the system classes, the VM will then search for the class in any JAR files in jre/lib/ext.

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

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

Download extensions

A download extension is a JAR files that is specified in the Class-Path header field in the manifest of another JAR files. Classes in download extensions 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 extension for the purposes of that applet. Extensions 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 extensions 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 extensions, the location of the JAR files that serve as download extensions is irrelevent. A download extension is an extension 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 extensions is that only applets and applications bundled in a JAR file can make use of download extensions. Applets and applications not bundled in a JAR file don't have a manifest from which to reference download extensions.

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

The extension mechanism will not install a download extension in the JRE or JDK directory structure. Download extensions do not become installed extentions after they have once been downloaded.

Unlike installed extensions, download extensions cannot have any native code.

Considerations when making an installed extension

There are several points to consider when you want to turn your classes into an extension.
  1. If your extension contains code that performs security-sensitive operations like reading from or writing to files, you'll need to consider making such code "privileged". You make your code privilged by enclosing it in a call to java.security.AccessController.doPrivileged. See API for Privileged Blocks in the JDK Security Documentation for details. When your code is privileged, the security manager can grant it permission to perform security-sensitive operations. If your extension contains security-sensitive code that isn't privileged, it won't work if it's called from untrusted (applet) code. If you don't care about that scenario, you can leave the doPrivileged calls out.

  2. You should bundle your extension classes in one or more JAR files. You can put vendor and versioning information for your extension in the JAR files' manifest. See the Versioning Specification for details. Versioning information in the manifest can be used during the installation of your extension to prevent overwriting a more recent version of your software that already may be installed. For general information on JAR files, see the JDK documentation on JAR Features.

  3. You'll need to prepare an installer and/or installation instructions for your extension to ensure that it can be used properly by the Java platform's extension mechanism. The proper location for installing class files and native code libraries for your extension are detailed in the Extension Specification.

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

Java Software