Here is a quick summary of basic use; see the next sections for details on these core features.

1. Install Java. Download from http://java.sun.com/javase/downloads/. I use JDK 1.6.0_21, but any Java 5 or 6 version will work. You need the full JDK (with compiler), not just the JRE (for running existing apps). Again, please note that if you use 1.6.0_21, you also need to fix the Eclipse PermGen bug or Eclipse will run out of memory and crash. That is the only Java version where you have this problem.
2. Unzip Tomcat. Unzip tomcat-6.0.28-preconfigured.zip into the location of your choice. I use the top level of the C drive, which results in C:\apache-tomcat-6.0.28. Alternatively, you can download any Tomcat 6 version from the Tomcat Web site and then copy context.xml, server.xml, and web.xml into install_dir/conf. These files are annotated with comments on what was done to them.
3. Install and start Eclipse. Download from http://www.eclipse.org/downloads/. Choose "Eclipse IDE for Java EE Developers", download, and unzip. I use Eclipse 3.6 (Helios), but these directions apply equally to 3.5 (Galileo) and 3.4 (Ganymede). Double click on eclipse.exe in the eclipse folder, then click on "Workbench".
4. Tell Eclipse about Tomcat. Click on Servers tab at bottom. R-click, New, Server, Apache, Tomcat v6.0, navigate to Tomcat installation folder (e.g., C:\apache-tomcat-6.0.28), OK.
5. Run Tomcat. Click on Servers tab at bottom. R-click on Tomcat v6.0, choose "Start". Open http://localhost/ in a browser: you should see an empty page showing a blank directory listing (but not a 404 error). The details below show how to copy the ROOT files that Eclipse erroneously forgets, so that http://localhost/ gives the normal Tomcat welcome page.
6. Import and test a sample Web App. Grab intro.zip, save it, and import it into Eclipse. Use File, Import, General, Existing Projects, Select archive file. Then click Browse and navigate to intro.zip. Click on Servers tab at bottom. R-click on Tomcat v6.0 Server, choose "Add and Remove Projects". Choose intro project. Start Tomcat, or restart if already running. Open http://localhost/intro/ in browser. Note that there are many other sample Eclipse projects to illustrate various servlet and JSP capabilities (session tracking, JSP scripting, MVC, custom tags, and dozens of other topics). You can download them from the servlet and JSP tutorial page. This intro project is merely to confirm that Tomcat and Eclipse are configured properly.
7. Create and test a new Web App. File, New, Project, Web, Dynamic Web Project. Copy HTML, JSP, and servlet files from the intro project into this new project. Deploy and test it as above.
8. Tweak Eclipse preferences. Window, Preferences, then many options re font sizes, import and indentation styles, and so forth. At a minimum, suppress unnecessary warnings about Serializable classes. Window, Preferences, Java, Compiler, Errors/Warnings, change "Serializable class without ..." to "Ignore".
9. Bookmark the servlet & JSP javadocs. Add the servlet 2.5 API and the JSP 2.1 API to your bookmarks/favorites list.
10. Learn details of servlet and JSP programming. If you got through the previous steps, Eclipse and Tomcat are all set up, and you are ready to start the fun part: learning JSP and servlet development! See these servlet and JSP programming tutorials.

For information on commercial Web hosting providers that support Tomcat, see the JSP hosting page.

Unzip tomcat-6.0.28-preconfigured.zip into the location of your choice. I use the top level of the C drive, resulting in C:\apache-tomcat-6.0.28\. This preconfigured version of Tomcat has the following settings already in place. For details on customizing this configuration, please see the detailed configuration guide.

• The port is changed from 8080 to 80. This lets you enter URLs of the form http://localhost/... instead of http://localhost:8080/....
  • When you download Tomcat from the Apache site, the port is 8080 in case you already have another server running on port 80.
• The invoker servlet is enabled. This lets run servlets with a URL of the form http://localhost/appName/servlet/packageName.ServletName. That is, the invoker servlet saves you from editing web.xml to give a servlet-mapping to your servlet.
  • When you download Tomcat from the Apache site, the invoker servlet is disabled. You definitely want the invoker servlet disabled on a server used for a deployed application, but having it enabled on your development server is very convenient for practice and testing.
• Tomcat monitors struts-config.xml and faces-config.xml. Whenever either of these files changes, Tomcat reloads the Web application. This saves you from restarting the server when you change these files.
  • If you do not use Struts or JSF, this change will not be beneficial to you. But it does not hurt either way.
• Directory listings are turned on. If you type a URL ending in / and there is no welcome file, Tomcat shows a directory listing.
  • Directory listings were on by default in previous Tomcat versions, but are off in the current version. They are convenient during development so you can just click on files, but most developers disable them for deployed applications.

