2.11 Web Applications: A Preview

Up to this point, we've been using the server's default Web application for our servlets. Most servers come preinstalled with a default Web application, and most servers let you invoke servlets in that application with URLs of the form http:// host /servlet/ ServletName or http:// host /servlet/ packageName.ServletName . Use of the default Web application and URL is very convenient when you are learning how to use servlets; you probably want to stick with these defaults when you first practice the techniques described throughout the book. So, if you are new to servlet and JSP development, skip this section for now.

However, once you have learned the basics of both servlets and JSP and are ready to start on real applications, you'll want to use your own Web application instead of the default one. Web applications are discussed in great detail in Volume 2 of this book, but a quick preview of the basics is presented in this section.

Core Approach

When first learning, use the default Web application and default servlet URLs. For serious applications, use custom Web applications and URLs that are assigned in the deployment descriptor ( web.xml ).

Most servers (including the three used as examples in this book) have server-specific administration consoles that let you create and register Web applications from within a Web browser. These consoles are discussed in Volume 2; for now, we restrict ourselves to the basic manual approach that is nearly identical on all servers. The following list summarizes the steps; the subsections that follow the steps give details.

1. Make a directory whose structure mirrors the structure of the default Web application. HTML (and, eventually, JSP) documents go in the top-level directory, the web.xml file goes in the WEB-INF subdirectory, and servlets and other classes go either in WEB-INF/classes or in a subdirectory of WEB-INF/classes that matches the package name .

2. Update your CLASSPATH . Add webAppDir/WEB-INF/classes to it.

3. Register the Web application with the server. Tell the server where the Web application directory (or JAR file created from it) is located and what prefix in the URL (see the next item) should be used to invoke the application. For example, with Tomcat, just drop the Web application directory in install_dir /webapps and then restart the server. The name of the directory becomes the Web application prefix.

4. Use the designated URL prefix to invoke servlets or HTML/JSP pages from the Web application. Invoke unpackaged servlets with a default URL of http:// host/ webAppPrefix /servlet/ ServletName , packaged servlets with http:// host/ webAppPrefix /servlet/ packageName.ServletName , and HTML pages from the top-level Web application directory with http:// host/ webAppPrefix /filename. html .

5. Assign custom URLs for all your servlets. Use the servlet and servlet-mapping elements of web.xml to give a URL of the form http:// host/webAppPrefix/someName to each servlet.

Making a Web Application Directory

To make a Web application, create a directory in your development folder. That new directory should have the same general layout as the default Web application:

• HTML and, eventually, JSP documents go in the top-level directory (or any subdirectory other than WEB-INF ).

• The web.xml file (sometimes called "the deployment descriptor") goes in the WEB-INF subdirectory.

• Servlets and other classes go either in WEB-INF/classes or, more commonly, in a subdirectory of WEB-INF/classes that matches the package name.

The easiest way to make such a directory is to copy an existing Web application. For instance, with Tomcat, you could copy the ROOT directory to your development folder and rename it to testApp , resulting in something like C:\Servlets+JSP\testApp . As with the default Web application, we strongly advise against developing directly in the server's Web application directory. Keep a separate directory, and deploy it whenever you are ready to test. The easiest deployment option is to simply copy the directory to the server's standard location, but Section 2.9 (Establish a Simplified Deployment Method) gives several other alternatives.

Updating Your CLASSPATH

Recall from Section 2.7 (Set Up Your Development Environment) that your CLASSPATH needs to contain the top-level directory of .class files. This is true whether or not you are using custom Web applications, so add webAppDir/classes to the CLASSPATH .

Registering the Web Application with the Server

In this step, you tell the server where the Web application directory (or JAR file created from it) is located and what prefix in the URL (see the next subsection) should be used to invoke the application. There are various server-specific mechanisms for doing this registration, many of which involve the use of an interactive administration console. But, on most servers, you can also register a Web application simply by dropping the Web application directory in a standard location and then restarting the server. In such a case, the name of the Web application directory is used as the URL prefix. Here are the standard locations for Web application directories with the three servers used throughout the book.

