16 Applets and Java Web Start Applications

Descriptions of some problems and solutions related to deploying Java applets and Java Web Start applications.

This chapter contains the following sections:

Configuration Problems

Troubleshooting techniques to solve configuration problems in applets and a Java Web Start application.

This following sections describes a number of problems concerning various configuration parameters and settings, and suggests troubleshooting techniques for configuring applets and Java Web Start applications.


Validation techniques when your application does not run.

If your application does not run, perform the following checks:

  1. Verify that the Java Plugin is working.
    • Go to Verify Java and Find Versions.

    • Click Verify Java version.

    • If you see that the expected Java technology version is reported, then the plugin is enabled and found.

  2. Check that your browser knows about the Java plugin.
    • Chrome: Enter about: plugins in the address bar.

    • Firefox: On the Tools menu, select Addons and click Plugins.

    • Internet Explorer: On the Tools menu, select Manage Addons.

  3. Make sure the Java runtime environment is installed.

    On Windows, check the list of installed programs in the Control Panel.

Common Configuration Problems

Troubleshooting techniques to solve common configuration problems.

The following are troubleshooting techniques for common configuration problems:

  • Install Java runtime:
    It is not sufficient to install the Java Developer Kit. A JRE is required to be able to run an applet or a Java Start application.


    The JRE requires a 64-bit browser.
  • Use the latest matching plugin/webstart:

    There could be just one plugin registered in the browser, and the JRE always registers the plugin from the latest JRE on the system as active. The only way to ensure the use of an older plugin is to uninstall newer JREs.

  • Restart the browser for any change in the Java runtime configuration:

    Java is not enabled or there are multiple places where Java could be disabled. Check the Java Control Panel and your browser plug-ins/addons list.

  • Ensure that the new generation plugin is enabled:

    Unless you need to run in the legacy mode, ensure that the New generation plugin is enabled in the Java Control Panel.

  • Enable JavaScript:

    If JavaScript is disabled, then an attempt to launch a Java applet may fail at a very early stage.

  • Disable last-time usage time tracking:
    The JRE keeps track of the last time it was used. It records, in a file, the last time it was used for an applet or a Java Web Start application, or invoked from the command line or through any other method.

    By default, last-usage time tracking is enabled. To disable last-usage time tracking, set the Java Usage Tracker property com.oracle.usagetracker.track.last.usage to false in the Java Usage Tracker properties file. See Java Usage Tracker Properties in Java Platform, Standard Edition Usage Tracker Guide for more information.

    If last-usage time tracking is enabled, then it creates a file in one of the following directories, depending on your operating system:
    • Windows: %ProgramData%\Oracle\Java\.oracle_jre-usage\

    • All other operating systems: ${user.home}/.oracle_jre_usage/


    Java Usage Tracker, which is a commercial feature, and last-usage time tracking, which is not a commercial feature, are enabled separately; disabling one does not disable the other.

  • Java control panel fails to make changes in the Java config:

    On Windows 7 or Windows Vista systems with UAC on, the Java Control Panel may fail to update the global registry settings. To work around this, ensure that you launch Java Control Panel as Administrator if you need to alter these settings.

Manage Java Runtime

You can use the Java Control Panel tool to manage the list of installed Java Runtime Environments and their behavior.

The Java Control Panel can be launched from the bin directory of the JRE installation folder. On Windows operating systems, you can also access it from Control Panel > Java.

Use the Java Control Panel if you need to:

  • See which versions of the JRE are installed and active

  • Temporarily enable or disable the use of a particular version of the JRE

  • Set "global" parameters to be passed to the JVM when an applet or Web Start application is launched

  • Enable or disable the use of the Java Plugin in a particular browser

  • Tune behavior of the Plugin or Web Start application by specifying configuration parameters such as the location of cache of temporary files or enable tracing, as shown in Figure 16-1.

Figure 16-1 The Java Runtime Environment Settings Window

Description of Figure 16-1 follows
Description of "Figure 16-1 The Java Runtime Environment Settings Window"

