Pre-General Availability: 2017-05-23

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

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

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

    Note:

    If you use a 64-bit browser, then the 64-bit version of the JRE is required. Similarly, the 32-bit JRE is necessary for 32-bit browsers.
  • Use latest matching plugin/webstart:

    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.

  • Restart 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 plugins/addons list.

  • Make 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.

  • Enable JavaScript:

    If JavaScript is disabled, then an attempt to launch a Java applet may fail at 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 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 system property com.oracle.usagetracker.track.last.usage to false.

    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/

    Last time usage time tracking and Java Usage Tracker (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 global registry settings. To work around this, make sure 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 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 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 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 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 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

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

See Pass Parameters to the JRE.

Troubleshoot Applets

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

The following are some problems with Applets and troubleshooting techniques.

Plugin Cheat Sheet for Applet Start

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, I don't get a trace file

      Check if Java technology is detected, see Validation

    • 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. Look at JVM client issues from Browser or Java Process Crash

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. See Fatal Error Log.

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

    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.

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

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

The following are two scenarios to avoid security dialogs.

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.

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:

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

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

  • Debug memory leaks:

    See Troubleshoot 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, jconsole to observe threads, or pass -XX:+HeapDumpOnOutOfMemoryError to the JVM (see Pass 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.