Warning: Parameter 1 to Language::getMagic() expected to be a reference, value given in /home/wikija5/public_html/w/includes/StubObject.php on line 58
Debugging a servlet with tomcat and Eclipse tutorial - WikiJava
Wednesday, 23rd April 2014
Follow WikiJava on twitter now. @Wikijava

Debugging a servlet with tomcat and Eclipse tutorial

From WikiJava

Jump to: navigation, search
The author suggests:

buy this book

This tutorial will guide you through the process setting up the debugging of a simple Servlet under Eclipse using Tomcat. There are many plugins for Eclipse to help you configuring this, they all basically try to automatize the process explained in this tutorial.

It's always good to know what's going on under the hood.

note: this tutorial doesn't explain how to do the actual debugging, for information about this see the how to debug tutorial


The article

The configuration process for debugging a Java servlet may appear scary and complex to the beginner. However, in this tutorial I will clearly explain to you how debugging in Tomcat works as well as show you how to trigger a debugging session.


The debugging of a web application involves several components:

The Application Server
Generally speaking all the application servers support the debug mode, you just have to enable it when starting up the application server. It will then open a debugger server (generally on port 8000). You can then connect to this port to start debugging your application. In this tutorial I will show you how to activate the debug mode in Apache Tomcat.
You can debug your application using the default command line debugger, which will give you complete access to the debugger and to the debugged software. It is much easier though to use an IDE to support your debugging. The IDE will in this case use a TCP/IP connection to connect to the debug port (usually 8000) of the application server. In this example I will explain you how to configure Eclipse to debug your application running on Tomcat
The debugger
The debugger is an external software which allows you to debug your programs. It will be run by the application server. Most the application servers come already configured with a debugger, the one preinstalled in Tomcat is JDB.
Your code to debug
Your code will be running on Tomcat, I will not go into details on how to deploy your applications. You can debug with the method explained in this tutorial any application that runs on the application server, with no limitation whatsoever.

As you may notice the connection between the application server and the IDE uses the TCP/IP protocol, this implies that you don't need to have the tomcat running on your same machine, you don't even need to be in the same continent of it. It is enough that you have network access (ex. internet) to the server, and you can debug whatever application wherever in the world. Isn't this the coolest thing ever?

Setting tomcat in debug mode

Tomcat comes ready for debugging. To enable the debug mode you just need to write the following commands (under windows OS, analogous commands under different OSs):

set JPDA_TRANSPORT=dt_socket
catalina.bat jpda start

ensure to execute this from the {catalina_home}/bin directory. For simplicity I normally generate a shell script (a .bat file) to automatize the process.

I call this file debugmode.bat, it contains the three commands listed above and I normally put it in the {catalina_home}/bin directory. I am then able to start the tomcat in debug mode just by double clicking on this file with the mouse.

Deploying your application to Tomcat

In order to debug your application you must deploy it in the application server, you do this in the normal way. Nothing special about this.

Connecting Eclipse to Tomcat for debugging

To connect Eclipse to the debug server created by tomcat follow these simple steps:

  1. Start Eclipse
  2. open the project containing the servlet that you want to debug
  3. click on the arrow close to the debug button (the little bug) to see the drop down menu
  4. click on open debug dialog... (may also be labeled "Debug Configurations...")

Image:Debug button.png

  1. in the debug window double click on the Remote Java Application on the left hand side list. This will create a new debug profile.

Image:Create new debug profile.png

  1. choose a name for the debug profile (it's just for you to easily distinguish it)
  2. select the project you want to debug
  3. verify that the other settings match your configuration
    1. the host is the address for your tomcat, if Tomcat is running on your machine then it will be localhost.
    2. the port is the one you configured in when starting Tomcat, 8000 by default

Image:Debug profile.png

  1. click on debug

at this point eclipse will connect to the debug server loaded in Tomcat, so it's important to do this procedure after you load Tomcat.

You can set some breakpoints on your servlet and you will see that nothing happens. This is because the servlet is indeed NOT executed yet.

Proceeding with the debug

To execute the servlet, and start debugging your code you simply open your web browser (for example firefox) and navigate to the address of your servlet, this will execute it. The execution will block at the point you put your breakpoint and the web browser will block too, waiting for the page.

At this point you can normally debug your application as you do with other programs.

Note that your IDE is running on your machine, while the servlet is running on the application server, and so is the debugger. The two latter elements are working on the same machine, but the machine for them may be different than your local one.

Through the web browser you can call the servlet as many times as you want and your Eclipse will be showing you the details about these executions, without actually needing to click again on the debug button, this may be very handy.

Ending Debugging Session

To end a debugging session simply click the Disconnect button within the Debug perspective.File:Debug_disconnect.png

See Also

how to debug tutorial, Deploying in Tomcat tutorial

Comments from the users

To be notified via mail on the updates of this discussion you can login and click on watch at the top of the page

Good Tutorial

Thanks Buddy !

-- 17:56, 20 April 2009 (UTC)

Suresh said ...

Nice Tutorial... Thanks.

--Suresh 13:06, 17 September 2009 (PDT)

Angel said ...

First of all, nice tutorial.

I have Tomcat 6.0.20 running in Windows XP as a service. (I have no file named catalina.bat)

To set Tomcat in debug mode.

  1. Run the Configuration option in Windows Menu or run {catalina_home}/bin/tomcat6w.exe
  2. In Java tab, add this line to Java options:-Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n

--Angel 12:18, 9 April 2010 (PDT)


Thanks.. this was really cool and nicely explained !!

--Deepak 06:43, 4 August 2010 (PDT)

Prashant Tejura

Very helpful...Keep it up

--Prashant Tejura 00:26, 28 August 2010 (PDT)


Just what i was looking for. Thank you!

--Affan 10:12, 26 September 2010 (PDT)


Thanks a ton.

--Ambi 22:47, 28 November 2010 (PST)


thanks a lot

--Soni 23:53, 21 April 2011 (PDT)


Thanks dude

--Sylvain 09:07, 29 April 2011 (PDT)


Thanks. Exactly what I was looking for.

--Nice 05:26, 9 May 2011 (PDT)


Nice Tutorial

--Raj 02:39, 18 May 2011 (PDT)

Good Comment Angel

Your comment on starting the jvm in debug mode was very helpful, Angel

--Good Comment Angel 03:57, 13 July 2011 (PDT)


Great tutorial. I was wondering how I could do this...

--Nice 09:36, 27 July 2011 (PDT)


Great tutorial. I was wondering how I could do this...

--Nice 09:36, 27 July 2011 (PDT)

just what i needed

save me alot of time. thanks for the help

--just what i needed 06:38, 9 August 2011 (PDT)

Nice tutorial

Nice tutorial

--Nice tutorial 11:31, 17 August 2011 (PDT)


Buen comienzo

--MatEleviete 19:12, 24 August 2011 (PDT)

Comments on wikijava are disabled now, cause excessive spam.