Documentation Contents
Java Platform, Standard Edition Deployment Guide
Contents    Previous    Next

11 Applet Development Guide

This topic provides information about developing and deploying Java applets. Java applets use Java Plug-in technology to run in a browser.

This topic contains the following sections:

11.1 Overview

Java Plug-in technology (hereafter the "Java Plug-in"), which is included in the Java Runtime Environment (JRE), enables Java applets to run in web browsers on the desktop. The Java Plug-in provides powerful capabilities to applets in the web browser, while improving the overall reliability and functionality of applets in a backward-compatible manner.

The Java Plug-in runs one or more Java virtual machine instances (JVMs) that connect back to the browser for full interoperability with the surrounding web page. This architectural change offers many advantages and features:

See the Applet Development Tutorial, a comprehensive Java Tutorial that explains various aspects of applet development and deployment.

11.2 Java Plug-In and Applet Architecture

This section describes how the Java Plug-in controls the execution of applets and interactions between applets and the browser.

11.2.1 Java Runtime Environment

With the Java Plug-in, applets are not run in the JVM inside the browser. Instead, they are executed in a separate process. The same JVM process can be shared between multiple applets, or applets can be placed into different processes depending on whether the existing JVMs match the applet requirements and have enough resources to execute the applet. An applet can request a specific version of the JRE to be used and can specify what options to pass to the JVM. An applet can also request to be executed in the separate JVM.

