| Documentation Contents

# Applet Deployment

Rich Internet Applications Deployment Advice > Applet Deployment

Contents

- Introduction
- Reference: New Parameters to APPLET, OBJECT, EMBED elements
  - Deployment using JNLP
    - jnlp_href
  - Loading Screen
    - boxborder
    - centerimage
  - Command-line Arguments
    - java_arguments
    - separate_jvm
  - JRE Version Selection
    - java_version
    - class-id attribute in Internet Explorer
    - version and jpi-version attributes in the Mozilla Browser family
  - Class Loader Caching
    - classloader_cache

## Introduction

Applets may be deployed by hand coding the applet, object or embed tags with the required parameters. However, to assure cross browser compatibility, it is recommended that the Deployment Toolkit be used to deploy applets. Applets may be deployed and launched via:

- Applet, object or embed tags, or,
- JNLP

Please refer to the Deployment Advice document for information on using the Deployment Toolkit and deploying applets using JNLP.

## Reference: New Parameters to APPLET, OBJECT, EMBED elements

### Deployment using JNLP

#### jnlp_href

The file containing information that the plug-in should use to launch the applet.

### Loading Screen

The new plug-in offers better customization of the image which is displayed before the applet is loaded. Animated GIFs are now supported as the target of the `image` parameter, as described in the Special Attributes section of the old Java Plug-In Guide. Additionally, the following new parameters are now supported:

#### `boxborder`

A boolean parameter indicating whether a one-pixel border should be drawn around the edge of the applet's area while displaying the image shown before the applet is loaded. Defaults to `true`. We recommend setting this value to `false`, in particular when using an animated GIF as the loading image, to avoid the possibility of flicker.

#### `centerimage`

A boolean parameter indicating whether the loading image should be centered within the area of the applet instead of originating at the upper left corner. Defaults to `false`.

Example using the `boxborder` and `centerimage` parameters:

       <APPLET archive="large_archive.jar"
    		   code="MyApplet"
    		   width="300" height="300">
    	  <!-- Use an animated GIF as an indeterminate progress bar
    		   while the applet is loading -->
    	  <PARAM NAME="image" VALUE="animated_gif.gif">
    	  <!-- Turn off the box border for better blending with the
    		   surrounding web page -->
    	  <PARAM NAME="boxborder" VALUE="false">
    	  <!-- Center the image in the applet's area -->
    	  <PARAM NAME="centerimage" VALUE="true">
    	</APPLET>

### Command-line Arguments

#### `java_arguments`

Specifies JVM command-line arguments to be used when executing this applet instance. Nearly all JVM command-line arguments are supported, though there are certain rules and restrictions.

Examples

1. Specifying a larger-than-default maximum heap size:

       <APPLET archive="my_applet.jar" code="MyApplet" width="300" height="300">
           <PARAM name="java_arguments" value="-Xmx128m">
       </APPLET>

2. Specifying a non-default heap size and a Java 2D hardware acceleration option typically used for applets using OpenGL via JOGL:

       <APPLET archive="my_applet.jar" code="MyApplet" width="300" height="300">
           <PARAM name="java_arguments" value="-Xmx256m -Dsun.java2d.noddraw=true">
       </APPLET>

3. Enabling verbose output of the garbage collector, and the assertion facility in the Java programming language:

       <APPLET archive="my_applet.jar" code="MyApplet" width="300" height="300">
           <PARAM name="java_arguments" value="-verbose:gc -ea:MyApplet">
       </APPLET>

A set of "secure" JVM command-line arguments and system properties is defined in the JNLP File Syntax section of the Java Web Start Developers' Guide. In the new plug-in, as long as all of the JVM command-line arguments specified via the `java_arguments` parameter are secure, then the applet, or any classes it loads, may be unsigned.

Insecure JVM command-line arguments (in other words, those not on the secure list) may also be specified via the `java_arguments` parameter. In this case, there is the potential for a security risk, so the Java Plug-In enforces the rule that no unsigned classes may be loaded. In other words, only trusted code, for which the user has accepted the security dialog, may be loaded by such a JVM instance. If an attempt is made to load an unsigned or untrusted class in a JVM instance for which insecure system properties have been specified, a `ClassNotFoundException` will be thrown indicating that the given class could not be loaded because it was not signed.

There are relatively few restrictions on what command-line arguments may be passed via the `java_arguments` parameter. In general, the `-Xbootclasspath` argument is forbidden, as well as any command-line argument used to specify a path, such as `-classpath` or `-jar`. All other command-line arguments, present and future, should be supported, with the caveat about secure and insecure command-line arguments described above.

The command-line arguments passed via the `java_arguments` parameter are added to any specified via the Java Applet Runtime Settings dialog in the Java Control Panel. The command-line arguments from the control panel are used for all JVM instances of the version for which they are specified; the `java_arguments` parameters do not completely replace them. (The Java Applet Runtime Settings dialog has also been enhanced in 6u10 to better manage multiple JRE versions, and now has the same capabilities as the Java Applet Runtime Settings dialog used for Java Web Start.)