• Tomcat Web application autodeploy directory.

    install_dir  /webapps 

• JRun Web application autodeploy directory.

    install_dir  /servers/default 

• Resin Web application autodeploy directory.

    install_dir  /webapps 

For example, we created a directory called testApp with the following structure:

• testApp/Hello.html

  The sample HTML file of Section 2.8 (Listing 2.1).

• testApp/Hello.jsp

  The sample JSP file of Section 2.8 (Listing 2.2).

• testApp/WEB-INF/classes/HelloServlet.class

  The sample packageless servlet of Section 2.8 (Listing 2.3).

• testApp/WEB-INF/classes/coreservlets/HelloServlet2.class

  The first sample packaged servlet of Section 2.8 (Listing 2.4).

• testApp/WEB-INF/classes/coreservlets/HelloServlet3.class

  The second sample packaged servlet of Section 2.8 (Listing 2.5).

• testApp/WEB-INF/classes/coreservlets/ServletUtilities.class

  The utility class (Listing 2.6) used by HelloServlet3 .

WAR Files

Web ARchive (WAR) files provide a convenient way of bundling Web applications in a single file. Having a single large file instead of many small files makes it easier to transfer the Web application from server to server.

A WAR file is really just a JAR file with a .war extension, and you use the normal jar command to create it. For example, to bundle the entire testApp Web app into a WAR file named testApp2.war , you would just change directory to the testApp directory and execute the following command.

 jar cvf testApp2.war * 

There are a few options you can use in advanced applications (we discuss these in Volume 2 of the book), but for simple WAR files, that's it!

Again, the exact details of deployment are server dependent, but most servers let you simply drop a WAR file in the autodeploy directory, and the base name of the WAR file becomes the Web application prefix. For example, you would drop testApp2.war into the same directory you dropped testApp , restart the server, then invoke the test resources shown in Figures 2-16 through 2-20 by merely changing testApp to testApp2 in the URLs.

Figure 2-16. Hello.html invoked within a Web application.

Figure 2-20. HelloServlet3.class invoked with the default URL within a Web application.

Figure 2-17. Hello.jsp invoked within a Web application.

Figure 2-18. HelloServlet.class invoked with the default URL within a Web application.

Figure 2-19. HelloServlet2.class invoked with the default URL within a Web application.

Using the URL Prefix

When you use Web applications, a special prefix is part of all URLs. For example:

• Unpackaged servlets are invoked with a default URL of http:// host/ webAppPrefix /servlet/ ServletName

• Packaged servlets are invoked with http:// host/ webAppPrefix /servlet/ packageName.ServletName

• Registered servlets (see the next subsection) are invoked with http:// host/ webAppPrefix /customName

• HTML pages from the top-level Web application directory are invoked with http:// host/ webAppPrefix /filename. html .

• HTML pages from subdirectories are invoked with http:// host/ webAppPrefix /subdirectoryName/filename. html .

• JSP pages are placed in the same locations as HTML pages and invoked in the same way (except that the file extension is .jsp instead of .html ).

Most servers let you choose arbitrary prefixes, but, by default, the name of the directory (or the base name of the WAR file) becomes the Web application prefix. For example, we copied the testApp directory to the appropriate Web application directory ( install_dir /webapps for Tomcat and Resin, install_dir /servers/default for JRun) and restarted the server. Then, we invoked the resources by using URLs identical to those of Section 2.8 except for the addition of testApp after the hostname. See Figures 2-16 through 2-20.

Assigning Custom URLs to Your Servlets

During initial development, it is very convenient to drop a servlet in WEB-INF/classes and immediately invoke it with http:// host/webAppPrefix /servlet/ ServletName . For deploying serious applications, however, you always want to define custom URLs.

You assign the URLs by using the servlet and servlet-mapping elements of web.xml (the deployment descriptor). The web.xml file is discussed in great detail in Volume 2 of the book, but for the purpose of registering custom URLs, you simply need to know five things:

• The file location. It always goes in WEB-INF .

• The base form. It starts with an XML header and a DOCTYPE declaration, and it contains a web-app element.

• The way to give names to servlets. You use servlet with servlet-name and servlet-class subelements.

• The way to give URLs to named servlets. You use servlet-mapping with servlet-name and url-pattern subelements.

• When the web.xml file is read. It is read only when the server starts.

Locating the Deployment Descriptor

The web.xml file always goes in the WEB-INF directory of your Web application. That is the only portable location; other locations (e.g., install_dir /conf for Tomcat) are nonstandard server extensions that you should steer clear of.

Defining the Base Format

A web.xml file that is compatible with both servlets 2.3 (JSP 1.2) and servlets 2.4 (JSP 2.0) has the following basic form:

 <?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE web-app   PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"   "http://java.sun.com/dtd/web-app_2_3.dtd"> <web-app> </web-app> 

Deployment descriptors that are specific to servlets 2.4 (JSP 2.0) are discussed in Volume 2 of the book.

Naming Servlets

To name a servlet, you use the servlet element within web-app , with servlet-name (any name) and servlet-class (the fully qualified class name) subelements. For example, to give the name Servlet2 to HelloServlet2 , you would use the following.

 <servlet>   <servlet-name>Servlet2</servlet-name>   <servlet-class>coreservlets.HelloServlet2</servlet-class> </servlet> 

Giving URLs

To give a URL to a named servlet, you use the servlet-mapping element, with servlet-name (the previously assigned name) and url-pattern (the URL suffix, starting with a slash) subelements. For example, to give the URL http:// host/webAppPrefix /servlet2 to the servlet named Servlet2 , you would use the following.

 <servlet-mapping>   <servlet-name>Servlet2</servlet-name>   <url-pattern>/servlet2</url-pattern> </servlet-mapping> 

Note that all the servlet elements must come before any of the servlet-mapping elements: you cannot intermingle them.

Reading the Deployment Descriptor

Many servers have "hot deploy" capabilities or methods to interactively restart Web applications. For example, JRun automatically restarts Web applications whose web.xml files have changed. By default, however, the web.xml file is read only when the server starts. So, unless you make use of a server-specific feature, you have to restart the server every time you modify the web.xml file.

Example

Listing 2.7 gives the full web.xml file for the testApp Web application. The file was placed in the WEB-INF directory of testApp , the testApp directory was copied to the server's Web application directory (e.g., install_dir /webapps for Tomcat and Resin, install_dir /servers/default for JRun), and the server was restarted. Figures 2-21 through 2-23 show the three sample servlets invoked with the registered URLs.

Listing 2.7 WEB-INF/web.xml

 <?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE web-app    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"    "http://java.sun.com/dtd/web-app_2_3.dtd"> <web-app>   <servlet>     <servlet-name>Servlet1</servlet-name>     <servlet-class>HelloServlet</servlet-class>   </servlet>   <servlet>     <servlet-name>Servlet2</servlet-name>     <servlet-class>coreservlets.HelloServlet2</servlet-class>   </servlet>   <servlet>     <servlet-name>Servlet3</servlet-name>     <servlet-class>coreservlets.HelloServlet3</servlet-class>   </servlet>   <servlet-mapping>     <servlet-name>Servlet1</servlet-name>     <url-pattern>/servlet1</url-pattern>   </servlet-mapping>   <servlet-mapping>     <servlet-name>Servlet2</servlet-name>     <url-pattern>/servlet2</url-pattern>   </servlet-mapping>   <servlet-mapping>     <servlet-name>Servlet3</servlet-name>     <url-pattern>/servlet3</url-pattern>   </servlet-mapping> </web-app> 

Figure 2-21. HelloServlet invoked with a custom URL.

Figure 2-23. HelloServlet3 invoked with a custom URL.

Figure 2-22. HelloServlet2 invoked with a custom URL.