Java Platform, Standard Edition Deployment Guide
Contents    Previous    Next

12 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:

12.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:

  • The JVM running the applet is isolated from the web browser at the operating system level. If something should go wrong while running the applet, or if an uncooperative applet refuses to shut down, the Java Plug-in detects and handles the error condition gracefully; the web browser is unaffected.

    The Java Plug-in starts applets in the background, so the web browser always remains responsive. Applets appear on the web page as they become ready to run.

  • The Java Plug-in offers the capability to launch applets directly from JNLP files, unifying deployment of Java content both in the browser and out of the browser (via Java Web Start). Developers can reuse JNLP extensions for advanced functionality. Applets can access JNLP APIs for persistent data storage, local file system access, and other useful functionality from sandboxed code.

  • The bridge between the JavaScript engine in the web browser and the Java programming language is backward-compatible and features reliability, performance, and cross-browser portability for both Java applets calling JavaScript code as well as JavaScript code calling Java applets.

  • Applets can utilize as much heap space as command-line applications.

  • JVM command-line arguments may be specified in the HTML of the web page on a per-applet basis, providing fine-grained control over options such as the heap size and Java 2D hardware acceleration features.

  • Each applet instance can request a different JRE version on which to run. Both selection of a specific JRE version, or any in a particular family, are supported in the Java Plug-in.

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

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

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

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

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

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.

12.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 19, "Deployment in the Browser" for information on using the Deployment Toolkit.

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

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

12.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 20.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.

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

12.5 Migrating Java Applets to the Java Network Launching Protocol

This section describes how to migrate existing Java Plug-in applets to the Java Network Launching Protocol (JNLP). You have the following options:

  • Migrate your applet to a Java Web Start application.

  • Use JNLP with your applet

Advantages and considerations for migrating to JNLP are described in the following sections.

12.5.3 Migrating an Existing Java Applet

Java Web Start technology has built-in support for applets. It is possible to run your applet directly with Java Web Start technology without any re-compilation of the applet. All you need do is to convert your applet HTML tags to a Java Network Launching Protocol (JNLP) file, using the JNLP applet-desc element. For example:

  <jar href="SwingSet2.jar"/>
<applet-desc main-class="SwingSet2Applet" name="SwingSet" width="625" height="595">
  <param name="param1" value="value1"/>
  <param name="param2" value="value2"/>
</applet-desc> Special Considerations

The following items are things to consider when migrating:

Contents    Previous    Next

Copyright © 1993, 2016, Oracle and/or its affiliates. All rights reserved.