In the instructions below, substitute your UW Net ID wherever you see "uwnetid".

Last updated: 27 Dec 2006

Debugging a dynamic web page application based on servlets (tomcat) has always been problematic -- it is difficult to find where problems are when the code is executing on another computer in another user's address space. This can be lessened somewhat by running a local copy of tomcat, but in some environments, this is not feasible.

Since Java 1.3, it has been possible to use the Java Platform Debugging Architecture (JPDA), but few faculty and students know how to use it, and especially in the context of remotely debugging JSP applications. This document describes the process for configuring the local development environment in Eclipse such that you can deploy and debug your JSP application in a remote server running your own Tomcat Development Service.

Tomcat Development Service Setup

1. You should already have a debugging port (second line in ~/.catalina_port)

   However, if you have previously (i.e., prior to 15 Dec 2004) requested this service, first you need to rename or remove it and request it again to get the additional debugging port:

   1. rm -rf ~/catalina
   2. rm -f ~/.catalina_port

   In either case, when you request_tomcat as described in Using the Tomcat Development Service, now you will get the service and debugging ports.

2. Mount your home directory (once)

       mounthome
     

   This step is only done once after you request the Tomcat Development Service and you see the ~/catalina directory. It will copy some information over to your Windows home directory (H:\.catalina_info) that will be used to define your remote server.

3. Set up the ability to debug (once per debug session)

   Whenever you want to debug, you need to start the local tomcat development service with the debugging option:

       ~/catalina/startup debug
     

   This uses the second number in the ~/.catalina_port file, which is the debugging port number. startup writes this number to the console -- you will need it to set the debugging port in Eclipse so Eclipse can connect to the server to allow you to debug remotely.

Eclipse 3.2 Setup

1. The Web Tools Platform (WTP) plugin must be installed (once)

   Please follow the instructions to download the plugin. Read the download instructions carefully, as they package Eclipse with everything you need, the prerequisite software and WTP, or just WTP. Eclipse and WTP have already been installed on Institute lab computers. The explanation which follows might help you install and configure WTP similarly in another environment.

   In menu Windows/Preferences/Ant/Runtime/Classpath,

   • expand "Global Entries"
   • click on "Add External JARs..."
   • browse to add C:\Program Files\Apache Software Foundation\Tomcat 5.5\server\lib\catalina-ant.jar
   • click "Apply"

   This is part of the foundation that allows you to deploy and undeploy your servlet.

2. Create Project and Deploy

3. Debug Deployed Application

Create Project and Deploy

1. Next, you need to create a WTP Dynamic Web Project (once per project)

   This is done via the wizard from menu File/New/Project/Web/Dynamic Web Project". Provide a project name, and create/select a target runtime called Tomcat 5.5.

2. Add your servlet code and test it using the local environment

3. Deploy your tested code to a remote tomcat server running from your account.
   • Create a Web Archive (.war) file

     Right-click on your project name, and choose "Export...", and specify that you want to create a Web/WAR file called the same as your project name. Put it in C:\temp

   • Connect to the Tomcat Manager Application

     Use the Tomcat Manager Application to deploy (or later undeploy) your web applications. To stay within the Eclipse IDE, open the Web Browser (one of the toolbar items) and use this URL:

         http://repos.insttech.washington.edu:%port%/manager/html
         

     substituting your port number (see below) for %port%, and supplying your UW Net ID (or team account name) for the "Tomcat Manager Application" User Name prompt, and the corresponding password for the Password prompt.

     Here is how to find the information to substitute:

     • For individual (not team) projects, use the H:\.catalina_info file set above for information about values to substitute:
       • %port% -- the port number (second line)

       • username is your UW Net ID

       • password associated with Tomcat username (first line)

     • For team projects, on repos you will need to look at the team's:
       • ~/.catalina_port file for the port number (first line)
       • ~/.pw file for the user name (team account name) and password on the tomcatdev user line

   • Deploy the application

     Your .war file is not on the server, but on the client. Therefore, you need to use the section "WAR file to deploy" and click on the Browse... button to find the path to the .war file you created. That file will be uploaded when you click on the Deploy button.

4. Test your application

   You should be able to test your application from the browser using something like:

     http://repos.insttech.washington.edu:%port%/%project_name%/servletname
     

   where you substitute the values you specified above for %port%, %project_name% should be the same as your Eclipse project name, as well as your servlet's name.

Debug Deployed Application

1. Shutdown your Tomcat service at your port (because we will restart it for debugging) on repos:

     ~/catalina/shutdown
     

2. Startup your tomcat service to run in debug mode (on repos):

     ~/catalina/startup debug
     

   You should see your debug port number.

3. Verify on repos that your Tomcat service is running in debug mode:

   Substitute your UW Net ID for "uwnetid":

     ps aux | grep uwnetid | grep Xdebug
     

   If all went well, you should see a long listing for a java process that has "catalina" in it, as well as this string: -Xdebug -Xrunjdwp:transport=dt_socket. If you don't see that, read or re-read Using the Tomcat Development Service. If all else fails, contact an Institute lab staff member.

4. Make sure your project is deployed as instructed above.

5. Configure for debugging

   On your project name, right click and choose menu Debug As/Debug..., you will see a Configurations choice that allows you to create new debugging specification on a per project basis.

   • Right-click on the "Remote Java Application" item and select "New".

   • In the "Connection Properties" section, configure the Host repos.insttech.washington.edu and the Port (i.e., the number of your debugging port (last line of H:\.catalina_info or on repos, ~/.catalina_port).

   • Click on the "Apply" button.

     This should enable the debugging perspective to appear when the servlet is executed.

   • Set a breakpoint in your servlet code.

   • In a browser, refer to the servlet page.

     For example:

     http://repos.insttech.washington.edu:8092/myweb/MyServlet
         

     Note that 8092 is not the debugging port, but the main service port for your local tomcat development service.

   • You should note that the servlet page does not display (the browser hangs) while Eclipse is paused at a breakpoint.

Change Log