Tuesday, January 10, 2012

Launching and Debugging Tomcat from Eclipse without complex plugins

 Modern IDEs like Eclipse provide various Plugins to ease web developement. However, I believe that starting Tomcat as "normal" Java application still provides the best debugging experience. Most of the time, this is because these tools launch Tomcat or any other servlet container as external process and then attach a remote debugger on it. While you're still able to set breakpoints and inspect variables, other features like hot code replacement don't work that well.

Therefore I prefer to start my Tomcat just like any other Java application from within Eclipse. Here's how it works:

This article addresses experienced Eclipse users. You should already know how to create projects, change their built path and how to run classes. If you need any help, feel free to leave a comment or contact me.

We'll add the Tomcat as additional Eclipse project, so that paths and all remain platform independent. (I even keep this project in our SVN so that everybody works with the same setup).

Step 1 - Create new Java project named "Tomcat7"

Step 2 - Remove the "src" source folder

Step 3 - Download Tomcat (Core Version) and unzip into our newly created project. This should now look something like this:

Step 4 - If you havn't, create a new Test project which contains your sources (servlets, jsp pages, jsf pages...). Make sure you add the required libraries to the built path of the project

 Step 5.1 - Create a run configuration. Select our Test project as base and  set org.apache.catalina.startup.Bootstrap as main class.

Step 5.2 -  Optionally specify larger heap settings as VM arguments. Important: Select the "Tomcat" project as working directory (Click on the "Workspace" button below the entry field.

Step 5.3 - Add bootstrap.jar and tomcat-juli.jar from the Tomcat7/bin directory as bootstrap classpath.Add everything in Tomcat7/lib as user entries. Make sure the Test project and all other classpath entries (i.e. maven dependencies) are below those.

Now you can "Apply" and start Tomcat by hitting "Debug". After a few seconds (check the console output) you can go to http://localhost:8080/examples/ and check out the examples provided by Tomcat.

Step 6 - Add Demo-Servlet - Go to our Test project, add a new package called "demo" and a new servlet called "TestServlet". Be creative with some test output - like I was...

Step 7 - Change web.xml - Go to the web.xml of the examples context and add our servlet (as shown in the image). Below all servlets you also have to add a servlet-mapping (not shown in the image below). This looks like that:


Hit save and restart tomcat. You should now see your debug output by surfing to http://localhost:8080/examples/demo/test - You now can set breakpoints, change the output (thanks to hot code replacement) and do all the other fun stuff you do with other debugging sessions.

Hint: Keeping your JSP/JSF files as well as your web.xml and other resources already in another project? Just create a little ANT script which copies them into the webapps folder of the tomcat - and you get re-deployment with a single mouse click. Even better (this is what we do): You can modify/override the ResourceResolver of JSF. Therefore you can simply use the classloader to resolve your .xhtml files. This way, you can keep your Java sources and your JSF sources close to each other. I will cover that in another post - The fun stuff starts when running multi tenant systems with custom JSF files per tenant. The JSF implementation of Sun/Oracle has some nice gotchas built-in for that case ;-)


  1. Any idea if a similar method can be used with Glassfish?

  2. Dear Ed,

    I used GF some years ago. If I remember it correctly, asadmin starts several processes (message queueing, derby db, appserver itself). Therefore it might be a bit more complex.

    Maybe you should ask someone in the GF forum, if there is a mainclass and if it can be started "by hand".


  3. Great post! Are you missing a step? I see that you set up the Test application and then I see you specifying it in the web.xml of the Tomcat/examples project. Is there a step where you copy the .war?

  4. Thanks Phillipp,

    no, thats the key. There is no need to deploy or redeploy a war at all since all classes are directly loaded from eclipse (and therefore all changes are immediatelly visible). All you have to worry about are resources like JSPs oder XHTML files. You can either use an ant script to copy them into the webapps folder in your tomcat7 project. The other thing you can do is to implement your own resource resolver and keep all your resources near your classes.

    regards andy

    1. Fantastic. I cannot thank you enough for posting this.

  5. Thanks Andreas. I followed all the steps of setup and was able to see "Hello World" output. How do I go further and debug the Tomcat by putting breakpoints in the source? could you explain more with an example, or give me a link of how to do the debug?