Overview

An applet that uses extensions is packaged as a signed JAR file including manifest.
When an applet is downloaded and run with Java Plug-in, Java Plug-in checks
the manifest of the applet JAR file. The manifest will contain a list of all
extensions that the applet requires. An extension consists of one or more JAR
files to be installed into the <jre>/lib/ext directory.

In general, for each extension the applet manifest will list name, vendor,
and version information of the extension JARs; it will also list URLs from which
the JARs, or an installer for them, may be obtained if the JARs are not already
installed <jre>/lib/ext or are out of date. A URL may directly
specify one of the extension JARs, or it may specify an installer, native or
Java, that will install the extension JARs. The rules for deciding that an update
is required are described in Optional
Package Versioning.

To use Java Plug-in for deploying Java Extensions, information about the extensions
must be specified in three different manifest files:

Manifest of the applet JAR file

To deploy Java extensions with an applet, the applet must be packaged as a
JAR file. Moreover, the manifest file of the applet JAR must define the list
of extensions it requires and specify the URLs from which the extensions can
be downloaded, along with other information about the extensions, according
to the Optional Package Versioning.
For example, below is the manifest file for two extensions:

In this example, two extensions are deployed with the appletRectangleArea
and RectanglePerimeter. Each has a single JAR file. If they have not
been installed or if updated versions are needed, the proper versions will be
downloaded from the Implementation-URL specifications. Notice that
an Implementation-URL must point to a JAR file that:

Extension-List names and attribute prefixes

There are two basic scenarios here: An extension may
have a single JAR file, or it may have multiple JAR files. Extension-List
names and attribute prefixes are discussed below for these two scenarios:

Extension with single JAR file

For an extension with a single JAR file (as in the example above), the name
in the Extension-List, and the prefix of the related manifest
attributes, should be the name of the extension JAR file.

Extension with multiple JAR files

Some extensions consist of multiple JAR files. For example, the Java 3D extension
consists of the following JAR files: j3daudio.jar, j3dcore.jar,
j3dutils.jar, and vecmath.jar. There are two scenarios
that need to be considered: (1) The JARs are installed by a native or Java
installer or (2) no installer is used (i.e., raw installation of the extension
JARs).

If a native or Java installer is used to install an extension, then
only one of the JAR file names should be used in the Extension-List,
and only one set of attributes, using that name as the prefix, should appear.
Usually an extension has a main JAR file; if so, you should use its name
in the Extension-List and as the prefix for the related manifest
attributes. If there is no main JAR file, you can use the name of any JAR
file in the optional package.

Here is an example of the applet manifest for the
Java 3D extension. j3dcore.jar is the main JAR file.

For a raw installation with multiple JAR files, the story is different:
You must treat each JAR file as though it were a separate extension and
list each according to its name in the Extension-List. Each
one listed then must have its own set of manifest attributes, where the
prefix for an attribute set is the name of the related JAR file.

Manifest of each extension JAR file

Here we are talking about the JAR files that Plug-in can obtain from the URLs
specified by Implemenation-URL. The URL-obtainable extension JARs
may be directly obtained (raw installation) or they may be obtained via a Java
or native installer. In either case they are installed into <jre>/lib/ext.

The extensions that the applet requires are listed in the applet manifest.
This allows Plug-in to examine the JAR files present in the <jre>/lib/ext
directory when an applet is launched and to decide if it needs to install missing
or out-of-date extensions.

In general, the manifest of an extension JAR obtained via an Implementation-URL
needs to include various name, version, and vendor information. Thus, when such
an extension JAR is installed, it will be possible in the future for Java Plug-in
to compare this information to the information about an extension that an applet
requests; and Plug-in will be able to determine if an extension needs to be
installed/upgraded. Prior to any applet ever requesting an extension, it is
more than likely that no extension is installed in <jre>/lib/ext,
or that no or incomplete manifest information is present in the installed extension
JAR.

For an extension with a single JAR file, the JAR file must be signed and include
a manifest file with the following attributes:

If an extension consists of more than one JAR file
and the extension is installed with a native/Java installer, then only the JAR
file whose name is listed in the Extension-List of the applet manifest
needs to have extension information (i.e., Extension-Name,
Specification-Version, etc.). If no installer is used, then
all JAR files must include extension information.

Manifest of the Implementation-URL
JAR file

This is the JAR file which the applet refers to with the Implementation-URL
attribute in its manifest. It is the URL from which the extension can be obtained
if no extension is installed in <jre>/lib/ext, or an extension
is installed but it is out of date.

If the Implementation-URL JAR is a native or Java installer, this
is indicated in the manifest via two special attributes: Main-Class
indicates a Java installer; Extension-Installation indicates native
installer. Note that if no installer is indicated, then the Implementation-URL
JAR file is simply the extension JAR file itself.

As implied from the above, there are three ways that extensions can be installed
by Java Plug-in:

Raw installation

With raw installation of an extension, each extension JAR is installed by Java
Plug-in into the <jre>/lib/ext directory without an installer
(Java or native); i.e., Java Plug-in is the "installer" for each JAR.
If an extension has a single JAR file, then the URL of that JAR is shown as
the Implementation-URL in the applet JAR manifest; and Java Plug-in
knows it is a raw extension because the manifest of the extension JAR file includes
neither Main-Class nor Extension-Installation attribute.

Suppose we have an extension called javax.mediax with a single
JAR, mediax.jar. Then the applet and extension JAR might be as
shown below:

Now suppose we have another version, javax.mediax-2, that has
two JARs: mediax_core.jar and mediax_codex.jar. Then
we must treat the two JAR files as though they were separate extensions and
list each in the applet JAR manifest.

Java Installer

An extension can be installed through a Java installer. The Java installer
must be bundled as a JAR file, and the resulting JAR file must be specified
as Implementation-URLin the applet JAR manifest file. During
installation the JAR file will be downloaded and verified, and the Main-Class
of the Java installer inside the JAR file will be executed to start the installer.
It is the job of the Java installer to copy the extension JAR files, normally
bundled with the installer, into the right location of the Java 2 Runtime (i.e.,
<jre>/lib/ext).

Though we are now dealing with an application JAR file, the attributes in its
manifest should be the same as those shown for the extension JAR whose name
is listed in the Extension-List of the applet manifestwith
the addition of the Main-Class attribute.

In this case, because Main-Class is present in the manifest, the
JAR will be treated as a Java Installer, and Main-class will be invoked.
It is the job of the Java installer to copy the extensions JAR files into the
<jre>/lib/ext directory. Note that each extension JAR file
must contain proper versioning information.

Native Installer

An extension can also be installed through a native installer. The native installer
must be bundled as a JAR file, and the resulting JAR file must be specified
as the Implementation-URLin the applet JAR manifest file.
During installation the JAR file will be downloaded and verified, and the native
installer will be started. It is the job of the native installer to copy the
extension JAR files, normally bundled with the installer, into the right location
of the Java 2 Runtime (i.e., <jre>/lib/ext).

Though we are now dealing with an application JAR file, the attributes in its
manifest should be the same as those shown for the extension JAR whose name
is listed in the Extension-List of the applet manifestwith
the addition of the Extension-Installation attribute.

In this case, because Extension-Installation is present in the
manifest, the JAR will be treated as a native installer; and the installer itself
will be launched. It is the job of the native installer to copy the Java extensions
into the <jre>/lib/extdirectory. Note that each Java
extension JAR file must contain proper versioning information.

Security

When an installed extension needs to be update, the extension will be downloaded
and verified to ensure that it is correctly signed. If it is valid, the Plug-in
will pop-up a security dialog providing three options:

Grant always: If selected, the Implementation-URL
JAR will be granted the AllPermission permission. Any sapplet
or extension signed with the same certificate will be trusted automatically
in the future, and no security dialog will pop up when this certificate is
encountered again. This decision can be changed from the Java Plug-in Control
Panel.

Grant this session: If selected, the Implementation-URL
JAR will be granted the AllPermission permission. Any applet
or extension signed with the same certificate will be trusted automatically
within the same browser session.

Deny: If selected, the installation is cancelled.

Once the user selects the options from the security dialog, the extensions
installation will be executed in the corresponding security context. The applet
will not be started until the extensions are properly installed.

Because Java extensions are downloaded and installed into the Java 2 Runtime
<jre>/lib/ext directory, each must be signed. Once the extensions
are installed, they will have the permissions granted to Java extensions through
the policy file.

For more information about the jar tool, see the Tools
and Utilities documentation for your platform.

To sign the JAR file is going to take some trouble. In outline form,
this is what you can do:

Use the keytool -genkey option to generate a key pair.

Use the keytool -certreq to generate a certificate request
for a Certificate Authority (CA), such as VeriSign
and Thawte. Email the request to the CA.
After the CA has confirmed your identity, it will respond with a certificate
chain via email. Copy the certificate chain to a file.

You can then use the keytool -import option to import the chain
to the keystore.

You can now use the jarsigner tool to sign the JAR and the
-verify option to check that it is signed.

For more information about keytool and jarsigner,
see the Tools and Utilities documentation
for your platform.

More information on this topic, along with examples, is given in the chapter
called How to Sign Applets Using RSA-Signed Certificates.
Although that chapter discusses how to sign an applet JAR file, the process
is identical to signing an extension JAR file.

II. Create/obtain the Implementation-URL JAR files

If no installer is to be used:

The extension JAR files described in step I are the Implementation-URL
JARs.

If an installer is to be used:

Create/obtain the installer.

Create the manifest for the JAR of the installer and any bundled extensions
that need to go into it.

For a Java installer include the Main-Class attribute in
the manifest;

for a native installer include the Extension-Installation
attribute.

JAR the installer, the manifest, and any bundled extensions that need to
be included and sign the JAR. (The steps for JARing and signing are the same
as described in step I above.)

Example

Suppose we have an applet that requires Sun's Java Advanced Imaging as an installed
extension. You can download this here:

http://java.sun.com/products/java-media/jai/downloads/download.html

Suppose you select the "Windows JRE Install" version. The following
file will be downloaded:

jai-1_1_1_01-lib-windows-i586-jre.exe

This installer bundles the following JAR files, which it will install into
the <jre>/lib/ext directory:

jai_codec.jar

jai_core.jar

mlibwrapper_jai.core

You need to create the manifest for a JAR file that contains the .exe
installer above, and you need to sign the JAR file.

Now JAR up the installer as jai_win.jar, together with the manifest
file. You don't need to include the extension JAR files, as they are bundled
with the .exe installer in this case. Be sure to include the .jar
extension in the JAR file name.

Now sign jai_win.jar.

III. Create the applet JAR

1. Create a manifest file for the applet. Below is a manifest file for the
jai example using a native installer:

Some optional packages come packaged in different JAR files for different operating
systems. If you want your applet to work on different OSs, you can use the $(os-name)$
construction in the Implementation-URL manifest attribute. The
$(os-name)$ will translate to the target OS that the applet is
being run oni.e., SunOS, Linux, Windows-98, Windows-NT, Windows-2000,
Windows-Me.

optpkg-Implementation-URL: http://.../optpkg-$(os-name)$.jar

2. JAR up the *.class files, and any other supporting files the
applet needs, together with the applet's manifest file, and sign the JAR. (The
procedure for JARing your files and signing the JAR is the same as discussed
previously.) Be sure to include the .jar extension in the JAR file
name.

IV. Generate the HTML to launch the applet

Create the HTML page for the applet. You can do this manually or you can use
the HtmlConverter that comes with the JDK. It is recommended that
you use the HtmlConverter. But if you want to do it manually, see
Using OBJECT, EMBED and
APPLET Tags in Java Plug-in for information on how to do it.
Note that the applet JAR file should go in the archive attribute.

Suppose your applet is called JaiApplet, the JAR file you created
for it is called JaiApplet.jar, and the main class is JaiApplet.class.

When you run the applet Java Plug-in will display a Java Security Warning if
the extension is not already installed, informing you the applet requires installation
of extension javax.media.jai from http://myserver.com/jai_win.jar.
If you grant permission to install the extension, the installer will install
the JAR files in the <jre>/lib/ext directory. Once the installation
is complete your applet will run.

Known Limitations and Other Notes

If an Implementation-URL JAR file is not signed properly, Java
Plug-in will fail silently.

For any extension be sure that a newer version of the extension contains
at least the same set of JAR file names as the older version. Otherwise, installing
a newer extensions may not overwrite all the older extensions JARs, and there
will be a mix of different versions of an extension in <jre>/lib/ext.
The results will be unpredictable.

If Java Installer is used, make sure the program does not exit the Main-class
until the installation is done. In some cases, Java Installer may create an
AWT window and switch control to a different thread and return immediately
from the Main-class. Returning control from the Main-class
will force the applets to be loaded and started immediately, even if the Java
Installer is still in the process of installation. This will cause the applet
to fail to load because the extension is not installed yet.