The Extension Mechanism





Documentation Contents 





Extension Mechanism Architecture






Contents



Introduction


The Extension Mechanism



Architecture


Optional Package Deployment


Bundled Optional Packages


Installed Optional Packages



Optional Package Sealing


Optional Package Security


Related APIs



Introduction


Note: Optional packages are the new name for what used to be known as
standard extensions. The "extension mechanism"
is that functionality of the JDK™ and JRE™
that supports the use of optional packages.


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 ProcessSM,
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.

A optional package is an implementation of an open, standard
API (examples of optional packages from Sun are JavaServlet,
Java3D, JavaManagement).
Most optional packages are rooted in the javax.* namespace,
although there may be exceptions.


The Extension Mechanism



Architecture
The extension mechanism is designed to contain the following elements:


an optional package or application packaged as a JAR file can declare dependencies
on other JAR files, thus allowing an application to consist of multiple
modules, and,


the class loading mechanism is augmented to search installed optional packages
(and other libraries) for classes, and, if that fails, to search along
an application-specified path for classes.

Applications must therefore, in general, be prepared to specify and
supply the optional packages (and, more generally, libraries) that it needs. The
system will prefer installed copies of optional packages (and libraries) if they
exist; otherwise, it will delegate to the class loader of the application
to find and load the referenced optional package (and library) classes.

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™ Operating System
(Solaris OS), Linux])

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.


Optional Package Deployment
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
(see Deploying Java
Extensions).
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.


Bundled Optional Packages
The manifest for an application or optional package can specify one or more relative
URLs referring to the JAR files and directories for the optional packages (and
other libraries) that it needs. These relative URLs will be treated relative
to the code base that the containing application or optional package JAR file
was loaded from.

An application (or, more generally, JAR file) specifies the relative
URLs of the optional packages (and libraries) that it needs via the manifest attribute
Class-Path. This attribute lists the URLs to search for implementations
of optional packages (or other libraries) if they cannot be found as optional packages
installed on the host Java virtual machine*. These relative URLs may include
JAR files and directories for any libraries or resources needed by the
application or optional package. Relative URLs not ending with '/' are assumed
to refer to JAR files. For example,

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

At most one Class-Path header may be specified in a JAR file's manifest..

Currently, the URLs must be relative to the code base of the
JAR file for security reasons. Thus, remote optional packages will originate from
the same code base as the application.

Each relative URL is resolved against the code base that the containing
application or optional package was loaded from. If the resulting URL is invalid
or refers to a resource that cannot be found then it is ignored.

The resulting URLs are used to extend the class path for the application,
applet, or servlet by inserting the URLs in the class path immediately
following the URL of the containing JAR file. Any duplicate URLs are omitted.
For example, given the following class path:
        a.jar b.jar
If optional package b.jar contained the following Class-Path
manifest attribute:
        Class-Path: x.jar a.jar
Then the resulting application class path would be the following:
        a.jar b.jar x.jar
Of course, if x.jar had dependencies of its own then these would
be added according to the same rules and so on for each subsequent URL.
In the actual implementation, JAR file dependencies are processed lazily
so that the JAR files are not actually opened until needed.


Installed Optional Packages
Beginning with Sun's implementation of the Java 2 Platform, the JAR files
of a 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.



Optional Package Sealing

JAR files and packages can be optionally sealed, so
that an optional package or package can enforce consistency within a version.

A package sealed within a JAR specifies that all classes defined in
that package must originate from the same JAR. Otherwise, a SecurityException
is thrown.

A sealed JAR specifies that all packages defined by that JAR are sealed
unless overridden specifically for a package.

A sealed package is specified via the manifest attribute, Sealed,
whose value is true or false (case irrelevant). For example,

Name: javax/servlet/internal/
Sealed: true

specifies that the javax.servlet.internal package is sealed, and
that all classes in that package must be loaded from the same JAR file.

If this attribute is missing, the package sealing attribute is that
of the containing JAR file.

A sealed JAR is specified via the same manifest header, Sealed,
with the value again of either true or false. For example,

Sealed: true

specifies that all packages in this archive are sealed unless explicitly
overridden for a particular package with the Sealed attribute
in a manifest entry.

If this attribute is missing, the JAR file is assumed to not be
sealed, for backwards compatibility. The system then defaults to examining
package headers for sealing information.

Package sealing is also important for security, because it restricts
access to package-protected members to only those classes defined in the
package that originated from the same JAR file.

Package sealing is checked for installed as well as downloaded optional packages,
and will result in a SecurityException if violated. Also, the
null package is not sealable, so classes that are to be sealed must be
placed in their own packages. 


Optional Package Security

The code source for a installed optional package (namely <java-home>/lib/ext)
has a pre-configured security policy associated with it. In Sun's implementation,
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.



Related APIs


Several classes in the Java platform support the extension
mechanism, including:


public class java.lang.ClassLoader


public class java.lang.Package

public class java.net.URLClassLoader




*As used on this web site, the terms "Java Virtual Machine"
or "JVM" mean a virtual machine for the Java platform.







Copyright © 1995-2010 Sun Microsystems, Inc. All Rights Reserved. Please send comments using this Feedback page.

Java Technology