Optional Package Versioning

Note: Optional packages is the new term for what used to be known as standard extensions or just extensions.

This section includes the following topics:

Overview

Version 1.3 of the Java^TM 2 Platform introduced support for an expanded set of Jar-file manifest attributes that enable applets to specify version and vendor information for the optional packages that they require. The manifests of Jar-packaged applets can specify a URL at which the latest version of the optional package the Java Plug-in can download if

the needed optional package is not already installed in the Java runtime environment, or
the optional package is installed but has an out-of-date version number, or
the optional package is installed but is not from a specified vendor.

The manifest attributes that can be used to specify version and vendor information are described below.

Manifest Attributes for Use by Installed Optional Packages

The following portion of a sample manifest file illustrates the attributes that are available for use by optional packages.

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

The attributes in this example are:

Extension-Name: This attribute specifies a name for the optional package contained in the Jar file. The name should be a unique identifier such as the name of the main package comprising the optional package.
Specification-Vendor: This attribute identifies the company that originated the specification to which the optional package conforms.
Specification-Version: This attribute specifies the version number of the specification to which the implementation conforms.
Implementation-Vendor-Id: This attribute's value is a unique identifier for the company that produced the optional package implementation contained in the Jar file.
Implementation-Vendor: This attribute's value is the name of the company that produced the implementation of the optional package. This attribute should be used only for such purposes such as user feedback, and the Java Plug-in software does not use it to identify the optional package vendor. Rather, the Java Plug-in relies on the Implementation-Vendor-Id attribute to provide unique vendor identification.
Implementation-Version: This attribute indicates the vendor's version number for the implementation of the optional package.

Each optional package installed in the Java runtime environment can use these manifest attributes to identify itself. When the Java Plug-in is running an applet that requires an optional package, the plug-in can access these attributes to determine if the installed optional packages match the vendor and version criteria specified by the applet. The applet specifies such information by using the manifest attributes described in the following section. Note that all of the above manifest attributes should be included in an optional package's manifest. If the plug-in looks for but doesn't find one of these attributes in an optional package's manifest, it will assume that the optional package is not suitable for the applet.

Manifest Attributes for Use by Applet Jar Files

The following sample manifest file illustrates the attributes that are available for use by Jar-packaged applets. (This sample is for illustrative purposes only. No actual optional packages are available at the URLs mentioned in this example.)

Extension-List: javahelp java3d 
javahelp-Extension-Name: javax.help 
javahelp-Specification-Version: 1.0 
javahelp-Implementation-Version: 1.0.3 
javahelp-Implementation-Vendor-Id: com.sun 
javahelp-Implementation-URL: http://java.sun.com/products/stdext/javahelp.jar 
java3d-Extension-Name: javax.3d 
java3d-Specification-Version: 1.0 
java3d-Implementation-Version: 1.2.1 
java3d-Implementation-Vendor-Id: com.sun 
java3d-Implementation-URL: http://java.sun.com/products/stdext/java3d.jar

The attributes used in this example are:

Extension-List: This attribute indicates the optional packages that are needed by the applet. Each optional package listed in this attribute will have a set of additional attributes that the applet uses to specify which version and vendor of the optional package it requires.
<extension>-Extension-Name: This attribute is the unique name of the optional package. The Java Plug-in will compare the value of this attribute with the Extension-Name attribute in the manifests of installed optional packages to determine if the optional package is installed.
<extension>-Specification-Version (Optional): This attribute specifies the minimum optional package specification version that is required by the applet. The Java Plug-in will compare the value of this attribute with the Specification-Version attribute of the installed optional package to determine if the optional package is up to date.
<extension>-Implementation-Version (Optional): This attritute specifies the miminum optional package implementation version number that is required by the applet. The Java Plug-in will compare the value of this attribute with the Implementation-Version attribute of the installed optional package to see if a more recent implementation needs to be downloaded.
<extension>-Implementation-Vendor-Id (Optional): This attribute can be used to identify the vendor of an optional package implementation if the applet requires an implementation from a specific vendor. The Java Plug-in will compare the value of this attribute with the Implementation-Vendor-Id attribute of the installed optional package.
<extension>-Implementation-URL: This attritute specifies a URL that can be used to obtain the most recent version of the optional package if the required version is not already installed.

Java Plug-in Update Rules

The Java Plug-in performs the following determinations when loading an applet whose manifest indicates that it needs one or more optional packages:

If an optional package with the correct value of the Extension-Name attribute is not installed, the Java Plug-in will prompt the user to let it download the optional package.
If an optional package with the correct value of the Extension-Name attribute is already installed, the Java Plug-in makes the following comparisons:
- If the optional package's Specification-Version value is greater or equal to that required by the applet:
  - If the Implementation-Vendor-Id attributes match:
    - If the optional package's Implementation-Version is greater than or equal to that specified in the applet's manifest, do nothing - an up-to-date version of the optional package is already installed.
    - If the optional package's Implementation-Version is less than that specified in applet's manifest, the plug-in will prompt the user to download an upgrade from the same vendor.
  - If the Implementation-Vendor-Id attributes do not match, the Java Plug-in will prompt the user to download the optional package from the vendor specified in the applet's manifest.
- If the optional package's Specification-Version value is less than that required by the applet:
  - If the optional package's Implementation-Vendor-Id matches that indicated in the applet's manifest, the Java Plug-in will prompt the user to download an updated optional package from the same vendor.
  - If the optional package's Implementation-Vendor-Id does not match that specified by the applet's manifest, the Java Plug-in will prompt the user to download the optional package from the vendor specified in the applet's manifest.

If the applet's manifest doesn't contain one or more of the optional attributes, the plug-in will accept any value of the corresponding attribute in the optional package's manifest.

Download and Installation of Optional Packages

The following considerations pertain to optional packages that are downloaded by the Java Plug-in.

The optional package download URL as indicated in the applet manifest's <extension>-Implementation-URL attribute need not be limited to the Applet codebase.

All downloadable files should be signed using a DSA or RSA certificate. Any optional packages not so signed will not be installed but instead will be treated as a bundled optional package and loaded through the applet class loader, sharing the applet security attributes.

When the Java Plug-in retrieves an optional package from the URL indicated in the applet's manifest, it will check the optional package's manifest for a Main-Class attribute after verifying the optional package's signature. If the optional package's manifest file does not contain a Main-Class attribute, the Java Plug-in will simply drop the Jar file into the optional packages directory of the runtime environment (jre/lib/ext in the JDK and lib/ext in the JRE).

Some optional package Jar files may contain their own installer programs in either native code or as applications written in the Java programming language. Such an installer program may be necessary for purposes such as installing native libraries or accessing the Microsoft Windows registry, for example. If the Java Plug-in finds a Main-Class attribute in the optional package's manifest, it will assume that it indicates a class that serves as a Java-language installer and will invoke the main() method of that class.

An optional package's manifest may alternatively contain a Extension-Installation attribute. The value of this field will point to a native installation application that is to be used by the Java Plug-in to install the optional package.

The URL of an optional package as specified by the <extension>-Implementation-URL must point to a JAR-file. The plug-in will not download and install optional packages packaged as .exe or .bin files.

Some optional packages come packaged in different Jar files for different operating systems. Such cases can be accomodated by the <extension>-Implementation-URL attribute by using the $(os-name)$ construction in the attribute's value. Here is an example.

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

Here, $(os-name)$ is the name of target operating system as defined by the os.name system property.