Java Technology Home Page
Downloads, APIs, Documentation
Java Developer Connection
Docs, Tutorials, Tech Articles, Training
Online Support
Community Discussion
News & Events from Everywhere
Products from Everywhere
How Java Technology is Used Worldwide

A-Z Index

The Source for Java Technology

Debugging applets in Java Plug-in

The experience of debugging Java applets in Java Plug-in has not been too easy in the past, partly because the applets relies lots of services and facilities from the Java 2 Runtime Environment, Java Plug-in, and the browser itself. If the applet doesn't work, the developer normally will need to spend certain amount of time to figure out what exactly the problem is, or take a wild guess.

The purpose of this document is to bridge this debugging gap. We will provide various techniques and suggestions for developing applets in Java Plug-in. We will also outlines some of the most common mistakes/problems in applet development, so you don't have to fall into the same trap again.

How to debug applets in Java Plug-in

In order to debug your applets you must have appropriate version of Java 2 Development Kit, Standard Edition (JDK) installed on your machine. Also make sure to compile your applet's .java files with -g option in javac. Steps to debug the applet are as follows

  1. Run the Java Plug-in Control Panel. Under the Basic tab, specify the parameters 
    -Djava.compiler=NONE 
    -Xnoagent 
    -Xdebug 
    -Xrunjdwp:transport=dt_shmem,address=<connection-address>,server=y,suspend=n

    in the Java Runtime Parameters. The <connection-address> could be any string which is used by the java debugger later to connect to the JVM. For example,

    -Djava.compiler=NONE 
    -Xnoagent 
    -Xdebug 
    -Xrunjdwp:transport=dt_shmem,address=2502,server=y,suspend=n 

    Visit the URL http://java.sun.com/products/jdk/1.3/docs/guide/jpda/conninv.html#Plugin  for the details on the possible run time parameters for debugging.

  2. Under the Advanced tab in the Java Plug-in Control Panel, select "JDK <version> in <jdk-path>" for the Java Runtime, where <version> is the Java Plug-in version and <jdk-path> is the path to the JDK installation. For example, "JDK1.3 in C:\jdk1.3" . Do NOT select the Debug Options under the Advanced tab. 
  3. Launch Internet Explorer or Netscape Navigator to load the page which contains the applet to be debugged. Make sure the applet code has been compiled with -g option in javac.
  4. Run the command jdb -attach <connection address> in a DOS command prompt. <connection address> is the name mentioned in the step 1. For example, if <connection address> is "2502", you will run the command as 

    jdb -attach 2502

    To know more about the jdb, visit the URL http://java.sun.com/products/jdk/1.3/docs/tooldocs/win32/jdb.html.
  5. Once the jdb debugger has attached to the VM, you may set up breakpoints in the applet. 
  6. When the applet in the browser reaches the breakpoint, it will stop executing, and you will see the debugger waiting for your input to continue debugging. 

When debugging applets in Java Plug-in, please make sure NO more than one instance of the browser are debugged using the same connection address at the same time. Otherwise, it will result in conflict because the Java Runtime running inside different instance of the browsers will try to gain exclusive access to the same connection address. Therefore, to debug applets in both Internet Explorer and Netscape Navigator, you should make sure either Internet Explorer or Netscape Navigator is running with Java Plug-in at any given time, but not both.

Debugging applets in Java Plug-in with Active Desktop is discouraged because an instance of Internet Explorer will always run in the desktop process in the lifetime of the user session.

You may also use other Java 2 debuggers instead of jdb. For example, you may use Inprise's JBuilder or Symantac's VisualCafe to debug applets in Java Plug-in. To debug applets using these debuggers, you will need to change the project option in these IDEs to attach Java Plug-in in the browser process on the same machine or remote machine. A different Java Runtime Parameters may also be required to be used in the Java Plug-in Control Panel. For more information, please consult your Java 2 debugger or IDE manuals.

Java Plug-in Console

One of the most powerful tools in Java Plug-in is Java Plug-in Console. It is a simple console window for redirecting all the System.out and System.err messages. By default, this console window is disabled, and it could be enabled from the Java Plug-in Control Panel. If the console is enabled, you should see the console window popup when Java Plug-in is used in the browser.

Java Plug-in Trace File

Similar to the Java Plug-in Console, this is a file that records all the System.out and System.err messages. By default, this trace file is disabled, and it is enabled automatically when Java Plug-in Console is enabled. The trace file is normally located in the user.dir, and the file is called plugin.trace. For example, in Windows NT, this file is located in C:\WINNT\Profiles\<username>\plugin.trace.

javaplugin.trace property

This property is for controlling whether Java Plug-in should print out its trace messages during execution. This is invaluable to applets developers to determine what exactly Java Plug-in is doing under the hood. The possible values are either true or false. By default, this property is set to false. To enable this property, -Djavaplugin.trace=true should be put in the Runtime Parameters in the Java Plug-in Control Panel.

java.security.debug property

