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

1. MANIFEST of the applet's JAR files.
   If the applet requires Java Extensions Installation, the applet MUST define the list of Java Extension Installation it requires in the MANIFEST, and specifies the URLs to download the extensions.

2. MANIFEST of the Java Extension Jar files to be installed (e.g. JAR files that will be downloaded to the \lib\ext directory).
   The purpose is to denote the extension name, version and vendor info within the extension JAR file itself. Therefore, Java Plug-in will be able to compare the vendor, extension-name and vendor info of all the installed extensions (e.g. inside lib/ext) against the extension the applet requests to determine if the extensions need to be installed/upgraded.

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

Note: For an explanation of version numbers, see the note in the section called "Using OBJECT, EMBED and APPLET Tags in Java Plug-in."

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 Extension Versioning Specification. 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

Java Extensions Installation

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

1. 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.
2. 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).
3. 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 Extensions itself must be bundled as JAR files and contain proper versioning information in its own MANIFEST file according to the Extension Versioning Specification. For example,

1. Raw Java Extensions:

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

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

   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.0
   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 the 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.0 
   Implementation-Vendor-Id: com.sun 
   Implementation-Vendor: Sun Microsystems, Inc 
   Implementation-Version: 1.0

   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.

3. Native Installer:

   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.0
   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.0 
   Implementation-Vendor-Id: com.sun 
   Implementation-Vendor: Sun Microsystems, Inc 
   Implementation-Version: 1.0

   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.

How it works

To deploy Java Extensions with Java applets, these steps must be followed:

1. Obtain the Java Extensions Installation through a third-party vendor. As described above, both Java Extensions Installation and the Java Extensions themselves must contain proper versioning information, according to the Extension Versioning Specification. Both the Java Extensions Installation and Java Extensions themselves must be bundled as JAR files.
2. Sign each Java Extensions Installation JAR file using DSA/RSA certificates. Notice that the Java Extensions itself is not required to be signed, unless it is a raw extension.
3. Specify the Java Extensions Installation in the applet's MANIFEST file, according to the Extension Versioning Specification.
4. Bundle the applet itself as JAR file.

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 the Extension Versioning Specification. 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:

1. 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 again 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 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.
   
3. 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 to ensure that the extensions installation is as seamless as possible.

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 result is un-deterministic. 
• 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 a AWT window and switch control to a different thread and return immediately from 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.