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 and Other Notes

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, the MANIFEST of the applet's JAR MUST define the list of Java Extensions it requires and specify the URLs from which to download the extensions, along with other information about the Java 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 that the extension name in the Extension-List and the prefix of the other manifest attributes must be the name of an extension JAR file that is installed in the extension directory (<jre_location>/lib/ext). Some Java Extensions consist of several JAR files. For example, optional package Java3D installs the following JAR files in the extension directory: j3daudio.jar, j3dcore.jar, j3dutils.jar, and vecmath.jar. For these Java Extensions only one of the Java Extensions JAR file names must be used in the Extension-List and the prefix of the other manifest attributes. Usually the optional package has a main JAR file; if so, that is the one you should use in the Extension-List and the prefix of the other manifest attributes.

Here is an example of the applet's manifest using optional package Java 3D.

Extension-List: j3dcore j3dcore-Extension-Name: javax.media.j3d j3dcore-Implementation-Vendor-Id: com.sun j3dcore-Implementation-Version: 1.2.1_03 j3dcore-Implementation-Title: Java 3D Core Runtime Environment j3dcore-Specification-Title: Java 3D API Specification j3dcore-Specification-Version: 1.2 j3dcore-Specification-Vendor: Sun Microsystems, Inc j3dcore-Implementation-URL: http://<some server>/native/java3d-$(os.name)$.jar

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 use 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_core jai_core-Extension-Name: javax.media.jai jai_core-Specification-Version: 1.1 jai_core-Implementation-Version: 1.1.1 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 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 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

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.

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.

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 and Other Notes

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 Java Extension consists of several JAR files and is installed through a Java or native installer, only one of the JAR files is required to have the extensions information (i.e., Extension-Name, Specification-Version, etc.). But if you only specify extensions information in one, make sure that one is the one used in the Extension-List of the applet JAR manifest for the Java Extension. For raw extensions installation, each JAR files must contain the proper extension 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.