This property is for controlling whether the security system of the Java 2 Runtime Environment should print out its trace messages during execution. This is invaluable to applet developers when security exception is thrown in their applets or when their signed applets not working. The following options are supported:

  • access - print all checkPermission results
  • jar - jar verification
  • policy - loading and granting
  • scl - permissions SecureClassLoader assigns

The following options can be used with access:

  • stack - include stack trace
  • domain - dumps all domains in context
  • failure - before throwing exception, dump stack and domain that didn't have permission

For example, to print all checkPermission results and dump all domains in context, -Djava.security.debug=access:stack will be specified in the Runtime Parameters in the Java Plug-in Control Panel. 

Online documentation

Java Plug-in provides a rich set of documentation on our web site to help developers leveraging various features in Java Plug-in. We also documented some of the most frequently asked questions in our FAQ as well. Please make sure you spend sometime to read and understand these documents during applet development, and it may save you hundreds of hours in debugging. 

Isolating bugs

Although Java Plug-in provides Java 2 Runtime Environment within Internet Explorer and Netscape Navigator, most of the facilities are provided by the Java 2 Runtime itself, rather than by Java Plug-in. Therefore, if a problem occurs in Java Plug-in, it may be either a problem in Java Plug-in or the Java 2 Runtime itself. It is extremely important to determine where the bugs belong, because it will speed up/slow down the bug evaluation and bug fix process. In some other cases, the bug may be an user error in the applet code. Here are some suggestions to isolate the bug:

  1. Run the applets in both Internet Explorer and Netscape Navigator through Java Plug-in. 
  2. Run the applets in appletviewer. Because Java Plug-in is mainly derived from appletviewer, so it also inherits problems from appletviewer as well. The step should be performed only if the applet doesn't require specific browser facilities that Java Plug-in provides. For examples, HTTPS or RSA signing.
  3. If the applet fails in appletviewer, it is very likely the problem is in Java 2 Runtime, and not in Java Plug-in. 
  4. If the applet fails in only one of the browsers (IE or NS), it is very likely a Java Plug-in problem.
  5. If the applet fails in both browsers but not appletviewer, it could be either a Java Plug-in problem or user errors. Please examine the applet code to see if it makes any assumption about the execution environment. For example, in appletviewer, the current directory is set to the current directory in the shell when appletviewer launched, while the current directory in Java Plug-in may be set to the browser's directory. Therefore, loading resources from current directory may work in appletviewer but not in Java Plug-in.
  6. Try to reproduce the problem on other machines or on other platforms. In some cases, the root of the problem is in the machine configuration. For example, DNS may not setup properly.
  7. If the developers have isolated the problems in Java 2 Runtime or Java Plug-in, please follow the instruction in the next section to submit a bug report to the appropriate product categories.

Submitting Bug Report

To submit bug report, you may go to the Java Development Connection's BugParade. Before submitting a bug, you should search the BugParade to determine if the bug has been reported previously and fixed. In some cases, workaround may also have been suggested. If the bug is not reported previously, you may submit a new bug report to the Java Plug-in team. In the bug report, please make sure the following information are included:

  • Complete description of the problem, and step-by-step description of how to reproduce it.
  • Error messages captured by Java Plug-in Console or trace file. Make sure javaplugin.trace is turned on.
  • Proxy configuration information. e.g. Auto proxy configuration, with the proxy configuration file attached.
  • Browser and platform information. e.g. Navigator 4.5 on Win98.
  • Test case that demonstrates the problem.
  • Specify whether the problem occurs in other browsers and appletviewer.
  • Specify any workaround available.
  • Specify your own information like name and email address, so you may be contacted if additional information are needed for further bug investigation.

Once the Java Plug-in team received the bug report with all the necessary information, it will be evaluated properly.

Submitting Feature Request

To submit feature request, you may go through Java Development Connection. In the feature request, please make sure the following information are included:

  • Complete description of the requested feature.
  • How this feature will be able to improve the quality of your product or Java Plug-in in general.

Once the Java Plug-in team received the feature request, it will be evaluated properly.

Java Plug-in Feedback Alias

The purpose of the Java Plug-in Feedback alias java-plugin-feedback@sun.com is for customers to provide feedback on various product features and the product itself in general, so the Java Plug-in team will be able to improve the product to fit the customers' needs. However, this alias is not intended for bug report submission. To submit bug report, please follow the instruction described earlier in this document.


[ This page was updated: 02-Dec-99 ]

Products & APIs | Developer Connection | Docs & Training | Support
Community Discussion | Industry News | Solutions Marketplace | Case Studies
Glossary - Applets - Tutorial - Employment - Business & Licensing - Java Store - Java in the Real World
Feedback | Map | A-Z Index

For more information on Java technology
and other software from Sun Microsystems, call:
(800) 786-7638
Outside the U.S. and Canada, dial your country's AT&T Direct Access Number first.
Sun Microsystems, Inc.
Copyright ?995-2000 Sun Microsystems, Inc.
All Rights Reserved. Terms of Use. Privacy Policy.