Remote debugging with Tomcat with Eclipse

Lately, as I was handing over some projects to a new colleague, I realized that remotely debugging a Java application which is deployed on a Tomcat instance, isn't actually trivial to every developer. 

That being said, I guess it is legitimate for a Java developer not to know that nice feature since most of us will probably work through embedding an instance of Tomcat within Eclipse.

However, there are situations in which you would definitely have to debug remotely. That's the reason why I think this topic is worth writing a post...

Configuration

As stated in the Apache Tomcat documentation, in order to enable remote debugging support, you'll need to pass the following argument to the JVM used by Tomcat, when it starts : 

-Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n

Since Apache has already announced that they'll stop supporting Tomcat 5 soon, therefore I won't address this version of Tomcat's configuration. 

Regarding Tomcat 6 (and later), it already provides all the required configuration in the catalina.bat file : the default transport type is already set to "dt_socket" (the other supported transport type is "shared memory" but this one is not commonly used - actually, I haven't used it so far so I won't be able to tell you what it is about precisely) and the default port is set to 8000. In case the port number 8000 is already in use in your environment, you can simply change it by editing the catalina.bat file. 

Here's the section from the catalina.bat file that would interest you :

if not ""%1"" == ""jpda"" goto noJpda
set JPDA=jpda
if not "%JPDA_TRANSPORT%" == "" goto gotJpdaTransport
set JPDA_TRANSPORT=dt_socket
:gotJpdaTransport
if not "%JPDA_ADDRESS%" == "" goto gotJpdaAddress
set JPDA_ADDRESS=8000
:gotJpdaAddress
if not "%JPDA_SUSPEND%" == "" goto gotJpdaSuspend
set JPDA_SUSPEND=n
:gotJpdaSuspend
if not "%JPDA_OPTS%" == "" goto gotJpdaOpts
set JPDA_OPTS=-agentlib:jdwp=transport=%JPDA_TRANSPORT%,address=%JPDA_ADDRESS%,server=y,suspend=%JPDA_SUSPEND%
:gotJpdaOpts
shift
:noJpda

Suppose you need to change the default port, you'll, then, set another value to the JPDA_ADDRESS variable.

Running Tomcat with remote debugging enabled

• deploy the application you need to debug as usually
• start Tomcat by executing the catalina.bat script and providing the "jpda" argument 

(ex.: D:\Develtools\apache-tomcat-7.0.26\bin>catalina jpda start)

Then, all you need to do is to create a remote Java application in Eclipse through these few steps : 

1° Open the debug configurations 

2° Create a new Remote Java application : 

3° Specify the project you're debugging (in my example, I've configured remote debugging for one on my sample projects, named "Blog - Remote Tomcat debugging")

4° Specify the host on which the application to debug is deployed

5° Specify the port that is opened for debugging purpose (same as the one configured as JPDA_ADDRESS in the catalina.bat file from Tomcat)

6° Launch the Remote application by clicking on "Debug" 

At this point, you could set breakpoints wherever you want in the project's source code and if the code marked with your breakpoints is executed, the running thread will be suspended and you'll be able to watch variables' value, execute expression, and so on.