Pass Parameters to the JRE

Troubleshooting, debugging, profiling, and other development activities may require launching the JVM with a special set of parameters. One way to accomplish this is to use the Java Control Panel.

Open the Java Control Panel, and click View on the Java tab. Select the Runtime Parameters cell for the JRE that you want to change, and enter parameters into this cell.


These changes are global, meaning that any Java Web Start application or applet that runs using this version of JRE will have these parameters set (in addition to what the applet tag or JNLP file may specify).

To pass parameters to a specific JVM used with Java Web Start or an applet, use one of the following techniques:

  • Set the environment variable before launching javaws or the browser process.
    • JAVAWS_VM_ARGS for Java Web Start applications. For example:

      JAVAWS_VM_ARGS = -Dsome.property=true
    • _JPI_VM_OPTIONS for applets. For example:

      _JPI_VM_OPTIONS = -Dsome.property=true


      You must restart your browser after you set the environment variable. If you are setting this environment variable in the command shell, then you must use the same command shell to launch the browser so that the browser inherits the value of the environment variable.

  • Use the -J option for the javaws command. For example:
    javaws -J-Dsome.property=true http://example.com/my.jnlp

Java Deployment Home

This is the place where the main configuration files are kept. The location is specific to your operating system:

  • Windows XP: %HOME%\Application Data\Sun\Java\Deployment

  • Windows 7/Vista: %APPDATA%\..\LocalLow\Sun\Java\Deployment

  • Oracle Solaris/Linux: %HOME%/.java/deployment

Deployment Tracing

Both Java Plug-in and Java Web Start can print trace information into trace files. This includes log information from the JRE itself as well as everything your application may be printing to System.out or System.err.

To get access to trace information:

  1. Open the Java Control Panel (jre_home_dir/bin/ControlPanel).
  2. Select the Advanced tab.
  3. In the Debugging category, select the Enable tracing check box.
  4. (Optional) In the Java console category, select the Show console option to see the trace information in the console window. The full trace file still will be saved to a file.

The trace file is saved into the log directory in the Java deployment home folder. See Java Deployment Home. The file name has the prefix javaws or plugin, depending on what you are running. One trace file is produced per process, but one application can be launched using several processes.

To get the maximum level of detail in the trace file, edit the deployment.properties file (which is located in the Java deployment home directory) and add the following line:


By default, a maximum of five trace files are created. The oldest trace files are automatically deleted. To change the limit of the maximum number of trace files, add the following line to the deployment.properties file:


You can use the Java console to view the trace log at runtime. By default, the Java console is hidden. Enable it in the Java Control Panel.

Deployment Cache

Application jars and resources are cached on the disk to avoid loading them the next time they are needed.

The default location of the cache depends on the operating system and can be overridden in the Java Control Panel.

Settings and controls for the cache are available in the General tab of the Java Control Panel, in the Temporary Internet Files section. Click Settings to change the location and size of the cache. Click View to see what files are in the cache.

You can clean the cache by running javaws -uninstall, or open the Java Control Panel's General tab, click View, and delete the files manually. You can also use the Java Control Panel to uninstall individual applications and extensions.

Network Configuration

In general, Java Web Start applications use the system network configuration by default, and applets use the browser network settings. You can set network proxies explicitly using the Java Control Panel.

In particular, the Java technology networking layer automatically detects which networking stack to use. However, sometimes autodetection does not work, and you may see Permission Denied exceptions trying to open a socket to download your application or applet, even while the same URL is accessible using the same proxy settings with other tools. This problem was seen on some Windows 7 systems when VPN software was used. This can be resolved by explicitly passing a parameter to the JVM:


See Pass Parameters to the JRE.

Troubleshoot Applets

For modern browsers that support tabs, each tab might be a separate browser process. If a Java applet is embedded in a browser page and the next generation plugin is being used, then usually the process associated with the browser tab creates a JVM within the process (browser VM). The browser VM will create another JVM process (client VM) which will run the applet and manage the applet's life cycle. The client VM is a Java process (java.exe on Windows and java on Oracle Solaris/Linux platforms).

