Deploying Java Extensions

Note: Java Extensions are also referred to as Optional Packages.

This section covers the following topics:

Overview
Specifying Java Extensions in the Applet
Java Extensions Installation
Detailed Instructions
How It Works
Security
Known Limitations

Java applets may use various Java Extensions to provide certain functions to users. Deploying Java Extensions dynamically with Java applets in Java Plug-in has been a challenge to developers, especially those with thousands of machines in an intranet/Internet environment.

Java Extensions Installation enables various Java Extensions (e.g., JavaHelp, Java3D ...) to be deployed and installed easily along with Java applets in the Java 2 Runtime Environment. This document outlines the basic steps for deploying Installed Java Extensions in Java Plug-in. For details about how Java Extensions works, please see the Java Extensions Mechanism documentation in Java 2.

Overview

To use Java Extensions Installation in Java Plug-in, information about the extensions must be specified in three places:

MANIFEST of the applet's JAR files
If the applet requires Java Extensions Installation, the applet MUST define the list of Java Extensions Installation it requires in the MANIFEST and specify the URLs from which to download the extensions.
MANIFEST of the Java Extension Jar files to be installed (i.e., JAR files that will be downloaded to the \lib\ext directory)
The purpose is to make known the extension name, version, and vendor info within the extension JAR file itself. Therefore, Java Plug-in will be able to compare the extension name, version, and vendor info of all the installed extensions (i.e., inside lib/ext) to the extension the applet requests; and Java Plug-in will then be able to determine if the extensions need to be installed/upgraded.
MANIFEST of the Java Extension Installation's JAR file
This is the JAR file which the applets refer to with the Implementation-URL attribute in the MANIFEST. The purpose is to indicate the extension installation type, so the installation will be triggered properly.

Specifying Java Extensions in the Applet

To deploy Java Extensions with applets, the applet must be packaged as a JAR file. The MANIFEST file of the applet must contain proper information about the Java Extensions to be installed, according to the Optional Package Versioning. For example,

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. If they have not been installed or if updates are needed, the proper versions will be downloaded from the Implementation-URL specifications. Notice that an Implementation-URL must point to a JAR file which is the Java Extensions Installation.

Note on Proper JAR Extension Identification:

Note that Java Plug-in checks four MANIFEST.MF 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 JAR MANIFEST.MF 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.

Sun-Supported `Specification-Version` and `Implemenation-Version` Formats

Specification-Version and Implementation-Version follow these rules for Sun products, and third-party products must follow the same rules for Java Plug-in to make reliable decisions about whether an extension is up-to-date or not:

The Specification-Version string will be of the form:

n1.n2[.n3]

where n1, n2, and n3 are integers, n1.n2 is the major version number, and optional n3 is the minor version number (also referred to as the maintenance version number).

The Implementation-Version will be of the same form initially but may:

append with a preceding underscore("_") n4n5 to indicate a patch version number (also referred to as the update version number)
or append with a hyphen ("-") a milestone name (ea , alpha, beta, rc ...), which may also include a trailing integer number (ea1, beta2, rc1 ...).

Both patch version number and milestone name may not be used together in the Implemenation-Version string.

The general form is as follows:

n1.n2[.n3][_<patch_number>|-<milestone_name>]

Integers (n1,n2, n3 ...), letters, dots, hyphens, and underscores , may be used in the version format as described above; no other characters ("*", "+" ...) are allowed.

Note that the Specification-Version and Implementation-Version numbers are in theory independent, though in practice they are often in sync with each other.

Examples:

Specification-Version examples: 1.3, 1.4

Implementation-Version examples: 1.3.1, 1.4.0_02, 1.4.0-beta3

While these are the rules, it is always a good idea when using a third-party extension JAR to examine its MANIFEST.MF file to see what actual values are in it. If it does not follow these rules, you may need to change your applet JAR MANIFEST.MF accordingly or alter the extension JAR.

Java Extensions Installation

Three types of Java Extensions Installation are supported in Java Plug-in:

Raw Java Extensions
Java Extensions consist of several JAR files. In the applet's MANIFEST file, these raw Java Extensions are specified through the Implementation-URL. During installation, these Java Extensions JAR files will be downloaded and verified, and copied into the Java 2 Runtime lib/ext directory.

Java installer
Java Extensions are 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's 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 Java Extensions inside the installer into the right location of the Java 2 Runtime (i.e., lib/ext).