Alternatively, you can download any Tomcat 6 version from the Tomcat Web site and then copy context.xml, server.xml, and web.xml into install_dir/conf. These files are annotated with comments on what was done to them.

Go to http://www.eclipse.org/downloads/. Choose "Eclipse IDE for Java EE Developers", download, and unzip. There is no real installer, so unzipping it is all you need to do. I normally unzip into the top level of the C drive, resulting in C:\eclipse, but any location is fine.

Start Eclipse by going to the "bin" folder and double-clicking on eclipse.exe. I usually make a shortcut on the desktop by R-clicking on eclipse.exe, selecting Copy, then going to the desktop, R-clicking, and doing Paste Shortcut.

After you start Eclipse, select "Workbench" as shown on the images to the right. I use Eclipse 3.6 (Helios), which is the latest Eclipse version as of July 2010. But, these directions apply equally to 3.5 (Galileo) and 3.4 (Ganymede).

First, start Eclipse and go to the Workbench as shown in the previous section. Then, click on Servers tab at bottom. R-click, New, Server, Apache, Tomcat v6.0, navigate to folder, OK. You should now see "Tomcat v6.0 Server at localhost" listed under the Servers tab at the bottom.

Click on Servers tab at bottom. R-click on Tomcat v6.0, choose "Start". Open http://localhost/ in a browser: you should see an empty page showing a blank directory listing (but not a 404 error). Eclipse incorrectly fails to copy the welcome pages when it sets up Tomcat, so if you want the friendlier welcome page, go to your-eclipse-workspace\.metadata and search for "ROOT". Copy all of the files from C:\apache-tomcat-6.0.28\webapps\ROOT into the ROOT folder inside your-eclipse-workspace\.metadata\...\ROOT.

If you fail to copy the ROOT files as mentioned above, http://localhost/ will result in an empty directory listing. It is often mistaken for an error page, but if you look closely you will see that it says "directory listing for /" and is not an error at all. However, if you copy the ROOT files, http://localhost/ will give the nice friendly "Welcome to Tomcat" page.

Grab intro.zip and save it. Import it into Eclipse with File, Import, General, Existing Projects, Select archive file. Then click Browse and navigate to intro.zip.


Click on Servers tab at bottom. R-click on Tomcat v6.0 Server, choose "Add and Remove Projects". Choose intro app. Start Tomcat, or restart it if already running (R-click on Tomcat and choose either "Start" or "Restart"). Try the following URLs in a browser:

• http://localhost/intro/ Directory listing showing Hello.html and Hello.jsp.
• http://localhost/intro/Hello.html Be sure to use an uppercase "H" in "Hello".
• http://localhost/intro/Hello.jsp Be sure to use an uppercase "H" in "Hello".
• http://localhost/intro/servlet/HelloServlet HelloServlet via invoker servlet.
• http://localhost/intro/hi HelloServlet via servlet mapping in web.xml.
• http://localhost/intro/servlet/coreservlets.HelloServlet2 HelloServlet2 via invoker servlet.
• http://localhost/intro/hi2 HelloServlet2 via servlet mapping in web.xml.
• http://localhost/intro/servlet/coreservlets.HelloServlet3 HelloServlet3 via invoker servlet.
• http://localhost/intro/hi3 HelloServlet3 via servlet mapping in web.xml.

Follow same procedure as given in example above with "intro" app: Click on Servers tab at bottom. R-click on Tomcat v6.0 Server, choose "Add and Remove Projects". Choose app. Start Tomcat, or restart if already running. Open http://localhost/appName/ in browser. You must restart the server after adding a new project. To do so, R-click server and choose "Restart".

For details on writing servlets, giving them custom URLs, using JSP, applying the MVC architecture, creating JSP custom tag libraries, and many other servlet and JSP topics, please see the servlet and JSP programming tutorial.

There are many customizations you can do in Eclipse. You can adjust the font size, colors, indentation styles, import statement formats, and much much more. Go to Window, Preferences and browse around.

One customization you almost always want to do is to suppress the unneeded warning re serialVersionUID on Serializable classes. The HttpServlet class is already Serializable, but nobody actually sends instances across the network or writes them to disk, and certainly almost nobody puts in a serialVersionUID field in servlets. But, if Eclipse marks every servlet with a warning, you get in the very bad habit of ignoring warnings. Most of the warnings are actually useful; this is a rare exception. So, go to Window, Preferences, Java, Compiler, Errors/Warnings, expand "Potential programming problems", and change "Serializable class without serialVersionUID" to "Ignore".

The single most useful reference for a servlet and JSP developer is the online API. So, you should add the servlet 2.5 API and the JSP 2.1 API to your bookmarks/favorites list. And, if you haven't already done so long ago, bookmark the Java SE 6 API.