The following are some problems with applets and troubleshooting techniques.

Plugin Cheat Sheet for Applet Start

If your applet does not start, ensure that you enable tracing and the Java console as explained previously. Then, use the following hints to find the reason why the applet does not work.

Do you get a trace file generated or see the Java console?

Browser or Java Process Crash

A crash could be caused by a platform or application issue.

Typically, if a crash happens in the JVM, then there should be an hs_err_*log file created in the current working directory. On Windows, it is often placed on the desktop. It is the same crash report file as for standalone applications. See Fatal Error Log.

If you can see native libraries loaded from the deployment cache directory, especially if you see code from these libraries in the crash stack, then it is very likely to be a bug in the application.

Otherwise, it is a JRE bug and needs to be reported to Bug Database.

The following are two scenarios to consider for a crash by platform or application issue.

  • JVM browser issues: Get more details about a JVM running in the browser process. Set the following two environment variables before starting the browser:


    On Windows, there should be a command window associated with the browser process. All browser VM debug output goes into the command window. Check to see if any exceptions are visible there. A Java thread dump can be obtained by using the Control+Break key sequence on the command window.

    On the Oracle Solaris or Linux platforms, after setting these variables, start the browser from the same session. All browser VM debug output goes into the terminal window. To get a Java thread dump, on a separate terminal, use kill -3 pid or kill -SIGQUIT pid, where pid is the process ID of the browser process.

    There are heartbeat messages sent between the client VM and browser VM. The heartbeat messages can be turned off by setting the JPI_PLUGIN2_NO_HEARTBEAT environment variable to 1. This will help isolate whether the problem is related to the heartbeat.

    If the log is not opening and environment variables are set in the browser process, then it is likely that the JRE is not installed correctly or Java is disabled. Check for configuration errors, and try to reinstall the JRE if nothing else helps.

  • JVM client issues: Check the latest trace file for ideas.

    Note: The same client JVM may be shared between multiple applets. Sometimes intermittent failures happen because the shared JVM does not have enough resources available (for example, heap size). In that case, a page reload often helps to resolve the problem.

    If an application fails with an Out of memory error, then the heap size needs to be increased. This can be done in the application deployment descriptor (JNLP file) or in the Java Control Panel using runtime parameters for JRE in use.

    If an application is signed and the user declined a security dialog box, then this may cause the application fail. The decision made by the user is remembered until the JVM is restarted. To see the security dialog box again, the user may need to restart the browser.

Unresponsive Web page

The following are scenarios that could cause an unresponsive web page.

  • Frozen applet at applet start or during runtime:

    The cause for a frozen applet at applet start or during runtime could be Liveconnect calls.

    On startup, an attempt to access the Java applet from JavaScript may block the JavaScript engine until the applet initialization is complete. It is recommended to postpone JavaScript access until the applet is ready, and use the enableStatusEvents parameter to unlock non-blocking access to applet status checks.

    To use Liveconnect in runtime, it is recommended to make JavaScript calls return quickly to avoid blocking the single-threaded JavaScript engine.

  • Applet or browser hangs:

    The best source of information in this case is the stack state for both client and browser JVMs.

    Use jstack to collect the JVM stack status for the browser JVM (by running jstack browser-pid) and client JVM. Note: The jstack may highlight a deadlock if it happens in context of one of these VMs, but it cannot do this if the deadlock involves both processes. In this case, the thread stacks need to be examined manually. See The jstack Utility.

    See Troubleshoot Process Hangs and Loops .

Avoid Security Dialog Boxes

The Java Runtime will automatically warn the user about possible security sensitive issues. If you are confident that applications you use are safe, then it is possible to bypass security dialog boxes to simplify the user experience.

The following are two scenarios to avoid security dialog boxes.

Signed Applications

If a Java applet or Web Start application is signed, a certificate security warning dialog box will pop up and the user must click Run to give all permissions to the code of the application.

