Java Platform Debugger Architecture (JPDA) with Tomcat, OC4J, Eclipse, IntelliJ IDEA and JDeveloper

With JPDA it is possible to propagate changes to compiled classes to the server immediately. This is very handy when you’re debugging your class files. With some older applications you have to restart your application server many times to make changes. With JPDA this is history. In this article I will show how you can connect with IDEA, Eclipse and JDeveloper to a remote Tomcat and OC4J instance.

Tomcat

The first step is to let Tomcat know you want to use JPDA. The Tomcat FAQ
 mentions several options. You can add command line parameters ( -Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n ) but I personally prefer the second option wrapped in a shell/batch file.The batch file for windows:

SET JPDA_ADDRESS=8000
SET JPDA_TRANSPORT=dt_socket
catalina jpda start

And for *nix:

export JPDA_ADDRESS=8000
export SET JPDA_TRANSPORT=dt_socket
./catalina jpda start

When you run the batch file Tomcat is started. Now we have to hook up our IDE’s.
Note that I tested everything with both Tomcat 5.5.20 and Tomcat 6.0.10.

OC4J

I only use OC4J when absolutely necessary, mainly because it takes so long to redeploy your application. With JPDA  you can speed up the process of redeploying, so I also tried JPDA with OC4J.
I tested everything with OC4J version 10.1.3.1.0.
Go to the j2ee\home directory and exceute the following command:
java -Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n -jar oc4j.jar
The following sections talk about how to connect to Tomcat. OC4J is no big difference. The only thing you have to keep in mind is that you don’t have to deploy your application like described. Just create a .war of you project, deploy it and connect your IDE to the OC4J instance (how to do that is explained in the following section)

Little warning before you start

I will now explain how to connect to Tomcat with 3 IDE’s. Note that the changes might not be propagated to the server the first time (probably some connection has to be set up). Just recompile or save your java files again and it should work.
IntelliJ IDEA
Our first IDE is IntelliJ.
Click on the edit configurations link

Next click on the plus sign, Tomcat Server, Remote

Click the configure button and search for your Tomcat home directory.

Add this server as the application server. Now click on the Startup/Connection tab

And change the port number at the debug section to 8000.
Now we have to tell the project to explode (that sounds even cooler than developing with pleasure, doesn’t it?) the files to the right directory. My project is called stripes-test and is located in the webapp directory of Tomcat. Right click your project and pick module settings and go to the Java EE Build Settings tab.

Hit the debug butotn, ctrl-f9 (make project) and  you’re ready to roll. The easiest way to test whether JPDA is working is to have a servlet without debugging statements. Run this sevlet and notice that there is no debugging (how strange). Now add some debugging statements in your code and recompile the class (Ctrl-shift-F9). When you run the same servlet again you’ll notice the new debugging statements, pretty cool huh?
With OC4J you musn’t connect to a Tomcat server, just a Remote instance:

Eclipse

In Eclipse you have to perform a step I’m not too happy with and there probably is a way to skip this step, but I just don’t know how. This step is deploying the application on your Tomcat server (I want this to happen automatically, but I can’t figure out how).
The next step is connecting the Eclipse debugger to Tomcat. Go to the run menu and click on Debug…
Click on remote appplication in the tree and hit the new button in the upper-left corner of the dialog.

Give the application a name and connect to port 8000, this dialog is quite straight forward. When you hit debug you’re connected to Tomcat (of course your Tomcat must be running). It’s not very easy to see that you’re connected when JPDA is new to you. The best way to make sure you’re really connected is to open the debug perspective.
When you did the right thing you should see a list with http threads (in Tomcat 6 this is slightly different, but when you see the words http and Catalina it is working)

The advantange of Eclipse is that you don’t have to recompile your classes, saving them is enough (but in IntelliJ you don’t have to save your files, that can be an advantage too). Try to run a servlet in Tomcat without any debugging statements and while Tomcat is running you add some lines of debugging to your class files, save the class file, run the servlet again and you’ll notice logging statements. I still can’t get enough of this cool trick, so the next step is JDeveloper.

JDeveloper

Since I don’t use Jdeveloper much this was a little bit harder for me, I almost gave up but it wasn’t that difficult after all.
Right click on your project and open the project properties. Go to the Run/Debug nod in the tree and create a new configuration.
Click on the configuraion and hit the edit button.

Make sure the checkbox ‘Remote Debugging and Profiling’ is checked (this can be found at the launch settings). The final configuration step is the remote node at the Tool Settings/Debugger node

Pick the ‘Attach to JPDA’ at the protocol and change the Host and Port. Your ready to debug your applicaiton. Right click your project and click ‘Start remote debugger’
At the Run Manager window you will see your project. When you want to detach the debugger don’t hit the red square!, this will terminate your Tomcat instance. Right click your project and choose Detach. Yes, this was a mistake I made.

Try to run a servlet in Tomcat without any debugging statements and while Tomcat is running you add some lines of debugging to your class files, save the class file, recompile it (alt-shift-f9) run the servlet again and you’ll notice logging statements. When your recompiled classes are successfully propagated to the server you well see the message “The recompiled classes have been redefined in the debuggee process.” In the Message log of JDeveloper.

Connecting to a remote server

In all the examples today I showed how to connect to your local Tomcat instance, it is also possible to connect to a remote instance. Just put the address of your server in the dialogs instead of localhost/127.0.0.1. Remote deploying is slightly more difficult (you have to use Maven2 or another tool for this)

Conclusion

When you use as many unit tests as I do you wonâ
€™t benefit much from the JPDA method. But with older app
lications without any unit tests it is a great way of debugging and is going to save you tons of time. Another thing about JPDA is that it is just so cool you can connect to any Tomcat instance and fiddle around with it. It’s just like changing the engine of your car when you’re on the highway.

I explained how to use JPDA with Tomcat, OC4J, Eclipse, IntelliJ IDEA and JDeveloper. I also tried Netbeans, but it took me too long (Netbeans is my least used IDE). But in principle every IDE or Application Server/Servlet Container with JPDA support should do what I explained.

Sources

http://www.eaves.org/blog-archive/000246.html
http://tomcat.apache.org/faq/development.html
http://www.oracle.com/technology/products/jdev/howtos/remotedebugservlet.html