When JVM command-line arguments are specified, it is likely that the new plug-in will need to launch another JVM instance in order to satisfy them. In other words, it is unlikely that a preexisting JVM instance will have been started with the correct set of command-line arguments to satisfy the request. The rules for exactly when a new JVM instance is launched to start a given applet are deliberately left unspecified, as this functionality is brand new in the 6u10 release and may need to change in subsequent releases. Here is a rough set of guidelines for the sharing and creation of new JVM instances:

- If the command-line arguments used to start a preexisting JVM instance are a superset of the requested arguments, the preexisting JVM instance will be used.
- If a JVM instance is launched for the "default" set of command-line arguments (i.e., those specified in the Java Control Panel, with no `java_arguments` specified), then this JVM instance will never be used to launch any applet that has even one command-line argument specified via `java_arguments`.
- `-Xmx` is handled specially: if a preexisting JVM instance was started with for example `-Xmx256m` via `java_arguments`, and a new applet requests `-Xmx128m`, then new applet will very likely be run in the preexisting JVM instance. In other words, `-Xmx` specifications are matched with a greater-than-or-equal test.

There is no way to "name" a JVM instance used to launch a particular applet and "force" subsequent applets into that JVM instance.

See the section on the `separate_jvm` parameter to isolate a particular applet in its own JVM instance, separate from all other applets.

#### `separate_jvm`

A boolean parameter specifying that a particular applet should run in its own JVM instance. This supports certain powerful desktop applets which can not tolerate any interference from other applets running in the same JVM and potentially consuming heap space or other resources.

    <APPLET archive="my_applet.jar" code="MyApplet" width="300" height="300">
        <PARAM name="java_arguments" value="...">
        <PARAM name="separate_jvm" value="true">
    </APPLET>

###

### JRE Version Selection

#### `java_version`

Specifies a JRE version upon which to launch a particular applet.

Examples

1. Specifying a particular JRE version for a particular applet:

       <APPLET archive="my_applet.jar" code="MyApplet" width="300" height="300">
           <PARAM name="java_version" value="1.5.0_09">
       </APPLET>

2. Requesting any JRE in a particular family for a particular applet:

       <APPLET archive="my_applet.jar" code="MyApplet" width="300" height="300">
           <PARAM name="java_version" value="1.5*">
       </APPLET>

3. Specifying a JRE from a particular family or any later family:

       <APPLET archive="my_applet.jar" code="MyApplet" width="300" height="300">
           <PARAM name="java_version" value="1.5+">
       </APPLET>

#### classid Attribute in Internet Explorer

The Internet Explorer browser uses the `classid` attribute of the `<object>` tag to indicate how the content of that tag should be displayed. The `classid` attribute can be used in conjunction with the `codebase` attribute to automatically download and install a particular JRE version if none is currently available on the system (see classid usage). The family CLSID concept was introduced more recently to provide a way to select an arbitrary JRE in a given family.

Not all of the classid options described in earlier documentation work in conjunction with the new Java Plug-In to both select, and potentially automatically download and install, a particular JRE version. This section describes what works in conjunction with the new plug-in, and what backward compatibility mechanisms are in place.

##### Recommended Usage

The recommended usage of the classid attribute is in conjunction with the `java_version` parameter described above. The dynamic classid, which always points to the latest installed JRE version, should be specified in the `<object>` tag in order to indicate that the latest version of the Java Plug-In, with multiple JRE support, should be used. The `java_version` parameter should then be used to specify the version of the JRE to use to run the applet.

Example of recommended usage:

      <object
        classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"
        codebase="http://java.sun.com/out-of-proc-plugin-url-placeholder.exe#1,6,0,10"
        width="200" height="200">
          <param name="code" value="MyApplet">
          <param name="java_version" value="1.5*">
      </object>

Note that, at the current time, Sun Microsystems, Inc. is not providing a new CLSID to describe the new Java Plug-In, but instead overloading the usage of the dynamic classid. This means that if a previous version of the JRE is already installed which does not have multiple JRE version support in the Java Plug-In, the new Java Plug-In will not be automatically downloaded and installed, since a handler for that classid is already available. The result will be that the version selection via the `java_version` parameter will be ignored. The decision to not provide a new classid may be revisited in the future. For the time being, Sun expects that sophisticated developers requiring multiple JRE version selection and automatic download of the new Java Plug-In will either document that their users must install and configure the new Java Plug-In in order to properly run their content, or will have administrative control over the client machines, as is common in many enterprises.

##### Backward Compatibility

