How to Use Tomcat Remote Debugging
    Main Page
    Lab Hardware
    Lab Software
 

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

27 Dec 2006 Simplified means of deploying/undeploying apps
22 Dec 2006 Clarified remote service shutdown/startup for debugging; reorganized major document structure.
12 Dec 2006 Revised for WTP and slightly new technique for debugging.
1 Jan 2006 Noted that support for the Lomboz-based capability has been removed.
24 Mar 2005 Clarified some instructions
22 Mar 2005 Added information on activating server definition
21 Mar 2005 Added some explanation regarding servlet mappings
7 Mar 2005 Original document


Hours  |  Support Information  |  News  | 
Policies  |  Emergencies