Extension Mechanism Architecture |
Note: Optional packages are the new name forwhat used to be known asstandard extensions. The "extensionmechanism" is that functionality of the JDK™ and JRE™that supports the use of optional packages.This document describes the mechanism provided by theJava™ platform for handlingoptional packages. Anoptional package is a group of packages housed in one or moreJAR files that implement an APIthat extends the Java platform. Optional package classes extend theplatform in the sense that the virtual machine can find and loadthem without their being on the class path, much as if they wereclasses in the platform's core API.
Since optional packages extend the platform's core API, theiruse should be judiciously applied. Most commonly they are used forwell standardized interfaces such as those defined by the JavaCommunity Process, although itmay also be appropriate for site wide interfaces. Optional packagesare rarely appropriate for interfaces used by a single, or smallset of applications.
Furthermore, since the symbols defined byinstalled optional packages will be visible in allJava processes, care should be taken to ensure that all visiblesymbols follow the appropriate "reverse domain name" and "classhierarchy" conventions. For example, com.mycompany.MyClass.
An implementation of an optional package may consist of codewritten in the Java programming language and, less commonly,platform-specific native code. In addition, it may includeproperties, localization catalogs, images, serialized data, andother resources specific to the optional package.
Support for optional packages in browsers such as InternetExplorer and Netscape Navigator is available through theJava Plug-in.
A optional package is an implementation of an open, standard API(examples of optional packages from Sun areJavaServlet,Java3D,JavaManagement).Most optional packages are rooted in thejavax.*namespace, although there may be exceptions.
Architecture
The extension mechanism is designed to contain the followingelements:Applications must therefore, in general, be prepared to specifyand supply the optional packages (and, more generally,libraries) that it needs. The system will prefer installed copiesof optional packages (and libraries) if they exist; otherwise, itwill delegate to the class loader of the application to find andload the referenced optional package (and library) classes.
- an optional package or application packaged as a JAR file candeclare dependencies on other JAR files, thus allowing anapplication to consist of multiple modules, and,
- the class loading mechanism is augmented to search installedoptional packages (and other libraries) for classes, and, if thatfails, to search along an application-specified path forclasses.
This architecture, since it allows applications, applets andservlets to extend their own class path, also permits packaging anddeploying these as multiple JAR files.
Each optional package or application consists of at least oneJAR file containing an optional manifest, code and assortedresources. As described below, this primary JAR file can alsoinclude additional information in its manifest to describedependencies on other JAR files. Thejar commandline tool included with the JDK provides a convenient means ofpackaging optional packages. (See the reference pages for thejar tool: [Microsoft Windows] [Solaris™ Operating System(Solaris OS), Linux])
An optional package or application may refer to additional JARfiles which will be referenced from the primary JAR, and these canoptionally contain their own dependency information as well.
Packages comprising optional packages should be named per thestandard package naming conventions when implementing optionalpackages. These conventions are outlined inThe Java LanguageSpecification, but the requirement that the domain prefix bespecified in all upper case letters has been removed. For example,the package namecom.sun.server is an accepted alternativetoCOM.sun.server. Unique package naming is recommended inorder to avoid conflicts, because applications and optionalpackages may share the same class loader.
Optional Package Deployment
An optional package may either be bundled with an application orinstalled in the JRE for use by all applications. Bundled optionalpackages are provided at the same code base as the application andwill automatically be downloaded in the case of networkapplications (applets). For this reason, bundled optional packagesare often calleddownload optional packages. When themanifest of a bundled optional package's JAR file contains versioninformation and the JAR is signed, it can be installed into theextensions directory of the JRE which downloads it (seeDeploying JavaExtensions). Installed optional packages are loaded whenfirst used and will be shared by all applications using the sameJRE.When packaging optional packages, the JAR file manifest can beused to identify vendor and version information (seePackage VersionIdentification).
Classes for installed optional packages areshared by allcode in the same virtual machine. Thus, installed optional packagesare similar to the platform's core classes (inrt.jar),but with an associated class loader and a pre-configured securitypolicy as described below.
Classes for bundled optional packages areprivate to theclass loader of the application, applet or servlet. In the case ofnetwork applications such as applets, these optional packages willbe automatically downloaded as needed. Since class loaders arecurrently associated with a codebase, this permits multiple appletsoriginating from the same codebase to share implementations (JARs).However, signed bundled optional packages with version informationas described above are installed in the JRE, and their contents areavailable to all applications running on that JRE and are thereforenot private.
Bundled Optional Packages
The manifest for an application or optional package can specify oneor more relative URLs referring to the JAR files and directoriesfor the optional packages (and other libraries) that it needs.These relative URLs will be treated relative to the code base thatthe containing application or optional package JAR file was loadedfrom.An application (or, more generally, JAR file) specifies therelative URLs of the optional packages (and libraries) that itneeds via the manifest attributeClass-Path. Thisattribute lists the URLs to search for implementations of optionalpackages (or other libraries) if they cannot be found as optionalpackages installed on the host Java virtual machine*. Theserelative URLs may include JAR files and directories for anylibraries or resources needed by the application or optionalpackage. Relative URLs not ending with '/' are assumed to refer toJAR files. For example,
At most oneClass-Path header may be specified in a JARfile's manifest..Class-Path: servlet.jar infobus.jar acme/beans.jar images/Currently, the URLs must berelative to the code base ofthe JAR file for security reasons. Thus, remote optional packageswill originate from the same code base as the application.
Each relative URL is resolved against the code base that thecontaining application or optional package was loaded from. If theresulting URL is invalid or refers to a resource that cannot befound then it is ignored.
The resulting URLs are used to extend the class path for theapplication, applet, or servlet by inserting the URLs in the classpath immediately following the URL of the containing JAR file. Anyduplicate URLs are omitted. For example, given the following classpath:
a.jar b.jarIf optional packageb.jar contained the followingClass-Path manifest attribute:Class-Path: x.jar a.jarThen the resulting application class path would be the following:a.jar b.jar x.jarOf course, ifx.jar had dependencies of its own then thesewould be added according to the same rules and so on for eachsubsequent URL. In the actual implementation, JAR file dependenciesare processed lazily so that the JAR files are not actually openeduntil needed.Installed Optional Packages
Beginning with Sun's implementation of the Java 2 Platform, the JARfiles of a installed optional package are placed in a standardlocal code source:<java-home>\lib\ext [Microsoft Windows]<java-home>/lib/ext [Solaris OS, Linux]Here<java-home> refers to the directory wherethe runtime software is installed (which is the top-level directoryof the JRE or thejre directory in the JDK).
The locations for installed optional packages can be specifiedthrough the system propertyjava.ext.dirs. This propertyspecifies one or more directories to search for installed optionalpackages, each separated byFile.pathSeparatorChar. Thedefault setting forjava.ext.dirs is the standarddirectory for installed optional packages, as indicated above. ForJava 6 and later, the default is enhanced: it is suffixed with thepath 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 moreshared libraries (such as .dll files) and executables. In whatfollows, <arch> will be shown but in practice should be thename of an instruction set architecture, for examplesparc,sparcv9,i386, andamd64. These can be installed in one of two places. Thefirst 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 toJava 6 and later. As with Java packages, native libraries can beinstalled in directories that will be shared by all Java 6 andlater 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 bedownloaded by network code into the virtual machine at executiontime, whether such code is trusted or not. An optional package thatcontains native code and is bundled with a network application mustbe installed in the JDK or JRE.
By default, installed optional packages in this standarddirectory are trusted. That is, they are granted the sameprivileges as if they were core platform classes (those inrt.jar). This default privilege is specified in the systempolicy file (in<java-home>/jre/lib/security/java.policy), but canbe overridden for a particular optional package by adding theappropriate policy file entry (seePermissions in the JDK).
Note also that if a installed optional package JAR is signed bya trusted entity, then it will be granted the privileges associatedwith the trusted signer.
JAR files and packages can be optionallysealed,so that an optional package or package can enforce consistencywithin a version.A package sealed within a JAR specifies that all classes definedin that package must originate from the same JAR. Otherwise, aSecurityException is thrown.
A sealed JAR specifies that all packages defined by that JAR aresealed unless overridden specifically for a package.
A sealed package is specified via the manifest attribute,Sealed, whose value istrue orfalse(case irrelevant). For example,
specifies that thejavax.servlet.internal package issealed, and that all classes in that package must be loaded fromthe same JAR file.Name: javax/servlet/internal/Sealed: trueIf this attribute is missing, the package sealing attribute isthat of the containing JAR file.
A sealed JAR is specified via the same manifest header,Sealed, with the value again of eithertrue orfalse. For example,
specifies that all packages in this archive are sealed unlessexplicitly overridden for a particular package with theSealed attribute in a manifest entry.Sealed: trueIf this attribute is missing, the JAR file is assumed tonot be sealed, for backwards compatibility. The system thendefaults to examining package headers for sealing information.
Package sealing is also important for security, because itrestricts access to package-protected members to only those classesdefined in the package that originated from the same JAR file.
Package sealing is checked for installed as well as downloadedoptional packages, and will result in aSecurityExceptionif violated. Also, the null package is not sealable, so classesthat are to be sealed must be placed in their own packages.
The code source for a installed optional package(namely<java-home>/lib/ext) has a pre-configuredsecurity policy associated with it. In Sun's implementation, theexact level of trust granted to JARs in this directory is specifiedby the standard security policy configuration fileThe default policy is for a installed optional package to behavethe same way it would if were part of the core platform. Thisfollows from the common need for a installed optional package toload native code.<java-home>/lib/security/java.policyThe Java Security Model provides some safety when installedoptional package code is called from untrusted code. Howeveroptional package code must be carefully reviewed for potentialsecurity breaches wherever it uses privileged blocks.
A remotely loaded optional package that needs to useaccess-checked system services (such as file I/O) to functioncorrectly must either be signed by a trusted entity or loaded froma trusted source.
Consult the Javasecuritydocumentation for further details regarding how to writeoptional package and application code to use the security featuresof the Java Platform.
Several classes in the Java platform support theextension mechanism, including:
 |