Native installer
Java Extensions are installed through a native installer. The native installer must be bundled as a JAR file, and the resulting JAR file must be specified as Implementation-URL in the applet's 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 Java Extensions inside the installer into the right location of the Java 2 Runtime (i.e., lib/ext).

To ensure the Java Extensions Installations are downloaded and installed properly, they must be bundled as JAR files and be specified as Implementation-URL in the applet's MANIFEST. Each Java Extension itself must be bundled as a JAR files and contain proper versioning information in its own MANIFEST file according to Optional Package Versioning. For example,

Raw Java Extensions:

Extension-Name: javax.help 
Specification-Vendor: Sun Microsystems, Inc 
Specification-Version: 1.4 
Implementation-Vendor-Id: com.sun 
Implementation-Vendor: Sun Microsystems, Inc 
Implementation-Version: 1.4.0_01

In this case, it will be recognized as a raw Java Extension, and will be copied into the lib/ext directory directly.

Java Installer:
```
Extension-Name: javax.help 
Specification-Vendor: Sun Microsystems, Inc 
Specification-Version: 1.4 
Implementation-Vendor-Id: com.sun 
Implementation-Vendor: Sun Microsystems, Inc 
Implementation-Version: 1.4.0-beta2
Main-Class: com.sun.javahelp.installer
```
In this case, because Main-Class is present in the MANIFEST, it will be treated as Java Installer, and Main-class will be invoked. It is the job of the Java Installer to copy the Java Extensions into the proper lib/ext directory. However, each Java Extension being copied into the lib/ext directory must contain proper versioning information as well. For example,
```
Extension-Name: javax.help 
Specification-Vendor: Sun Microsystems, Inc 
Specification-Version: 1.4 
Implementation-Vendor-Id: com.sun 
Implementation-Vendor: Sun Microsystems, Inc 
Implementation-Version: 1.4.0-beta2
```
This ensures the versioning information of the extensions can be determined by looking in the MANIFEST file of all the JAR files in the lib/ext directory.
Native Installer:
```
Extension-Name: javax.help 
Specification-Vendor: Sun Microsystems, Inc 
Specification-Version: 1.4 
Implementation-Vendor-Id: com.sun 
Implementation-Vendor: Sun Microsystems, Inc 
Implementation-Version: 1.4.0-rc1
Extension-Installation: installer.exe
```
In this case, because Extension-Installation is present in the MANIFEST, it 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 proper lib/ext directory. However, similar to the Java installer case, each Java Extension being copied into the lib/ext directory must contain proper versioning information as well. For example,
```
Extension-Name: javax.help 
Specification-Vendor: Sun Microsystems, Inc 
Specification-Version: 1.4 
Implementation-Vendor-Id: com.sun 
Implementation-Vendor: Sun Microsystems, Inc 
Implementation-Version: 1.4.0-rc1
```
This ensures the versioning information of the extensions can be determined by looking in the MANIFEST file of all the JAR files in the lib/ext directory.

Detailed Instructions

To deploy optional packages with Java applets using the Java Plug-in, follow these steps:

I. Make the optional package installer JAR file.

A. Obtain the optional package installer.The Java Plug-in supports three types of installers—Java, Native, and Raw. Be sure to use the correct manifest attribute for the install type

Java: Main-Class
Native: Extension-Installation
Raw: No manifest attribute

B. Make the manifest file for the optional package. Here is an example of the optional package Java Advanced Imaging API (jai_win.jar) manifest which uses a native installer (jai-1_1_1-lib-win-jre.exe). The reason it is recognized as a native installer is because the manifest attribute Extension-Installation is used.

Manifest-Version: 1.0 Extension-Name: javax.media.jai Extension-Installation: jai-1_1_1-lib-win-jre.exe Specification-Version: 1.1 Specification-Vendor: Sun Microsystems. Inc Implementation-Version: 1.1.1 Implementation-Vendor: Sun Microsystems, Inc Implementation-Vendor-Id: com.sun

C. JAR up the the installer, together with the optional package manifest file, to make the optional package installation JAR file. Be sure to include the .jar extension in the jar file name. Also, depending on the optional package and the type of installation, you may have to include the optional package JAR file(s) in the optional package installation JAR file or stage the optional package JAR file(s) on your web server. Both the optional package installation and the optional package themselves must be bundled as JAR files and contain proper versioning information.

jar cmfv manifest-addition jar-file.jar input-file(s)

D. Sign the JAR file.

You have to obtain an RSA certificate from a certificate authority (Thawte, VeriSign) to be able to sign your JAR file. Below are some tools and commands to used to sign a JAR file. They are not inclusive.

