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

Manifest of the applet JAR file
Manifest of each extension JAR
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://example.com/RectangleArea.jar
RectanglePerimeter-Extension-Name: com.example.RectanglePerimeter
RectanglePerimeter-Specification-Version: 1.2
RectanglePerimeter-Implementation-Version: 1.2
RectanglePerimeter-Implementation-Vendor-Id: com.example
RectanglePerimeter-Implementation-URL: http://example.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. There are three ways that extensions can be installed by Java Plug-in. They are:

Using Raw Installation
Using Java Installer
Using Native Installer

Each method is discussed below:

Installing Java Extensions Using 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
mediax-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_codec.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

Installing Java Extensions Using 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 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.

Installing Java Extensions Using 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 Runtime (i.e., <jre>/lib/ext).

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 updated, the extension will be downloaded and verified to ensure that it is correctly signed. If it is valid, the Plug-in may pop-up a security dialog providing user with an option to continue with extension installation or cancel the installation.

Once the user selects the option 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 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:

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.

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.example.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/update/1.6.0/jinstall-6-windows-i586.cab#Version=6,0,0,99"
    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.6">
    <PARAM NAME = "scriptable" VALUE = "false">
    <COMMENT>
    <EMBED 
            type = "application/x-java-applet;version=1.6" 
            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.example.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.

Deploying Java Extensions

Overview

Manifest of the applet JAR file

Extension-List names and attribute prefixes

Extension with single JAR file

Extension with multiple JAR files

Note on JAR Extension Identification:

Manifest of each extension JAR file

Example

Manifest of the Implementation-URL JAR file

Installing Java Extensions Using Raw Installation

Example: Applet JAR manifest

Example: Extension JAR manifest

Example: Applet JAR manifest

Installing Java Extensions Using Java Installer

Example: Java Installer JAR manifest

Installing Java Extensions Using Native Installer

Example: Native Installer Jar Manifest

Security

Detailed Instructions

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

II. Create/obtain the Implementation-URL JAR files

If no installer is to be used:

If an installer is to be used:

Example

III. Create the applet JAR

IV. Generate the HTML to launch the applet

Known Limitations and Other Notes

`Extension-List` names and attribute prefixes

Manifest of the `Implementation-URL` JAR file

II. Create/obtain the `Implementation-URL` JAR files