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

# 13 Applets and Java Web Start Applications

This chapter describes some problems and solutions related to deploying Java applications.

This chapter contains the following sections:

- Configuration Problems

- Applet Troubleshooting

- Avoiding Security Dialogs

- Development Tips

## Configuration Problems

This section describes a number of problems concerning various configuration parameters and settings.

### Validation

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

Task 1Verify that the Java Plugin is working.

  1. Go to `http://java.com/en/download/installed.jsp`.

  2. Click Verify Java version.

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

Task 2Check that your browser knows about the Java plugin.

  - Chrome: Type `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.

Task 3Make sure the Java Runtime Environment is installed.

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

### Common Configuration Problems

Issue 1There is no Java Runtime installed.

  It is not sufficient to install the Java Developer Kit. A JRE is required to be able to run an applet or webstart. Note that if you use a 64-bit browser, then the 64-bit version of the JRE is required. Likewise, the 32-bit JRE is necessary for 32-bit browsers.

Issue 2Latest matching plugin/webstart is always used.

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

Issue 3Any change in the Java Runtime configuration requires the browser to be restarted.

  Java is not enabled.

  There are multiple places where Java could be disabled. Check the Java Control Panel and your browser plugins/addons list.

Issue 4Make sure new generation plugin is enabled.

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

Issue 5Java 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 global registry settings. To work around this, make sure you launch Java Control Panel as Administrator if you need to alter these settings.

Issue 6JavaScript needs to be enabled.

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

### Managing Java Runtimes

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 Java Control Panel if you need to:

- see what versions of JRE are installed and active

- temporarily enable/disable use of particular version of JRE

- set "global" parameters to be passed to JVM when applet or webstart application is launched

- enable/disable use of Java Plugin in the particular browser

- tune behavior of the plugin/webstart by specifying configuration parameters such as location of cache of temporary files or enable tracing

Figure 13-1 The Java Runtime Environment Settings Window

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

### Passing Parameters to the JRE

Troubleshooting, debugging, profiling and other development activities may require launching 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 you wish to change and enter parameters into this cell.

Note: These changes are "global", meaning that any Java Web Start application or applet that will be run 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 environment variable before launching `javaws` or the browser process.

  - `JAVAWS_VM_ARGS` for Java Web Start apps. For example:

        JAVAWS_VM_ARGS = -Dsome.property=true

  - `_JPI_VM_OPTIONS` for applets. For example:

        _JPI_VM_OPTIONS = -Dsome.property=true

    Note: You need to 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 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 Information

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, follow these steps:

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. Optionally, in the Java console category, select the Show console option to see trace information in the console window. The full trace 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:

    deployment.trace.level=all

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

    deployment.max.output.files=max_number_of_trace_files

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 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 Java Control Panel.

In particular, the Java technology networking layer automatically detects what networking stack to use. However, sometimes autodetection does not work and you may observe `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 observed on some Windows 7 systems when VPN software is used. This can be resolved by explicitly passing a parameter to the JVM:

    -Djava.net.preferIPv4Stack=true

For details, see "Passing Parameters to the JRE."

## Applet Troubleshooting

For modern browsers which 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, 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).

### Applet Does Not Start - Plugin Cheat Sheet

If your applet does not start, make sure to enable tracing and the Java console as explained previously. Then use hits below to find reason why applet does not work:

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

  - No

    Check if Java technology is detected, see "Validation" Is Java technology detected?

    - Yes

      Proceed to "Browser JVM Troubleshooting"

    - No

      It is likely to be a configuration issue. See "Common Configuration Problems" for common configuration problems and if it does not help, proceed to "Browser JVM Troubleshooting."

  - Yes, I have a trace file

    It is unlikely to be a configuration issue (unless you have the new generation plugin disabled). The problem is likely to be specific to this applet. Try to launch some other applets to confirm. Proceed to "Client JVM Troubleshooting."

Consult the sections below for further advice.

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 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. For details about the report file, see Appendix A.

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

Otherwise it is a JRE bug and needs to be reported to `http://bugs.java.com`.

Browser JVM Troubleshooting

To get more details about a JVM running in the browser process, set the following two environment variables before starting the browser:

    JPI_PLUGIN2_DEBUG=1
    JPI_PLUGIN2_VERBOSE=1

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 Oracle Solaris or Linux platforms, after setting the above 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.

Client JVM Troubleshooting

Check the latest trace file for ideas.

Note that 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 application fails with an `Out of memory` error, 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, this may cause application failure. The decision made by the user is remembered until the JVM is restarted. To see the security dialog again, the user may need to restart the browser.

Note that an applet can be deployed to reduce the risk of being affected by other applets and tailor execution environment for the applet's needs. See Applet Deployment in the JDK documentation. In particular, consider using the `separate_jvm parameter` argument.

### Unresponsive Web Page

If a page appears to be frozen while an applet starts, or in the runtime, the cause 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. See Applet Status And Event Handlers for details and examples.

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 that `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" for more details.

For other approaches, read "Troubleshooting Hanging or Looping Processes"

## Avoiding Security Dialogs

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 dialogs to simplify user experience.

### Signed Applications

If a Java applet/webstart 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, 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`.

Note: 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 security dialog box popup again in the future.

### 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 generally requires making changes to application implementation or repackaging the application. It is also possible to completely disable the software from checking for mixing trusted and untrusted code, but it is not recommended as this allows the user to run potentially unsafe code with no warning and without additional protections. For details on mixed code and ways to bypass this security warning dialog box, please refer to Mixing Privileged Code and Sandbox Code.

## Development Tips

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

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

### Debugging 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. Once the JVM is started, you can use your favorite IDE or tools to attach to it.

For details on how to pass arguments to the JVM running applet or Java Web Start application, see "Passing Parameters to the JRE" For example, here is 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 instructs the agent to suspend after the JVM is initialized and wait for a debugger to connect on port 4000. Please consult this guide for a full description of invocation options.

### Profiling 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. For details on how to pass options to the JVM, see "Passing Parameters to the JRE."

For example:

    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 NetBeans IDE to attach to the `java` process. Please consult your profiler documentation for exact details on what agent to use and how to configure it.

### Debugging Memory Leaks

See "Troubleshooting Memory Leaks" for any techniques available for standalone applications on the process running your applet or application. For example, use `jmap` to obtain a heap dump, VisualVM or `jconsole` to observe threads, or pass `-XX:+HeapDumpOnOutOfMemoryError` to the JVM (see "Passing Parameters to the JRE") to get a memory dump on error. Use the `jps` utility to find the process id for the process running your application.

Contents Previous Next

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