Debugging Applets in Java Plug-in

Print-friendly Version

Debugging Java applets in Java Plug-in has not been simple in the past, partly because the applets use many services and facilities from the Java 2 Runtime Environment, Java Plug-in, and the browser itself. If the applet does not work, the developer needs to spend time diagnosing the problem.

The purpose of this document is to simplify the debugging process. We will provide techniques and suggestions for developing applets in Java Plug-in and outline some of the most common mistakes in applet development.

How to debug applets in Java Plug-in

In order to debug applets, you must have appropriate version of the Java 2 SDK, Standard Edition installed on your machine. Also make sure to compile your .java files with -g option in javac. To begin debugging your applet:

1. Start the Java Plug-in Control Panel. On the Basic tab, specify the following 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
   	

   See JPDA Connection and Invocation for the details on the possible runtime parameters for debugging.

   
   
   
2. On 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 Java 2 SDK installation. For example, "JDK1.3 in C:\jdk1.3" . Do not select the Debug Options under the Advanced tab.
   
   
3. Start Internet Explorer or Netscape Navigator and 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 learn more about the jdb, see The Java Debugger.
   
   
5. Once the jdb debugger has attached to the VM, you can 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, make sure that only one instance of the browser is being used for debugging using the same connection address at the same time. Otherwise, it will result in conflict because the Java Runtime for each instance of the browser will try to gain exclusive access to the connection address. 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 be running in the desktop process during the lifetime of the user session.

You can use other Java 2 debuggers, like Inprise's JBuilder or Symantac's VisualCafe, instead of jdb. To use 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. Different Java Runtime Parameters may also be required 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 the 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 can be enabled from the Java Plug-in Control Panel. If the console is enabled, you will see the console window appear 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, but 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 controls whether Java Plug-in prints its trace messages during execution. This is useful to applet developers to determine what is occuring within Java Plug-in. The possible values are 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 controls whether the security system of the Java 2 Runtime Environment prints its trace messages during execution. This is usful to applet developers when a security exception is thrown in their applets or when their signed applet is 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 the 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 use various features in Java Plug-in. We also document some of the most frequently asked questions in our FAQ. Make sure you read and understand these documents before applet development, as it may save you hundreds of hours in debugging.

Isolating bugs

Although Java Plug-in provides the 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, the Java 2 Runtime itself or a user error. It is extremely important to determine where the bugs originates, because it will affect the speed of the bug evaluation and bug fix process. Here are some suggestions for isolating the bug:

1. Run the applets in both Internet Explorer and Netscape Navigator through Java Plug-in. 
2. Run the applets in appletviewer. Java Plug-in is mainly derived from appletviewer and has inherited problems from appletviewer as well. This step should be performed only if the applet doesn't require specific browser facilities that Java Plug-in provides, like HTTPS or RSA signing.
3. If the applet fails in appletviewer, it is 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 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 assumptions 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, like an improper DNS setup.
7. If the developers have identified the problems in Java 2 Runtime or Java Plug-in, please follow the instructions in the next section to submit a bug report to the appropriate product categories.

Submitting Bug Reports

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

• Complete description of the problem, and step-by-step instructions for reproducing it.
• Error messages captured by Java Plug-in Console or trace file.
• 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.
• A test case that demonstrates the problem.
• Specify whether the problem occurs in other browsers and appletviewer.
• Specify any workaround available.
• Specify your personal information (name and email address), so you may be contacted if additional information is needed for further bug investigation.

Submitting Feature Requests

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

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

Java Plug-in Feedback Alias

The purpose of the Java Plug-in Feedback alias http://java.sun.com/docs/forms/plugin-sendusmail.html is for customers to provide feedback on product features and the product in general. This alias is not intended for bug report submission. To submit a bug report, please follow the instructions earlier in this document.