This document describes the mechanism provided by the Java™ platform for handling optional packages. An optional package is a group of packages housed in one or more JAR files that implement an API that extends the Java platform. Optional package classes extend the platform in the sense that the virtual machine can find and load them without their being on the class path, much as if they were classes in the platform's core API.
Since optional packages extend the platform's core API, their use should be judiciously applied. Most commonly they are used for well standardized interfaces such as those defined by the Java Community Process, although it may also be appropriate for site wide interfaces. Optional packages are rarely appropriate for interfaces used by a single, or small set of applications.
Furthermore, since the symbols defined by installed optional packages will be visible in all Java processes, care should be taken to ensure that all visible symbols follow the appropriate "reverse domain name" and "class hierarchy" conventions. For example, com.mycompany.MyClass.
An implementation of an optional package may consist of code written in the Java programming language and, less commonly, platform-specific native code. In addition, it may include properties, localization catalogs, images, serialized data, and other resources specific to the optional package.
Support for optional packages in browsers such as Internet Explorer and Netscape Navigator is available through the Java Plug-in. See Applet Development Guide for more information.
A optional package is an implementation of an open, standard API (examples of optional packages JavaServlet, Java3D). Most optional packages are rooted in the javax.* namespace, although there may be exceptions.
This architecture, since it allows applications, applets and servlets to extend their own class path, also permits packaging and deploying these as multiple JAR files.
Each optional package or application consists of at least one JAR file containing an optional manifest, code and assorted resources. As described below, this primary JAR file can also include additional information in its manifest to describe dependencies on other JAR files. The jar command line tool included with the JDK provides a convenient means of packaging optional packages. (See the reference pages for the jar tool: [Microsoft Windows] [Solaris, Linux, or Mac OS X])
An optional package or application may refer to additional JAR files which will be referenced from the primary JAR, and these can optionally contain their own dependency information as well.
Packages comprising optional packages should be named per the standard package naming conventions when implementing optional packages. These conventions are outlined in The Java Language Specification, but the requirement that the domain prefix be specified in all upper case letters has been removed. For example, the package name com.sun.server is an accepted alternative to COM.sun.server. Unique package naming is recommended in order to avoid conflicts, because applications and optional packages may share the same class loader.
An optional package may either be bundled with an application or installed in the JRE for use by all applications. Bundled optional packages are provided at the same code base as the application and will automatically be downloaded in the case of network applications (applets). For this reason, bundled optional packages are often called download optional packages. When the manifest of a bundled optional package's JAR file contains version information and the JAR is signed, it can be installed into the extensions directory of the JRE which downloads it. Installed optional packages are loaded when first used and will be shared by all applications using the same JRE.
When packaging optional packages, the JAR file manifest can be used to identify vendor and version information (see Package Version Identification).
Classes for installed optional packages are shared by all code in the same virtual machine. Thus, installed optional packages are similar to the platform's core classes (in rt.jar), but with an associated class loader and a pre-configured security policy as described below.
Classes for bundled optional packages are private to the class loader of the application, applet or servlet. In the case of network applications such as applets, these optional packages will be automatically downloaded as needed. Since class loaders are currently associated with a codebase, this permits multiple applets originating from the same codebase to share implementations (JARs). However, signed bundled optional packages with version information as described above are installed in the JRE, and their contents are available to all applications running on that JRE and are therefore not private.
The JAR files of an installed optional package are placed in a standard local code source:
<java-home>\lib\ext [Microsoft Windows] <java-home>/lib/ext [Solaris OS, Linux]
Here <java-home> refers to the directory where the runtime software is installed (which is the top-level directory of the JRE or the jre directory in the JDK).
The locations for installed optional packages can be specified through the system property java.ext.dirs. This property specifies one or more directories to search for installed optional packages, each separated by File.pathSeparatorChar. The default setting for java.ext.dirs is the standard directory for installed optional packages, as indicated above. For Java 6 and later, the default is enhanced: it is suffixed with the path to a platform-specific directory that is shared by all JREs (Java 6 or later) installed on a system:
%SystemRoot%\Sun\Java\lib\ext [Microsoft Windows] /usr/java/packages/lib/ext [Linux] /usr/jdk/packages/lib/ext [Solaris OS]
An installed optional package may also contain one or more shared libraries (such as .dll files) and executables. In what follows, <arch> will be shown but in practice should be the name of an instruction set architecture, for example sparc, sparcv9, i386, and amd64. These can be installed in one of two places. The first to be searched is:
<java-home>\bin [Microsoft Windows] <java-home>/lib/<arch> [Solaris OS, Linux]
The second extension directory to be searched applies only to Java 6 and later. As with Java packages, native libraries can be installed in directories that will be shared by all Java 6 and later JREs:
%SystemRoot%\Sun\Java\bin [Microsoft Windows] /usr/java/packages/lib/<arch> [Linux] /usr/jdk/packages/lib/<arch> [Solaris OS]
An optional package that contains native code cannot be downloaded by network code into the virtual machine at execution time, whether such code is trusted or not. An optional package that contains native code and is bundled with a network application must be installed in the JDK or JRE.
By default, installed optional packages in this standard directory are trusted. That is, they are granted the same privileges as if they were core platform classes (those in rt.jar). This default privilege is specified in the system policy file (in <java-home>/jre/lib/security/java.policy), but can be overridden for a particular optional package by adding the appropriate policy file entry (see Permissions in the JDK).
Note also that if a installed optional package JAR is signed by a trusted entity, then it will be granted the privileges associated with the trusted signer.
The code source for a installed optional package (namely <java-home>/lib/ext) has a pre-configured security policy associated with it. The exact level of trust granted to JARs in this directory is specified by the standard security policy configuration file
<java-home>/lib/security/java.policy
The default policy is for a installed optional package to behave the same way it would if were part of the core platform. This follows from the common need for a installed optional package to load native code.
The Java Security Model provides some safety when installed optional package code is called from untrusted code. However optional package code must be carefully reviewed for potential security breaches wherever it uses privileged blocks.
A remotely loaded optional package that needs to use access-checked system services (such as file I/O) to function correctly must either be signed by a trusted entity or loaded from a trusted source.
Consult the Java security documentation for further details regarding how to write optional package and application code to use the security features of the Java Platform.
Several classes in the Java platform support the extension mechanism, including:
