# Deploying Java Extensions

Note: Java extensions are also referred to as optional packages, standard extensions, or simply extensions.

This section covers the following topics:

- Overview
- Manifest of the applet JAR file
- Manifest of each extension JAR file
- Manifest of the `Implementation-URL` JAR file
  - Raw installation
  - Java installer
  - Native installer
- Security
- Detailed Instructions
- Known Limitations and Other Notes

Java applets may use Java extensions to provide extra functionality to users. Java Plug-in enables applets to trigger installation of various Java extensions (e.g., JavaHelp, Java 3D, Java Media Framework ...) in the Java 2 Runtime Environment. This document describes the basic steps for deploying installed Java extensions (versus bundled Java extensions) with Java Plug-in. For details about how Java Extensions work, see the The Java Extensions Mechanism.

## 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:

1. Manifest of the applet JAR file

2. Manifest of each extension JAR

3. Manifest of the `Implementation-URL` JAR file

Each of these types of manifest files is described in detail below.

## 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:

>     Extension-List: RectangleArea RectanglePerimeter
>     RectangleArea-Extension-Name: com.mycompany.RectangleArea
>     RectangleArea-Specification-Version: 1.2
>     RectangleArea-Implementation-Version: 1.2
>     RectangleArea-Implementation-Vendor-Id: com.mycompany
>     RectangleArea-Implementation-URL: http://mycompany.com/RectangleArea.jar
>     RectanglePerimeter-Extension-Name: com.mycompany.RectanglePerimeter
>     RectanglePerimeter-Specification-Version: 1.2
>     RectanglePerimeter-Implementation-Version: 1.2
>     RectanglePerimeter-Implementation-Vendor-Id: com.mycompany
>     RectanglePerimeter-Implementation-URL: http://mycompany.com/RectanglePerimeter.jar

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:

- is the desired extension JAR itself (for raw installation) or
- contains a Java installer that will install the extension or
- contains a native installer that will install the extension.

This will be explained in detail in the section below called The manifest of the `Implementation-URL` JAR file.

### `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.

> > > `Extension-List: j3dcore
> > > j3dcore-Extension-Name: javax.media.j3d``
> > > ` `j3dcore-Specification-Version: 1.2
> > > j3dcore-Specification-Vendor: Sun Microsystems, Inc
> > > j3dcore-Implementation-Version: 1.2.1_03
> > > j3dcore-Implementation-Vendor-Id: com.sun
> > > j3dcore-Implementation-URL: http://<myserver>/native/java3d-win.jar`

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

## Note on JAR Extension Identification: Note that Java Plug-in checks four manifest attributes of an installed extension `JAR` file: `Extension-Name` `Specification-Version` `Implementation-Version` `Implementation-Vendor-Id` `Extension-Name` and `Implementation-Vendor-Id` must match exactly the values specified in the applet manifest file. See Optional Package Versioning for how Java Plug-in evaluates the version attributes of an installed extension to decide if a newer extension needs to be downloaded. See Appendix 6: Sun-Supported `Specification-Version` and `Implemenation-Version` Formats for rules about the format of `Specification-Version` and `Implemenation-Version`.

## 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:

- `Extension-Name`
- `Specification-Vendor`
- `Specification-Version`
- `Implementation-Vendor-Id`
- `Implementation-Vendor`
- `Implemenation-Version`

### Example

> `Extension-Name: javax.help
> Specification-Vendor: Sun Microsystems, Inc
> Specification-Version: 1.0
> Implementation-Vendor-Id: com.sun
> Implementation-Vendor: Sun Microsystems, Inc
> Implementation-Version: 1.1.3`

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.

See Optional Package Versioning for more information about these attributes.

## 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:

- By raw installation
- With a Java installer
- With a native installer

Each method is discussed below:

### 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:

> #### Example: Applet JAR manifest

>     Extension-List: mediax
>     mediaz-Extension-Name: javax.mediax
>     mediax-Specification-Version: 1.1
>     mediax-Implementation-Version: 1.1.2
>     mediax-Implementation-Vendor-Id: com.sun
>     mediax-Implementation-URL: http://java.sun.com/products/plugin/extensions/examples/media/mediax.jar

> #### Example: Extension JAR manifest

>     Extension-Name: javax.mediax
>     Specification-Vendor: Sun Microsystems, Inc
>     Specification-Version: 1.1
>     Implementation-Vendor-Id: com.sun
>     Implementation-Vendor: Sun Microsystems, Inc
>     Implementation-Version: 1.1.2

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.

> #### Example: Applet JAR manifest

>     Extension-List: mediax_core mediax_codec
>     mediax_core-Extension-Name: javax.mediax_core
>     mediax_core-Specification-Version: 1.1
>     mediax_core-Implementation-Version: 1.1.2
>     mediax_core-Implementation-Vendor-Id: com.sun
>     mediax_core-Implementation-URL: http://java.sun.com/products/plugin/extensions/examples/media/mediax_core.jar
>     mediax_codec-Extension-Name: javax.mediax_codec
>     mediax_codec-Specification-Version: 1.1
>     mediax_codec-Implementation-Version: 1.1.2
>     mediax_codec-Implementation-Vendor-Id: com.sun
>     mediax_codec-Implementation-URL: http://java.sun.com/products/plugin/extensions/examples/media/mediax_codec.jar

> Example: Extension JAR manifests

>     Extension-Name: javax.mediax_core
>     Specification-Vendor: Sun Microsystems, Inc
>     Specification-Version: 1.1
>     Implementation-Vendor-Id: com.sun
>     Implementation-Vendor: Sun Microsystems, Inc
>     Implementation-Version: 1.1.2

>     Extension-Name: javax.mediax_codec
>     Specification-Vendor: Sun Microsystems, Inc
>     Specification-Version: 1.1
>     Implementation-Vendor-Id: com.sun
>     Implementation-Vendor: Sun Microsystems, Inc
>     Implementation-Version: 1.1.2

### 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-URL` in 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.

> #### Example: Java Installer JAR manifest

>     Extension-Name: javax.help
>     Specification-Vendor: Sun Microsystems, Inc
>     Specification-Version: 1.1
>     Implementation-Vendor-Id: com.sun
>     Implementation-Vendor: Sun Microsystems, Inc
>     Implementation-Version: 1.1.3
>     Main-Class: com.sun.javahelp.installer

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-URL` in 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.

> #### Example: Native Installer Jar Manifest

>     Extension-Name: javax.media.jmf
>     Specification-Vendor: Sun Microsystems, Inc
>     Specification-Version: 2.1
>     Implementation-Vendor-Id: com.sun
>     Implementation-Vendor: Sun Microsystems, Inc
>     Implementation-Version: 2.1.1
>     Extension-Installation: jmf-2_1_1-win.exe

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/ext` directory. 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:

1. 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.
2. 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.
3. 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.

## Detailed Instructions

Follow these steps to set up extensions for use with Java Plug-in:

### I. Create/obtain the extensions that your applet needs.

Each extension will consist of one or more JAR files, each of which must include a manifest file with version information as described above in Manifest of each extension JAR file, and each must be signed. (See exception to this with mulitple JARs installed with native/Java installer.)

To create a JAR file from any set of files, use this command:

> `% jar cmf my_manifest my_jar input_files`

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:

1. Use the `keytool -genkey` option to generate a key pair.
2. 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.
3. You can then use the `keytool -import` option to import the chain to the keystore.
4. 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:

1. Create/obtain the installer.
2. 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.
3. 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.

The manifest would look like this:

>     Extension-Name: javax.media.jai
>     Specification-Vendor: Sun Microsystems, Inc
>     Specification-Version: 1.1
>     Implementation-Vendor-Id: com.sun
>     Implementation-Vendor: Sun Microsystems, Inc
>     Implementation-Version: 1.1.1_01
>     Extension-Installation: jai-1_1_1-01-windows-i586-jre.exe

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:

> `Extension-List: jai_core
> jai_core-Extension-Name: javax.media.jai
> jai_core-Specification-Version: 1.1
> jai_core-Implementation-Version: 1.1.1_01
> jai_core-Implementation-Vendor-Id: com.sun
> jai_core-Implementation-URL: http://myserver.com/jai_win.jar`

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`.

Assume the original applet looks like this:

>     <html>
>     <head>
>     <title>JaiApplet</title>
>     </head>
>     <body>
>     <APPLET code="JaiApplet.class" archive="JaiApplet.jar" align="absmiddle" WIDTH="400"HEIGHT="300"> </APPLET>
>     </body>
>     </html>

Then if we use the `HtmlConverter` to convert it for dynamic versioning, we will have this:

>     <html>
>     <head>
>     <title>JaiApplet</title>
>     </head>
>     <body>
>     <!--"CONVERTED_APPLET"-->
>     <!-- HTML CONVERTER -->
>     <OBJECT
>         classid = "clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"
>         codebase = "http://java.sun.com/products/plugin/autodl/jinstall-1_4-windows-i586.cab#Version=1,4,0,0"
>         WIDTH = "400" HEIGHT = "300" ALIGN = "absmiddle" >
>         <PARAM NAME = CODE VALUE = "JaiApplet.class" >
>         <PARAM NAME = ARCHIVE VALUE = "JaiApplet.jar" >
>         <PARAM NAME = "type" VALUE = "application/x-java-applet;version=1.4">
>         <PARAM NAME = "scriptable" VALUE = "false">
>         <COMMENT>
>     	<EMBED
>                 type = "application/x-java-applet;version=1.4"
>                 CODE = "JaiApplet.class"
>                 ARCHIVE = "JaiApplet.jar"
>                 WIDTH = "400"
>                 HEIGHT = "300"
>                 ALIGN = "absmiddle"
>     	    scriptable = false
>     	    pluginspage = "http://java.sun.com/products/plugin/index.html#download">
>     	    <NOEMBED>
>                 </NOEMBED>
>     	</EMBED>
>         </COMMENT>
>     </OBJECT>
>     <!--
>     <APPLET CODE = "JaiApplet.class" ARCHIVE = "JaiApplet.jar" WIDTH = "400" HEIGHT = "300" ALIGN = "absmiddle">
>     </APPLET>
>     -->
>     <!--"END_CONVERTED_APPLET"-->
>     </body>
>     </html>

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.

See Appendix 5: Complete Example—Deploying Java Media Framework as Java Extension for a complete, working example showing how to deploy the Java Media Framework as a Java Extension.

## 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.