Tomcat and Eclipse Notes

The easist way to debug a web application that runs on Tomcat is to run the application in Eclipse over Tomcat. You download and associate Tomcat with Eclipse and run your application from within the workbench. (Unless you specifically know what version of Tomcat you want to use, I'd suggest 6.)


How to install a private copy of Tomcat...

First, download Tomcat from http://tomcat/apache.org. Unless you know you want to use Tomcat 7, the best choice is Tomcat 6.

  1. Click the version you like to reach its download page.
  2. Scroll down until you find the download appropriate for your computer, under "Core." This would be a tarball (tar.gz) if you're downloading for Linux or Macintosh, or a zip file for Windows of which there are a number of separate options including 32-bit, 64-bit, Itanium, for Windows service, etc. Since you really want a private one of these for use only with Eclipse, just use the 32- or 64-bit appropriate to your host.
  3. If downloading to Linux, you need only explode the tarball in the subdirectory where you want it to be. I put mine on the path /home/russ/dev/downloads/apache-tomcat-6.0.32.

    If downloading to Windows, you need only extract the contents which produces a subdirectory you can copy to where you would like to consume it from in Eclipse. I copy mine to C:\Users\russ\dev\downloads\apache-tomcat-6.0.32.

  4. While not super-relevant to this discussion, you need to be aware of another package option, "Deployer," which is not what you want now. However, it's a tiny download and, once extracted, you should read deployer-howto.html for information on what this is.

      5. If you've accomplished this installation correctly, you're now ready to associate your private copy of Tomcat with Eclipse.


How to associate Tomcat with Eclipse

In order to do this, you must have downloaded and exploded Eclipse IDE for Java EE Developers or used Help -> Install New Software to install the Eclipse Web Tools platform plug-ins. The plug-ins are known collectively as "Eclipse IDE for Java EE Developers" just as is the download.

The first way is very much easier.

  1. Choose Window menu, then Preferences -> Server -> Runtime Environment.
  2. Choose the version of Tomcat you're going to use (that you've already downloaded); Eclipse gives you a wide range of choices.
  3. Click Add..., then navigate to where you downloaded and exploded Tomcat. This makes Tomcat available to Eclipse. You consume it there by adding a Server "project" to your workspace. You do this because your project contains a servlet, JSP, etc. and you want to run one or more of your workspace projects as a server.
  4. Right-click in the Project/Package Explorer view, choose New.
  5. Click Server -> Server.
  6. Click Next.
  7. Click Apache -> Tomcat v6.0 Server. (You can also install Tomcat 7.)
  8. Click Next.
  9. Add your project to the Configured pane.
  10. Click Finish.

At this point, you're ready to create a Tomcat server in Eclipse for running your web application.


How to create a Tomcat server in Eclipse

Once Tomcat is associated with Eclipse, create a new Server:

  1. File -> New -> Other.
  2. Scroll down to Server and choose Server, click Next.
  3. Choose the version of Tomcat you associated with Eclipse. click Next.
  4. Double-click your application to move it from the left pane to the right pane, click Finish.

At this point, you should have

If you already have Tomcat running on your development host, you may need to change the port number on which Tomcat runs inside Eclipse. See here.


How to run Tomcat in Eclipse

Assuming your web application is already set up in Eclipse...

Right-click the server, probably "Tomcat v6.0 Server at localhost", in the Servers view. This will involve

  1. Eclipse publishing your application (as if it were a WAR) to /.metadata/.plugins/org.eclipse.wst.server.core/tmp0/wtpwebapps just as if this subdirectory were tomcat/webapps where the WAR file is usually dropped.
  2. running the application using your application's web.xml as a guide; if this is wrong, there will be trouble.

Once up and running, you can set breakpoints where you think execution will wander and stop.

To get things going, you typically use a client application or a browser to hit your applicaion via the URL, probably http://localhost:8080//etc..


How to change the port on which Tomcat runs

If port 8080 is already in use, you get an error when you launch Tomcat, go back to the Servers view, double-click the Tomcat server which will bring up a configuration page. Change the port to something else like 8000 and save, relaunch the server, retry your application with the new port number.


catalina.out and other log files when run under Eclipse

In the Servers view, double-click the server to run (not while it's running), click Open launch configuration, click the Common tab, then File:. Navigate to (Workspace, File System, etc.) where you'd like the files to drop, e.g.: the root of your project, something like: ${workspace_loc:/myapp} if your application's project folder is named myapp.

What does this do?

Maybe not what you want. For one thing, your logging to the console will disappear. However, catalina.out will magically show up there, and any other log file you've used log4j.properties to create.

Where did this stuff live before?

Likely these files lived under the logs subdirectory of wherever you told Eclipse your Tomcat was. My path was /home/russ/dev/apache-tomcat-6.0.37/logs/catalina.out.

Or, likelier still, you'll find log files on the path /home/username/path-to-workspace/.metadata/.plugins/org.eclipse.wst.server.core/tmp0/logs.

This said, I only saw this work once. Thereafter, it returned to the original location(s) described just above and stopped work at project root. This mechanism is squirrely and to be avoided. Just look in the tried and true place.

To facilitate what does work, I created handy symbolic links at the root of the project.


Tomcat server-state in Eclipse

Here is an article on how to fix a server-state issue in Eclipse. The following link shows how to enable/disable the server state and status in Eclipse:

Showing the state and status in the Servers view

The Server State Decorator was enabled, but I disabled it and then enabled it again. Now it is showing up again. I don’t recall what I did that made it disappear in the first place though.