Chapter 5   Debugging Servlets and JSPs


This appendix gives guidelines for debugging servlets and JSPs in iPlanet Web Server 6.0. It includes the following sections:

• Servlet Debugging

• JSP Debugging

• Generating a Stack Trace for Debugging

• Using Forte for Java to Debug Servlets and JSPs

• JPDA Options for Debugging

Debugging servlets and JSPs requires that you edit thejvm12.conf file as described in this chapter. For more general information about this file, see Appendix C "JVM Configuration."

Servlet Debugging

---

If the server has been instructed to use a JDK, you can do remote servlet debugging. If the server is using the JRE, you need to switch it to using the JDK before you can do remote debugging. For information on instructing the server to use the JDK or the JRE, see the section "Configuring JRE/JDK Paths."

Assuming that the server is using the JDK, you can enable remote debugging by following these steps:

1. Make sure that the server is running in single-process mode. Single-process mode is the default, but you can check in the file magnus.conf to make sure that the MaxProcs parameter is not set to a value greater than 1. If you do not see a setting for MaxProcs in magnus.conf, the default value of 1 is enabled for it. For more information about single process mode versus multi-process mode, see the iPlanet Web Server Administrator's Guide.

2. Set the following parameters in jvm12.conf as appropriate:
   
   jvm.enableDebug=1
   java.compiler=NONE

3. To send exceptions to the client in addition to the log file, set the following parameter. If the client is a browser, exceptions are displayed in the browser.
   
   jvm.trace=7

4. On some platforms, you may be required to specify the bootclasspath. For example, for Solaris platforms, if Java 1.2 is in /java, you set it as follows in jvm12.conf:
   
   jvm.option=-Xbootclasspath:/java/lib/tools.jar:/java/jre/lib/rt.jar

5. Start the server manually and record the password for remote debugging (this is displayed on the console).

6. Start the Java debugger:
   
   jdb -host your_host -password the_password

You should be able to debug your Java classes now using the jdb command.

JSP Debugging

---

You can debug your JSPs by following these steps:

1. Make sure that the server is running in single-process mode. Single-process mode is the default, but you can check in the file magnus.conf to make sure that the MaxProcs parameter is not set to a value greater than 1. If you do not see a setting for MaxProcs in magnus.conf, the default value of 1 is enabled for it. For more information about single process mode versus multi-process mode, see the iPlanet Web Server Administrator's Guide.

2. Set the following parameters in jvm12.conf as appropriate:
   
   java.compiler=NONE
   jvm.trace=6
   nes.jsp.enabledebug=1

3. To send exceptions to the client in addition to the log file, set the following parameter. If the client is a browser, exceptions are displayed in the browser.
   
   jvm.trace=7

Setting java.compiler=NONE includes line numbers of the Java source code in the verbose output of the log files. Setting jvm.trace=6 or jvm.trace=7 enables verbose output from the JSP compiler and the servlet engine. Setting nes.jsp.enabledebug=1 makes iPlanet Web Server 6.0 generate debuggable Java servlets from the JSPs.

Generating a Stack Trace for Debugging

---

You can generate a Java stack trace for debugging as described here:

http://developer.java.sun.com/developer/technicalArticles/Programming/Stacktrace/

Comment out the jvm.option=-Xrs flag (for reduced signal usage) in the jvm12.conf file before generating the stack trace. If the -Xrs flag is used, the server may simply dump core and restart when you send the signal to generate the trace.

For more about the jvm12.conf file and using jvm.option, see Appendix C "JVM Configuration."

Using Forte for Java to Debug Servlets and JSPs

---

To set up iPlanet Web Server so you can use the Forte for Java debugger, follow these steps:

1. If you have not already done so, install the JDK version 1.2.x that iPlanet Web Server requires as described in "What Does the Server Need to Run JSP?" The specific version you need depends on your platform.

2. Install the JDK version 1.3, available here:

   http://java.sun.com/j2se/1.3/

   Although iPlanet Web Server uses the JDK version 1.2.x, Forte for Java requires version 1.3.

3. Install Forte for Java, Community Edition 1.0, available here:

   http://www.sun.com/forte/ffj/ce/

4. iPlanet strongly recommends that you also install the JPDA, available here:

   http://java.sun.com/products/jpda/

5. If you installed the JPDA, copy all the files from the jpda_install/bin directory to the jdk1.2_install/jre/bin directory. Also copy the jpda.jar file from the jpda_install/lib directory to the jdk1.2_install/jre/lib/ext directory.

   Note that the JPDA runs on JDK 1.2, not 1.3.

6. On Windows NT, add the following line to the magnus.conf file to enable the NT console:

   Init fn="nt-console-init" stdout=console stderr=console

7. Edit the jvm12.conf file to enable remote debugging. If you did not install the JPDA, add the following lines:

   jvm.enableDebug=1
   jvm.compiler=NONE

   If you installed the JPDA, add the following lines:

   jvm.enableDebug=1
   jvm.compiler=NONE
   jvm.option=-classic
   jvm.option=-Xnoagent
   jvm.option=-Xrunjdwp:transport=dt_socket,server=y,suspend=n

8. Start Forte for Java, and mount the directory that contains the servlet or JSP you want to debug.

9. Start iPlanet Web Server. You will see a line similar to the following displayed in the console:

   Listening for transport dt_socket at address: port_number

   Write down this port_number.

10. In Forte for Java, select the Debug menu and the Attach to VM... option. Type the port_number in the Port: text box, then select OK.

You are now ready to debug your servlet or JSP.

JPDA Options for Debugging

---

A list of debugging options that you can include in the jvm12.conf file if the JPDA is installed is available here:

http://java.sun.com/products/jpda/doc/conninv.html#Invocation