table of contents
close
 Top

table of contents

• Executive Summary
• Details
• More Information

Deploying Custom Web Apps in Tomcat

For Developers Not Using an IDE


This section is for developers that are manually editing and deploying. If you use an IDE, it will handle Web app creation and deployment for you. I strongly recommend you use an IDE from the beginning: for details, see the sections on using Tomcat with Eclipse and using Tomcat with MyEclipse.

For learning and practicing servlet and JSP techniques, it is simplest to use Tomcat's default Web application (ROOT) and to use the "invoker servlet" that lets you run servlets by putting /servlet/ServletName at the end of the URL. When you start developing your real project, however, you almost always use custom Web applications (and never use the invoker servlet). This section gives a quick summary on the use of Web applications in Tomcat. For more details, see the Web application sections of the JSP and servlet tutorials page.

Learning Deployment

  • Use default Web application (ROOT on Tomcat)
  • Use default URLs (http:///servlet/ServletName)
  • Advantages
    • Simpler. Just drop the servlet in the right location and test immediately. This is far easier than editing web.xml every time you create a new servlet.
    • Can test without restarting server or editing web.xml (although Tomcat 6.0 usually notices when web.xml has been modified, and reloads the Web app automatically when it has)
  • Use a custom Web application (on Tomcat, a directory in install_dir/webapps with structure similar to ROOT)
  • Register custom URLs in WEB-INF/web.xml
  • Advantages
    • URLs look better. No class names in the URLs.
    • Advanced features (init params, security, filters, etc.) depend on your using registered URLs. The invoker servlet is just a convenience for initial testing; never use it for real applications!

Executive Summary

Using custom Web apps involves the following steps:

  1. Making a directory whose structure mirrors the structure of the default Web application. Web content goes in the top-level directory or any subdirectory other than WEB-INF. web.xml goes in WEB-INF. Java code goes in WEB-INF/classes/subdirectory-matching-package-name.
  2. Updating your CLASSPATH. It should include the WEB-INF/classes folder of your new app.
  3. Using the directory name in the URL. URLs are of the form http://hostname/webappName/blah.
  4. Using web.xml to assign custom URLs. Use the servlet and servlet tags.

Details

1. Make a directory whose structure mirrors the structure of the default Web application.

  • HTML, JSP, images, style sheets, and other regular Web content goes in the top-level directory (or any subdirectory other than WEB-INF or META-INF).
  • The web.xml file goes in the WEB-INF subdirectory
  • Servlets and other classes go either in WEB-INF/classes (unpackaged servlets) or a subdirectory of WEB-INF/classes that matches the package name.
  • On Tomcat, entire directory is deployed in install_dir/webapps. One of the simplest approaches is to create the Web app in your development directory (e.g., C:\Servlets+JSP), then copy the entire directory to install_dir/webapps whenever you want to test it. Simplify the process by keeping a shortcut to install_dir/webapps in C:\Servlets+JSP.

Note that you can also deploy using WAR files instead of regular directories. A WAR file is just a JAR file (which is just a ZIP file) with a .war extension. You can create WAR files using jar, WinZip, or the Windows XP "Create Compressed Folder" R-Mouse option. If you use WAR files, a directory such as myWebApp should become myWebApp.war, and the top-level directory within the WAR file should be WEB-INF (i.e., do not repeat myWebApp within the WAR file).

2. Update your CLASSPATH

If your Web application directory is myWebApp, your CLASSPATH should include mainDevelDir/myWebApp/WEB-INF/classes. A convenient trick is to include .. and ../.. in your CLASSPATH so that you never need to update your CLASSPATH as long as you stick with singly and doubly nested packages. The CLASSPATH setting in the preconfigured Tomcat version uses this trick.

3. Use the directory name in the URL

All URLs should be of the form http://hostname/myWebApp/... . For example, if Hello.html is in the top-level directory of the Web app and you are running on your desktop system, once the Web app is deployed (copied to tomcat_dir/webapps), the file would be accessed with http://localhost/myWebApp/Hello.html. In general, you use the same URLs as for the default Web app (ROOT) except that you insert /myWebApp right after the hostname.

4. Use web.xml to assign custom URLs

First, you use servlet and servlet-mapping elements to give the servlet an address relative to the Web application, as below: (note that the servlet-name is arbitrary, but you have to use the same name in both the servlet and servlet-mapping entries)

	<?xml version="1.0" encoding="ISO-8859-1"?>
	<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
		version="2.4">
	  <servlet>
		<servlet-name>Servlet2</servlet-name>
		<servlet-class>coreservlets.HelloServlet2</servlet-class>
	  </servlet>
	  <servlet-mapping>
		<servlet-name>Servlet2</servlet-name>
		<url-pattern>/servlet2</url-pattern>
	  </servlet-mapping>
	</web-app>

If you deployed HelloServlet2 in the myWebApp application using the invoker servlet, it would go in .../myWebApp/WEB-INF/classes/coreservlets and be invoked with the URL http://localhost/myWebApp/servlet/coreservlets.HelloServlet2. If you used a registered URL of servlet2 as above, the class file would still go in .../myWebApp/WEB-INF/classes/coreservlets, but it would be invoked with the URL http://localhost/myWebApp/servlet2



More Information

Online documentation