The browser and the applet can still communicate with one another, however. Existing APIs have been re-engineered to use process sockets, so everything continues to work as it did before, only better. This architecture provides a number of benefits:

  • Applets that require different versions of the JRE can run simultaneously.

  • Applets can specify JRE start-up parameters such as heap size. (A new applet uses an existing JRE if it's requirements are a subset of an existing JRE, otherwise, a new JRE instance is launched.);

  • The message-passing interfaces are written in Java, so they run on all supported platforms, in the same way, so cross-browser compatibility is enhanced.

With that architecture, a new JRE can be launched whenever it is needed. However, an applet runs in an existing JRE when the following conditions are met:

  1. The JRE version required by the applet matches an existing JRE.

  2. The launch parameters for the JRE satisfy the applet's requirements.


  • If two applets each require a large amount of memory, they might both run in the same JRE, causing one of them to run out of memory. But that's only a concern when you have multiple applets running simultaneously.

  • Particular versions of JRE can be marked as unavailable to the plugin by disabling them in the Java Control Panel.

11.2.2 Java Runtime Environment Version Selection

On all platforms, the Java Plug-in locates JREs to use from the entries listed in the Java Control Panel ("Java" tab, "View" button). The available JREs in this list are encoded in the file whose location is platform-dependent. On the Windows platform, it is generally located in C:\Users\[username]\AppData\LocalLow\Sun\Java\Deployment. On Solaris, Linux, and OS X platforms, it is generally located in ~/.java/deployment/

On Windows platforms, both the Java Control Panel and the Java Plug-in automatically detect the installed JREs and add them to the available set. On Solaris, Linux, and OS X platforms, auto-detection of installed JREs is not supported. The Java Runtime Environment Settings dialog, which is accessed by clicking View in the Java tab of the Java Control Panel, can be used to manually add JREs to the known list for the Java Plug-in.

By default, the Java Plug-in executes all applets in the latest JRE version named in this list. The Java Plug-in executes an applet on an earlier JRE version only if explicitly requested.

When considering a request to launch an applet on a specific JRE version (for example, a particular update release like "1.5.0_11"):

  1. The list of available JREs is consulted. If there is an exact match of the version string, that JRE version is selected. Otherwise, if there are one or more installed JREs in the same family, the latest version is selected. Otherwise, the latest available JRE on the machine is selected.

  2. The selected JRE version is compared against the security baseline for the family. (See Deploying Java Applets With Family JRE Versions in Java Plug-in for Internet Explorer for more information.) If it is equal to or more recent than that version, no further prompting is done and the applet is launched.

  3. Otherwise, the code for the applet is downloaded in a JVM instance of the selected JRE version. If the applet is signed and the user accepts the security dialog for the applet (or the code source has already been trusted), no further prompting is done and the applet is launched.

  4. Otherwise, we are dealing with an unsigned applet on an "older" JRE version. A dialog box is presented indicating that this applet is requesting to run on top of an older JRE release, and asks the user whether he or she wants to allow it to. If the user clicks "yes", the applet is launched. If the user clicks "no", the applet is re-launched on top of the latest available JRE version.

When considering a request to launch an applet on a particular family, the most recent JRE from that family will be selected and the above steps starting from (2) will be followed.

When considering a request to launch an applet on a particular family or any later family, the latest available JRE will be used to launch the applet.

11.2.3 Thread Considerations

A web browser's JavaScript interpreter engine is single thread. The Java Plug-in is capable of managing multiple threads. The Java Plug-in creates a separate worker thread for every applet. Applets themselves may be multi-threaded. Applets making JavaScript to Java calls and vice versa should be designed with the thread related issues in mind.

The following figure shows the thread interactions between the JavaScript Interpreter, Java Plug-in, and an applet.

Figure 11-1 Thread Interactions

Description of Figure 11-1 follows
Description of "Figure 11-1 Thread Interactions"

When the JavaScript interpreter is idle, the Java Plug-in executes a JavaScript to Java call on the per applet worker thread (JavaScript Interpreter Not Busy scenario).

When a Java to Javascript call is in progress and a JavaScript to Java call is made, the latter is executed on the same thread that made the Java to JavaScript call (Round Trip scenario).

When a thread is executing a Java to JavaScript call, another thread wanting to do the same will be blocked till the first thread has received its result and is done (JavaScript Interpreter Busy scenario)

In order to avoid thread related issues especially when multiple applets are running simultaneously, keep both Java to JavaScript and JavaScript to Java calls short and avoid round trips, if possible.

11.2.4 Classloader Cache and Interaction between Applets

Normally, if two applets have the same codebase and archive parameters, they will be loaded by the same class loader instance. This behavior is required for backward compatibility, and is relied on by several real-world applications. The result is that multiple applets on the same web page may access each others' static variables at the Java language level, effectively allowing the multiple applets to be written as though they comprised a single application.

While this feature enables certain kinds of applications to be conveniently written, it has certain drawbacks. It interferes with termination of applets, in particular when multiple instances of the same applet are active. It makes the programming model for applets more complex, since it is under specified exactly when the static fields of an applet will be re-initialized, and when they will be maintained from run to run of the same applet. It causes imprecise behavior of certain user interface operations within the Java Plug-in due to the inability to identify exactly which applet initiated a particular request.

For this reason, the Java Plug-in provides a way to opt out of the use of the Section 11.3.5, "Class Loader Caching" on an applet by applet basis.

11.2.5 Applet Garbage Collection

Garbage collection occurs on an applet instance immediately after the destroy method finishes. The garbage collection applies to all memory acquired by the applet, except for static variables. Statics are preserved in the classloader cache, along with the classes themselves, for as long as the class loader is present.

So when does the class loader go away? That behavior is not specified. It's up to the implementation of the Java virtual machine and its interactions with the operating system. You can expect it be retained for as long as possible, but to be discarded when the memory is needed for other purposes.

11.2.6 Applet Privileges

Sign all applets with a valid certificate from a recognized certificate authority to provide a better user experience. An applet runs in a secure sandbox that prevents it from interacting with the user's system, unless authorized. To obtain that authorization, the applet must request permissions when it is launched and the user must agree to run the applet. Permissions are needed to:

  • Print

  • Access the file system

  • Access browser cookies

  • Access other system resources

The basic applet security model is an all or nothing proposition. An applet with permissions has full access to the user's system. Without permissions, the applet has virtually no access at all.

Deployment of applets using JNLP gives the applets access to JNLP APIs similar to Java Web Start applications, which gives the applet controlled access to a user's system, under control of the user. For example, using JNLP provides the ability to save or open a file selected by the user and the ability to print.

11.2.7 Proxy Configuration

See Section 28.1, "Proxy Configuration" for details.

11.2.8 Security

See Chapter 21, "Setting the Security Level of the Java Client" for details.

11.3 Applet Deployment Parameters

Applets can 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. See Chapter 17, "Deployment in the Browser" for information on using the Deployment Toolkit.

11.3.1 Deployment using JNLP


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

11.3.2 Loading Screen

The Java Plug-in offers better customization of the image that is displayed before the applet is loaded. Animated GIFs are supported as the target of the image parameter. Additionally, the following parameters are supported:


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.


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"
 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">

11.3.3 Command-line Arguments


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.


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.


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> 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: -verboseThe 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: -verboseThe 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: -Xmx256mThe 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

  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">
  2. 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">
  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">

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.

11.3.4 JRE Version Selection


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

Use the Deployment Toolkit to specify an older version of the JRE, if needed. In an enterprise environment, the preferred method of requesting an older version of the JRE is to use the Deployment Rule Set feature.

11.3.5 Class Loader Caching


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">

For applets, the default value of the classloader_cache parameter is true; which indicates that class loader caching is enabled. For JNLP applets, class loader caching is disabled.

11.3.6 Security


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" />

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.

11.3.7 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 tab of the Java Contro Panel, which is described in Section 18.1, "General," enables you to view which files are stored in the Java cache and control how much disk space the cache can take up in your computer.


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 or object tag.

11.4 Applet Status And Event Handlers

Beginning in the Java SE 7 release, you can check the value of the status variable of an applet while it is being initialized. This check is non-blocking and immediately returns the status of the applet. You can explicitly check the status of the applet while it is loading and perform relevant actions or register event handlers that are automatically invoked during various stages of applet initialization. To use this functionality, deploy the applet with the java_status_events parameter set to true. See the Handling Initialization Status With Event Handlers lesson in the Java Tutorials for step by step instructions and an example.

11.4.1 Applet Status

Table 11-1 explains the meaning of values returned by the status method of the applet.

Table 11-1 Applet Status Values and Meaning

Applet Status Applet Status Variable Value Meaning



Applet is loading



Applet has loaded completely and is ready to receive JavaScript calls



Error while loading applet

11.4.2 Applet Event Handlers

You can register event handlers for various events. The Java Plug-in software invokes these event handlers at various stages of the applet loading process. Table 11-2 describes applet events for which event handlers can be registered.

Table 11-2 Applet Events

Applet Event When Event Occurs


Applet status is READY. Applet has finished loading and is ready to receive JavaScript calls.


Applet has stopped.


Applet status is ERROR. An error has occurred while loading the applet.

You can register or determine an event handler in the JavaScript code of a web page as shown in the following code examples:

// use an anonymous function
applet.onLoad(function() {
 //event handler for ready state

// use a regular function
function onLoadHandler() {
 // event handler for ready state

// Use method form

// Use attribute form
applet.onLoad = onLoadHandler;

// get current event handler
var handler = applet.onLoad
Contents    Previous    Next

Oracle and/or its affiliates Copyright © 1993, 2014, Oracle and/or its affiliates. All rights reserved.
Contact Us