from locating jaxp.properties JBuilder, for instance, installs its own version of Java 2 that it uses by default.
Chapter 6. Servlet Basics and XSLT
6.2 WAR Files and Deployment
In the servlet model, Web Application Archive (WAR) files are the unit of deployment. WAR files enable portability across a wide range of servlet containers regardless of the vendor. The good news is that WAR files are very easy to create and require only that you carefully follow the guidelines for file and directory names. If you are careful to avoid spelling errors and misplaced files, you should not have any problem with WAR files.
6.2.1 WAR Files
Figure 6-2 shows the standard structure of a WAR file. Since a WAR file is really just a JAR file with a .war extension, you can utilize the jar command to create your WAR files.
Figure 6-2. WAR file structure
To create a WAR file, simply arrange your files into the directory structure shown in Figure 6-2 and issue the following command from the directory that contains index.html:[1]
[1]
index.html is the "home page" for a web application.
jar -cvfM ../appname.war
This command assumes that the WAR file will be placed in the parent of your current working directory; the forward slash (/ ) works on Windows as well as Unix clients. Once the WAR file has been created, you can view its contents by changing to its directory and issuing the following command:
jar -tvf appname.war .
This shows the table of contents for the WAR file, which must match the structure shown in Figure 6-2.
The topmost directory in the WAR file is publicly accessible to web browsers and should contain your JSP and HTML files. You can also create subdirectories, which will also be visible to the client. A common practice is to create an images directory for storing your graphic files. The WEB-INF directory is always hidden from clients that access your web application. The deployment descriptor, web.xml, is located here, as are the classes and lib directories. As Figure 6-2 indicates, the classes directory becomes available to your application's ClassLoader. Any JAR files contained in the lib directory are also available to your code, making it very easy to deploy third-party libraries along with a web application. The folder other_directories can be anything you want and will also be hidden from clients since it resides under the WEB-INF directory. Although clients cannot see any of these directories and files directly, your servlet can access these resources programmatically and then deliver that content.
6.2.2 Deployment Descriptor
The deployment descriptor is always called web.xml and must be placed directly in the WEB-INF directory of your web application. The job of the deployment descriptor is to provide the servlet container with complete configuration information about a web application. This may include security attributes, aliases for servlets and other resources, initialization parameters, and even graphical icons for Integrated Development Environments (IDEs) to utilize. For our needs, a very small subset of this functionality will be sufficient. For SplashScreenServlet, we need to list the Java class of the servlet, an alias for that servlet, and a URL mapping. The complete deployment descriptor for SplashScreenServlet is listed in Example 6-2.
Example 6-2. web.xml for SplashScreenServlet.java
<?xml version="1.0" encoding="UTF -8"?> <!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" "http://java.sun.com/j2ee/dtds/web -app_2.2.dtd">
<web-app> <servlet>
<!-- define an alias for the Servlet --> <servlet-name>splashScreen</servlet-name>
<servlet-class>chap6.SplashScreenServlet</servlet -class> </servlet>
<servlet-mapping>
<!-- associate the Servlet with a URL pattern --> <servlet-name>splashScreen</servlet-name>
<url-pattern>/splash/*</url-pattern> </servlet-mapping>
</web-app>
The DOCTYPE is a required element of a deployment descriptor and must match what is shown in Example 6-2. The only caveat is that newer versions of the servlet specification, such as Version 2.3, use a different version number in the deployment descriptor. Unless you are using 2.3 features, however, you should stick with 2.2 to remain compatible with as many servlet containers as possible.
A servlet definition lists the fully qualified package and class name of the servlet class, as well a name for that servlet. Whenever another section in the deployment descriptor wishes to reference this particular servlet, it uses the name specified here:
<servlet>
<servlet-name>splashScreen</servlet-name>
<servlet-class>chap6.SplashScreenServlet</servlet -class> </servlet>
As you can see in Example 6-2, the servlet mapping uses this name in order to associate a URL pattern with this particular servlet. This pattern will show up in the address that users type into their web browsers when they access this servlet. In this case, the URL to
SplashScreenServlet is: http://hostname:port/chap6/splash
This is the form that Tomcat defaults to, having the following components:
hostname:port
Typically localhost:8080, although Tomcat can be configured to run on any port number
chap6
The name of your web application, which is deployed in chap6.war for this example
splash
Part of the URL pattern for the servlet
Wildcards in the URL pattern indicate that any text will match. Since the deployment descriptor listed /splash/* as the pattern, any of the following URLs also invoke
SplashScreenServlet:
• http://localhost:8080/chap6/splash/
• http://localhost:8080/chap6/splash/whatever.html
• http://localhost:8080/chap6/splash/a/b/c
6.2.3 Deploying SplashScreenServlet to Tomcat
The simple steps for getting SplashScreenServlet up and running are to compile the code, create the deployment descriptor listed in Example 6-2, and create the WAR file using the jar utility. The WAR file contents for this servlet are shown in Figure 6-3.
Figure 6-3. SplashScreenServlet WAR file
Once you have created chap6.war, be sure to execute jar -tvf chap6.war to confirm that the contents are structured properly. The final step is to simply copy the entire JAR file to Tomcat's webapps directory.