See How to Sign Applets Using RSA Certificates in the Plug-in document and other related documents for more information on this topic.

Use keytool to generate an RSA keypair and your keystore:

keytool -genkey -keyalg rsa -alias MyCert -validity 360

Use keytool to import the certificate into your keystore:

keytool -import -file <path>/mycerts/my_veri.p12

Use jarsigner to sign your JAR file:

jarsigner InstallMyOptPkg.jar MyCert

Use jarsigner to verify that the JAR file was signed properly:

jarsigner -verify -verbose -certs InstallMyOptPkg.jar

E. Put the resulting JAR file (and any other needed JAR files) on your web server so it can be downloaded by users. The URL is specified in the manifest attribute <extension>-Implementation-URL in the test applet's manifest file.

II. Make the applet JAR file and HTML file.

A. Create the applet that uses the features of the optional package.

B. Create a manifest file for the applet. Below is an example of a manifest file of an applet declaring its dependency on the optional package Java Advanced Imaging API.

Extension-List: jai jai-Extension-Name: javax.media.jai jai-Specification-Version: 1.1 jai-Implementation-Version: 1.1.1 jai-Implementation-Vendor-Id: com.sun jai-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 the different OS's you can use the $(os-name)$ construction in the Implementation-URL manifest attribute. The $(os-name)$ will translate to the target OS (i.e. SunOS, Windows-NT) that the applet is being run on.

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

C. JAR up the *.class files (and any other supporting files) that the applet uses together with the applet's manifest file. Be sure to include the .jar extension in the jar file name.

jar cmfv manifest-addition jar-file.jar input-file(s)

D. Create the HTML page for the applet. Put the name of the above JAR file in the ARCHIVE parameter. See Using OBJECT, EMBED and APPLET Tags in Java Plug-in for more information about the required format.

OBJECT classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93" width="200" height="200" align="baseline" codebase="http://java.sun.com/products/plugin/1.4/jinstall-14-win32.cab#Version=1,4,0,0"> <PARAM NAME="code" VALUE="myapplet.class"> <PARAM NAME ="archive" VALUE = "myapplet.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" width="200" height="200" align="baseline" code="myapplet.class" archive="myapplet.jar" pluginspage="http://java.sun.com/products/plugin/1.4/plugin-install.html"> <NOEMBED> </COMMENT> Optional Package Deployment Using Java Plug-in </NOEMBED></EMBED> </OBJECT>

E. Use the resulting HTML page to load your applet.

When you run the applet the Java Plug-in will display a Java Security Warning (if the optional package is not already installed) informing you that the applet requires the installation of optional package name from http://someserver.com/some.jar. If you grant the installation of the optional package the installer will install the JAR files in the <jre>\lib\ext directory. Once the installation is complete your applet will run.

How It Works

When the applet is deployed with Java Extensions, the Java Extensions information stored in the applet's MANIFEST file will be examined. The extension update algorithm is based on the one described in Optional Package Versioning. If an update is required, the Java Extensions Installation will be downloaded and verified to ensure that the extension is correctly signed. If it is valid, the Plug-in will pop-up a security dialog that provides three options:

Grant always: If selected, the extensions installation JAR will be granted "AllPermission". Any signed applet or signed extension that was signed using 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 extensions installation will be granted "AllPermission". Any signed applet or signed extension that was signed using the same certificate will be trusted automatically within the same browser session.
Deny: If selected, the extensions 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.

Security

Because Java Extensions are downloaded and installed into the Java 2 Runtime lib/ext directory, each Java Extensions Installation must be signed. Once the Java Extensions are installed, it will have the proper permissions that are granted to Java Extensions through the policy file.

Known Limitations

If the Java Extensions Installation is not signed properly, Java Plug-in will fail silently.
For Java Extensions Installation, please ensure newer versions of the Java Extensions contains at least the same set of the JAR file names as the older versions. Otherwise, installing newer Java Extensions may not overwrite all the older Java Extensions, and there will be a mix of different versions of Java Extensions in the same Java Runtime. The results will be unpredictable.
If the applet consists of several JAR files, only one of them is required to have the extensions versioning information if Java Extensions installation is used. We recommend putting the versioning information in the first JAR specified in the archive/cache_archive attribute to speed up the extensions download.
If the Java Extensions consists of several JAR files and is installed through Java/native installer, only one of the JAR files is required to have the extensions versioning information. However, for raw extensions installation, each JAR files must contain the proper extensions versioning information.
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.