Applet Deployment Parameters

Java Rich Internet Applications Guide > Applet Developer's Guide > Applet Deployment Parameters

Applets may be deployed by hand-coding the applet, object or embed tags with the required parameters. This section describes these parameters. However, to assure cross browser compatibility, it is recommended that the Deployment Toolkit be used to deploy applets. Refer to Java Rich Internet Applications Deployment Advice for information on using the Deployment Toolkit and deploying applets using JNLP.

The following topics are covered:

Deployment using JNLP
- jnlp_href
Loading Screen
- boxborder
- centerimage
Command-line Arguments
JRE Version Selection
Class Loader Caching
- classloader_cache
Security
- permissions
Java Cache
- cache_archive

Deployment using JNLP

`jnlp_href`

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

Loading Screen

The Java Plug-in offers better customization of the image that is displayed before the applet is loaded. Animated GIFs are now supported as the target of the image parameter, as described in Special Attributes. Additionally, the following parameters are 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-vm-args`

Specifies an additional set of standard and non-standard virtual machine arguments that the application prefers the JNLP client to use when launching Java. When both java_arguments and java-vm-args are present, the java-vm-args arguments take precedence.

`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. When both java_arguments and java-vm-args are present, the java-vm-args arguments take precedence.

The java_arguments option is primarily for the purpose of avoiding a client Java VM relaunch during applet startup. As a good practice, if both java_arguments and java-vm-args are specified, they should contain the same values.

Examples Illustrating the Relationship Between java_arguments and java-vm-args

Scenario 1:: Both parameters are defined and their values are different.

java_arguments = -Xmx256m
java-vm-args = -verbose

Expected behavior on all platforms: -verbose
The JVM first launches using the value specified by the java_arguments tag. The client JVM detects the mismatch and relaunches with -verbose only. A warning is printed to the Java console.

Scenario 2: Both parameters are defined, and the values specified in java-vm-args are a subset of those specified in java_arguments.

java_argument = -Xmx256m -verbose
java-vm-args = -verbose

Expected behavior on all platforms: -verbose
The JVM first launches with the full set of arguments as specified by java_arguments. The client JVM detects the mismatch, and relaunches the smaller set of argument as specified by java-vm-args only. A warning about the parameter mismatch is printed in the Java console.

Scenario 3: The java_arguments tag is defined in the HTML file, but the java-vm-args tag is not defined in the JNLP file.

java_arguments = -Xmx256m
java-vm-args = [not defined]

Expected behavior on all platforms: [no jvm params]
The JVM first launches with the values specified in java_arguments. The client JVM detects the mismatch and relaunches the JVM with no params. A warning about the parameter mismatch is printed in the Java console.

Scenario 4: The java_arguments tag is not defined in the HTML file, but the java-vm-args tag is defined in the JNLP file.

java_arguments = [not defined]
java-vm-args = -Xmx256m

Expected behavior on all platforms: -Xmx256m
The JVM first launches with no JVM arguments, as there are none specified in the java_arguments tag. The client JVM detects the mismatch and relaunches the JVM using the values specified in java-vm-args.

Other Examples

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>

Specifying a non-default heap size and a Java 2D hardware acceleration option typically used for applets using OpenGL via Java Binding for the OpenGL API (JOGL):

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

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 Java 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 run without permissions.

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 Runtime Environment 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.

When JVM command-line arguments are specified, it is likely that the Java 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 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

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>

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>

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. (See Deploying Java Applets With Family JRE Versions in Java Plug-in for Internet Explorer for more information.)

Not all of the classid options described in earlier documentation work in conjunction with the 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 Java 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://www.example.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, Oracle is not providing a new CLSID to describe the 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 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, Oracle expects that sophisticated developers requiring multiple JRE version selection and automatic download of the Java Plug-In will either document that their users must install and configure the Java Plug-In in order to properly run their content, or will have administrative control over the client computers, 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 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 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. Oracle recommends transitioning existing content to the new mechanisms described previously.

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 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 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 Java 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 Java Plug-In can be enabled using the pluginspage parameter:

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

Note that, at the current time, Oracle is not providing a new MIME type to describe the 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 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, Oracle expects that sophisticated developers requiring multiple JRE version selection and automatic download of the Java Plug-In will either document that their users must install and configure the Java Plug-In in order to properly run their content, or will have administrative control over the client s, 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 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 Java Plug-In.

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

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 this 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 Java 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.

Security

`permissions`

Specifies the level of permissions that the applet needs to run. The following values are valid:

sandbox - The applet runs in the security sandbox.
all-permissions - The applet requires access to resources on the user's system.
default - The level of permissions is determined by the Permissions attribute in the manifest for the main JAR file.

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

If this parameter is omitted, default is assumed. If the parameter is present and not set to default, the value must match the value of the Permissions attribute in the manifest for any JAR file that has the Permissions attribute, otherwise the applet is blocked.

Java Cache

Files you use in Java applications are stored in a special folder for quick execution later; this folder is also called the Java cache. The subpanel Temporary Internet Files in the General panel in the Java Control Panel enables you to view which files are stored in the Java cache and control how much disk space it can take up in your computer.

`cache_archive`

The cache_archive attribute contains a list of the files to be cached:

<param name="cache_archive" VALUE="a.jar,b.jar,c.jar">

Like the archive attribute in the applet tag, the list of jar files in the cache_archive attribute do not contain the full URL, but are always downloaded from the codebase specified in the embed/object tag.