To ease the transition for developers already using the classid attribute, two backward compatibility mechanisms have been introduced: the ability to use a classid to select either a specific JRE version, or an arbitrary JRE in a given family. In both cases, the expectation is that both the new Java Plug-In, and the target JRE version for the applet, are already installed and configured. In conjunction with these backward compatibility mechanisms, auto-downloading of any JRE, either the one supplying the new Java Plug-In or the one to be used to run the applet, is not supported.

Note that these backward compatibility mechanisms may be removed in a future release. Sun recommends transitioning existing content to the new mechanisms described above.

Selecting a particular JRE version (1.5.0_11) for an individual applet:

      <object
        classid="clsid:CAFEEFAC-0015-0000-0011-ABCDEFFEDCBA"
        width="200" height="200">
          <param name="code" value="MyApplet">
      </object>

Selecting the latest JRE from a particular family (1.5) using the family CLSID:

      <object
        classid="clsid:CAFEEFAC-0015-0000-FFFF-ABCDEFFEDCBA"
        width="200" height="200">
          <param name="code" value="MyApplet">
      </object>

Note that attempts to download older versions of the JRE using the `codebase` parameter will be ignored, because these classids are registered on the system to point to more recent versions of the DLLs during the installation process of the new Java Plug-In. Note also that the use of the `java_version` parameter in conjunction with these classids is not supported. Specifying both the `java_version` parameter as well as either a static or family classid will result in undefined behavior.

#### `version` and `jpi-version` attributes in the Mozilla Browser Family

The Mozilla browser family uses the MIME type in the `<embed>` tag to indicate how the content of that tag should be displayed. The `<embed>` tag also supports automatic downloading of a particular version of the JRE.

Previous versions of the Java Plug-In used the `version` and `jpi-version` portions of the `application/x-java-applet` MIME type to perform JRE version selection. Not all of these mechanisms described in earlier documentation work in conjunction with the new Java Plug-In to both select, and potentially automatically download and install, a particular JRE version. This section describes what works in conjunction with the new plug-in, and what backward compatibility mechanisms are in place.

##### Recommended Usage

The recommended usage of the `<embed>` tag is to not specify any `version` or `jpi-version` in the MIME type of the applet. Instead, use the `java_version` parameter to choose a particular JRE version upon which to run the applet. If no previous Java version is installed, auto-download of the new Java Plug-In can be enabled using the `pluginspage` parameter:

      <embed code="MyApplet"
        type="application/x-java-applet"
        pluginspage="http://java.sun.com/out-of-proc-plugin-url-placeholder.xpi"
        width="200" height="200">
        java_version="1.5*"
      </embed>

Note that, at the current time, Sun Microsystems, Inc. is not providing a new MIME type to describe the new Java Plug-In, but instead overloading the usage of the `application/x-java-applet` MIME type. This means that if a previous version of the JRE is already installed which does not have multiple JRE version support in the Java Plug-In, the new Java Plug-In will not be automatically downloaded and installed, since a plugin supporting that MIME type is already available. The result will be that the version selection via the `java_version` parameter will be ignored. The decision to not provide a new MIME type may be revisited in the future. For the time being, Sun expects that sophisticated developers requiring multiple JRE version selection and automatic download of the new Java Plug-In will either document that their users must install and configure the new Java Plug-In in order to properly run their content, or will have administrative control over the client machines, as is common in many enterprises.

##### Backward Compatibility

To ease the transition for developers already using the `version` and `jpi-version` portions of the MIME type, a limited degree of backward compatibility is supported in the new Java Plug-In. Specifically, the `version` attribute is supported to request an arbitrary JRE in a given family or any later family. Using the `jpi-version` attribute to select a particular JRE version is no longer supported. Its use is strongly discouraged since it may disrupt correct operation of the new Java Plug-In.

Note that this backward compatibility mechanism may be removed in a future release. Sun recommends transitioning existing content to the new mechanisms described above.

To use the `version` attribute to require the 1.5 JRE or a later one:

      <embed code="MyApplet"
        type="application/x-java-applet;version=1.5"
        width="200" height="200">
      </embed>

Note that the semantics of the `version` attribute imply that the above tag is equivalent to using the `java_version` parameter with a value of `1.5+`. Since the new Java Plug-In is delivered with Java SE 6 update 10, which is a later version than 5.0, this version request essentially has no effect.

Note also that combining the `version` attribute with the `java_version` parameter is not supported. Specifying both the `java_version` parameter as well as a `version` attribute will result in undefined behavior.

### Class Loader Caching

### `classloader_cache`

  The new plug-in provides a way to opt out of the use of the class loader cache on an applet by applet basis.

      <APPLET archive="my_applet.jar" code="MyApplet" width="300" height="300">
          <PARAM name="classloader_cache" value="false">
      </APPLET>

  The default value of the `classloader_cache` parameter is `true`; class loader caching is enabled by default.

##

Copyright © 1995-2010 Sun Microsystems, Inc. All Rights Reserved. Please send comments using this Feedback page. | Java Technology