To avoid seeing this dialog box, you can do one of the following:

  • User accepts the certificate used to sign the application and selects the Always trust content from this publisher check box. Then, next time permissions will be granted to this application automatically (until the certificate expires or is removed from the trusted key store).

  • The certificate can be manually imported into the JRE trusted certificate store. To import the certificate using the Java Control Panel, on the Security tab, click Certificates and then Trusted Certificates. To import a certificate into the certificate store from the command line, use the keytool utility (in the JRE's bin folder).

  • Grant AllPermissions in the Java policy file located at ${user.home}/.java.policy, or point to any Java policy file which has AllPermissions in the $(JRE_HOME)/lib/security/java.security file. Permissions can be granted to all applications or restricted to a particular URL. See Default Policy Implementation and Policy File Syntax for more details on .java.policy.


If automatic granting of permissions is not desired, then use the Java Control Panel to remove certificates from trusted certificate keystore. This will result in the security dialog box popping up.

Mixed-Code Issues

Signed Java Web Start applications and applets that contain signed and unsigned components could potentially be unsafe unless the mixed-code was intended by the application vendor. The latest versions of the Java runtime raise a mixed-code warning dialog when a program contains both signed and unsigned components and suspicious use is detected.

Bypassing this dialog box generally requires making changes to application implementation or repackaging the application. It is also possible to completely disable the software from checking for mixed trusted and untrusted code, but that is not recommended because this allows the user to run potentially unsafe code with no warning and without additional protections.

Development Tips

For Java Web Start applications and applets, you can use most of techniques available to debug and profile standalone applications, except that you will need to use the attach mechanism instead of direct launch.


Both the plugin and Java Web Start will spawn additional java or javaw processes that will actually run the JVM executing the application or applet. You must attach to those processes to be able to collect information about your applet. For example, if you want to get a memory dump of your applet, then you must first figure out the process ID for the java process executing the PluginMain class. For example, use the The jps Utility from the JDK and then use The jmap Utility to get a memory dump.

The following are development tips for debugging applets:

  • Debug Java applets and Web Start applications:

    Just as with standalone Java applications, any JPDA-based debugger can be used to debug your applet or Web Start application; for example, see The jdb Utility or the NetBeans debugger.

    You will need to enable the JDWP agent for the JVM running your application and specify the port number. After the JVM is started, you can use your favorite IDE or tools to attach to it.

    For details about how to pass arguments to the JVM running applet or Java Web Start application, see Pass Parameters to the JRE. The following example shows how you can pass details to the Java Web Start application from the command line.

    bash$ javaws -J-agentlib:jdwp=transport=dt_socket,address=4000,server=y,suspend=y http://acme.com/my/webstart.jnlp

    This code instructs the agent to suspend after the JVM is initialized and wait for a debugger to connect on port 4000.

  • Profile Java applets and Java Web Start applications:

    When you profile a standalone Java application, your favorite IDE is likely to be using the JVMTI agent to collect details on program execution. You can do the same for applets and Java Web Start applications but you may need to configure the JVMTI agent explicitly by passing the -agentpath option to the JVM, as shown in the following example. To know more about how to pass options to the JVM, see Pass Parameters to the JRE.

    set _JPI_VM_OPTIONS="-agentpath:C:\Tools\NetBeans\profiler\lib\deployed\jdk16\windows\profilerinterface.dll=C:\Tools\NetBeans\profiler\lib,5140"

    Now, launch your browser. The NetBeans profile agent is enabled for any applet you will be running in this browser session. You can use the NetBeans IDE to attach to the java process. Consult your profiler documentation for exact details about which agent to use and how to configure it.

  • Debug memory leaks:

    See Troubleshoot Memory Leaks for the techniques available for standalone applications on the process running your applet or application. For example, use jmap to obtain a heap dump, jconsole to observe threads, or pass -XX:+HeapDumpOnOutOfMemoryError to the JVM (see Pass Parameters to the JRE) to get a memory dump if an error occurs. Use the jps utility to find the process ID for the process running your application.