Tomcat provides an implementation of both the servlet and JSP specifications. These specifications are in turn part of Sun's Java Enterprise Edition. Java EE is designed to let application developers move their applications from one compliant application server (a program that implements the Java EE specification) to another, without significant rewriting or revising. To accomplish this, applications are packaged in very specific, portable ways; for example, as web application archives or enterprise application archives.
The Java Servlet Specification defines the Web Application aRchive (WAR) file format and its file structure for this very purpose. For your webapp to be application-server-implementation-independent, your files must follow certain conventions, such as the directory layout for storing web pages, configuration files, and so on. This general layout is shown in Figure 3-2.
As a concrete example, Acme Widgets' site might look like Example 3-1.
Example 3-1. Example web application file layout
/ /index.jsp /products.jsp /widgets/index.html /widgets/pricing.jsp /images/logo.png /WEB-INF/web.xml /WEB-INF/classes/com/acme/PriceServlet.class /WEB-INF/classes/DataHelper.class /WEB-INF/lib/acme-util.jar
As you can see, the web pages (whether static HTML, dynamic JSP, or another dynamic templating language's content) can go in the root of a web application directory or in almost any subdirectory that you like, except the WEB-INF or META-INF directory trees. Images often go in a /images subdirectory, though this is a convention, not a requirement. The WEB-INF directory has several specific pieces of content. First, the classes directory is where you place any Java class files that are not in a JAR file, whether they are servlets or other class files used by a servlet, JSP, or other part of your webapp's code. Second, the lib directory is where you put any JAR files containing packages of classes. And finally, the web.xml file is known as a deployment descriptor, which contains configuration for the web application, a description of the webapp, and any additional customization.
One of the nice things about the notion of putting per-site customizations into an XML file (the deployment descriptor) in a site's directory, compared with the way other web servers tend to do things, is that the customizations for each site are stored with that site's deployment. This makes it easier for maintenance and also makes it easy to package up the files from one site to move them to another server or even to a different ISP. Additionally, the contents of the WEB-INF and META-INF directories are automatically protected from access by client web browsers, so this configuration information (which may contain account names and passwords) is safe from client view.
You can configure the URI to which a servlet is mapped by providing a servlet-mapping element in the
WEB-INF/web.xml file, for example. Listing the servlet in the
descriptor is required if you want to provide an alternate mapping, pass any
initialization parameters to the servlet, specify loading order on startup, and so on. The
servlet element is an XML tag that appears near the
start of web.xml and is used for all of these tasks. Chapter 7 details all of the options available to servlets at deployment
time.
Here is an example of a servlet with most of its allowed subelements:
<servlet>
<icon>
<small-icon>/images/tomcat_tdg16x16.jpg</small-icon>
</icon>
<servlet-name>InitParams</servlet-name>
<display-name>InitParams Demo Servlet</display-name>
<description>
A servlet that shows use of both servlet- and
webapp-speicific init-params
</description>
<servlet-class>InitParams</servlet-class>
<init-param>
<param-name>myParm</param-name>
<param-value>
A param for the Servlet:
Forescore and seven years ago...
</param-value>
</init-param>
<load-on-startup>25</load-on-startup>
</servlet>You may also want to add JSPs to your webapp. JSPs can be installed anywhere in a web application (except under WEB-INF; this folder is protected against access from the web because it may contain initialization parameters, such as database connections, names, and passwords). JSPs can simply be copied to the root of your web application or placed in any subdirectory other than WEB-INF. The same goes for any static content, such as HTML files, data files, and image files.