The primary purpose of an HTTP get request is to retrieve the content of a specified URLnormally an HTML or XHTML document. The servlet in Fig. 26.7 and the XHTML document in Fig. 26.8 demonstrate a servlet that handles HTTP get requests. When the user clicks the Get HTML Document button (Fig. 26.8), a get request is sent to the servlet WelcomeServlet (Fig. 26.7). The servlet responds to the request by dynamically generating an XHTML document for the client that displays "Welcome to Servlets!". Figure 26.7 shows the WelcomeServlet source code. Figure 26.8 shows the XHTML document the client loads to access the servlet and shows screen captures of the client's browser window before and after the servlet interaction. [ Note: Section 26.3 discusses how to set up and configure Tomcat to execute this example.]

Figure 26.7. WelcomeServlet that responds to a simple HTTP get request.

(This item is displayed on page 1248 in the print version)

""A Simple Servlet Example

Figure 26.8. HTML document in which the form's action invokes WelcomeServlet tHRough the alias welcome1 specified in web.xml.

(This item is displayed on page 1250 in the print version)

"http://www.w3.org/1999/xhtml"> 8 9

Lines 36 import various classes in the javax.servlet and javax.servlet.http packages. We use several data types from these packages in the example. Package javax.servlet.http provides superclass HttpServlet for servlets that handle HTTP get requests and HTTP post requests. This class implements interface javax.servlet.Servlet and adds methods that support HTTP protocol requests. Class WelcomeServlet extends HttpServlet (line 10) for this reason.

Superclass HttpServlet provides method doGet to respond to get requests. Its default functionality is to indicate a "Method not supported" error. Typically, this error is indicated in Internet Explorer and in Netscape with a Web page that states "HTTP status 405." Lines 1344 override method doGet to provide custom get request processing. Method doGet accepts two argumentsan HttpServletRequest object and an HttpServletResponse object (both from package javax.servlet.http). The HttpServletRequest object represents the client's request, and the HttpServletResponse object represents the server's response to the client. If method doGet is unable to handle a client's request, it throws an exception of type javax.servlet.ServletException. If doGet encounters an error during stream processing (reading from the client or writing to the client), it throws a java.io.IOException.

To demonstrate a response to a get request, our servlet creates an XHTML document containing the text "Welcome to Servlets!" The text of the XHTML document is the response to the client. The response is sent to the client through the PrintWriter object obtained from the HttpServletResponse object.

Line 17 uses the response object's setContentType method to specify the content type of the data to be sent as the response to the client. This enables the client browser to understand and handle the content. The content type is also known as the MIME (Multipurpose Internet Mail Extension) type of the data. In this example, the content type is text/html to indicate to the browser that the response is an XHTML document. The browser knows that it must read the XHTML tags, format the document accordingly and display it in the browser window.

Line 18 uses the response object's getWriter method to obtain a reference to the PrintWriter object that enables the servlet to send content to the client. [Note: If the response is binary data, such as an image, method getOutputStream is used to obtain a reference to a ServletOutputStream object.]

Lines 2342 create the XHTML document by writing strings with the out object's println method. This method outputs a newline character after its String argument. When rendering the Web page, the browser does not use the newline character. Rather, the newline character appears in the XHTML source that you can see by selecting Source from the View menu in Internet Explorer or Page Source from the View menu in Netscape. Line 43 closes the output stream, flushes the output buffer and sends the information to the client.

The XHTML document in Fig. 26.8 provides a form that invokes the servlet defined in Fig. 26.7. The form's action attribute (/jhtp6/welcome1) specifies the URL path that invokes the servlet, and the form's method attribute indicates that the browser sends a get request to the server, which results in a call to the servlet's doGet method. The URL specified as the action in this example is discussed in detail in Section 26.4.1 after we show how to set up and configure the Apache Tomcat server to execute the servlet in Fig. 26.7.

Note that the sample screen captures show a URL containing the server name localhosta well-known server host name on most computers that support TCP/IP-based networking protocols such as HTTP. We often use localhost to demonstrate networking programs on the local computer, so that readers without a network connection can still learn network programming concepts. In this example, localhost indicates that the server on which the servlet is installed is running on the local machine. The server host name is followed by :8080, specifying the TCP port number at which the Tomcat server listens for requests from clients. Web browsers assume TCP port 80 by default as the server port at which clients make requests, but the Tomcat server listens for client requests at TCP port 8080. This allows Tomcat to execute on the same computer as a standard Web server application without affecting the Web server's ability to handle requests. If we do not explicitly specify the port number in the URL, the servlet will not receive our request and an error message will be displayed in the browser.

Software Engineering Observation 26.3

Ports in this case are not physical hardware ports to which you attach cablesthey are logical locations named with integer values that allow clients to request different services on the same server. The port number specifies the logical location where a server waits for and receives connections from clientsthis is also called the handshake point. A client connecting to a server to request a service must specify the port number for that service; otherwise, the request cannot be processed. Port numbers are positive integers with values up to 65,535, and there are separate sets of these numbers for both the TCP and UDP protocols. Many operating systems reserve port numbers below 1024 for system services (such as e-mail and World Wide Web servers). Generally, these ports should not be specified as connection ports in your own server programs. In fact, some operating systems require special access privileges to use port numbers below 1024.

With so many ports from which to choose, how does a client know which port to use when requesting a service? The term well-known port number is often used when describing popular services on the Internet, such as Web servers and e-mail servers. All Web browsers know 80 as the well-known port on a Web server where requests for HTML documents are made. So when you type a URL into a Web browser, the browser by default connects to port 80 on the server. Because, the Tomcat server uses port 8080 as its port number, requests to Tomcat for Web pages or to invoke servlets and JavaServer Pages must specify that the Tomcat server listens on port 8080.

The client can access the servlet only if it is installed on a server that can respond to servlet requests. In some cases, servlet support is built directly into the Web server, and no special configuration is required to handle servlet requests. In other cases, it is necessary to integrate a servlet container with a Web server (as can be done with Tomcat and the Apache or IIS Web servers). Web servers that support servlets normally have an installation procedure for servlets. If you intend to execute your servlet as part of a Web server, please refer to your server's documentation on how to install a servlet. For our examples, we demonstrate servlets with the Apache Tomcat server. Section 26.3 discusses the setup and configuration of Tomcat for use with this chapter. Section 26.4.1 discusses the deployment of the servlet in Fig. 26.7.

26.4.1. Deploying a Web Application

JSPs, servlets and their supporting files are deployed as part of Web applications. Normally, Web applications are deployed in the webapps subdirectory of jakarta-tomcat-5.0.25. A Web application has a well-known directory structure in which all the files that are part of the application reside. This structure can be created by the server administrator in the webapps directory, or the entire directory structure can be archived in a Web application archive file. Such an archive is known as a WAR file and ends with the .war file extension. Such files are typically placed in the webapps directory. When the Tomcat server begins execution, it extracts the WAR file's contents into the appropriate webapps subdirectory structure. For simplicity as we teach servlets and JavaServer Pages, we create the already expanded directory structure for all the examples in this chapter.

The Web application directory structure contains a context rootthe top-level directory for an entire Web applicationand several subdirectories. These are described in Fig. 26.9.

Common Programming Error 26.1

Configuring the context root for a Web application in Tomcat requires creating a subdirectory in the webapps directory. When Tomcat begins execution, it creates a context root for each subdirectory of webapps, using each subdirectory's name as a context root name. To test the examples in this chapter, create the directory jhtp6 in Tomcat's webapps directory.

After configuring the context root, we must configure our Web application to handle the requests. This configuration occurs in a deployment descriptor, which is stored in a file called web.xml. This specifies various configuration parameters, such as the name used to invoke the servlet (i.e., its alias), a description of the servlet, the servlet's fully qualified class name and a servlet mapping (i.e., the path or paths that cause the servlet container to invoke the servlet). You must create the web.xml file for this example. Many Java Web application deployment tools create the web.xml file for you. The one for the first example in this chapter is shown in Fig. 26.10. We will enhance this file as we add other servlets to the Web application throughout this chapter.

Figure 26.10. Deployment descriptor (web.xml) for the jhtp6 Web application.

(This item is displayed on page 1253 in the print version)

Element web-app (lines 137) defines the configuration of each servlet in the Web application and the servlet mapping for each servlet. Element display-name (lines 811) specifies a name that can be displayed to the administrator of the server on which the Web application is installed. Element description (lines 1316) specifies a description of the Web application that might be displayed to the server administrator.

Element servlet (lines 1929) describes a servlet. Element servlet-name (line 20) is the name we chose for the servlet (welcome1). Element description (lines 2224) specifies a description for this particular servlet. Again, this can be displayed to the server administrator. Element servlet-class (lines 2628) specifies the compiled servlet's fully qualified class name. Thus, the servlet welcome1 is defined by class WelcomeServlet.

Element servlet-mapping (lines 3235) specifies servlet-name and url-pattern elements. The URL pattern helps the server determine which requests are sent to the servlet (welcome1). Our Web application will be installed as part of the jhtp6 context root discussed in Section 26.4.1. Thus, the relative URL we supply to the browser to invoke the servlet in this example is

/jhtp6/welcome1

where /jhtp6 specifies the context root that helps the server determine which Web application handles the request and /welcome1 specifies the URL pattern that is mapped to servlet welcome1 to handle the request. Note that the server on which the servlet resides is not specified here, although this can be done as follows:

http://localhost:8080/jhtp6/welcome1

If the explicit server and port number are not specified as part of the URL, the browser assumes that the form handler (i.e., the value of the action attribute of the form element in HTML) resides at the same server and port number from which the browser downloaded the Web page containing the form.

There are several URL pattern formats that can be used. The /welcome1 URL pattern requires an exact match of the pattern. You can also specify path mappings, extension mappings and a default servlet for a Web application. A path mapping begins with a / and ends with a /*. For example, the URL pattern

/jhtp6/example/*

indicates that any URL path beginning with /jhtp6/example/ will be sent to the servlet that has the preceding URL pattern. An extension mapping begins with *. and ends with a file-name extension. For example, the URL pattern

*.jsp

indicates that any request for a file with extension .jsp will be sent to the servlet that handles JSP requests. In fact, servers with JSP containers have an implicit mapping of the .jsp extension to a servlet that handles JSP requests. The URL pattern / represents the default servlet for the Web application. This is similar to the default document of a Web server. For example, if you type the URL www.deitel.com into your Web browser, the document you receive from our Web server is the default document index.html. If the URL pattern matches the default servlet for a Web application, that servlet is invoked to return a default response to the client. This can be useful for personalizing Web content to specific users. To compile your servlet, you will need to use javac's -classpath option to specify the name and location of the file servlet-api.jar, which is located in Tomcat's commonlibs directory. Finally, we are ready to place our files into the appropriate directories to complete the deployment of our first servlet for testing. We have three files to placeWelcomeServlet.html, WelcomeServlet.class and web.xml. In your jakarta-tomcat-5.0.25webappsjhtp6 directorythe context root for our Web applicationcreate subdirectories named servlets and WEB-INF. We place our HTML files for this servlets chapter in the servlets directory. Copy the WelcomeServlet.html file into the servlets directory. In the WEB-INF directory, create the subdirectory classes, then copy the web.xml file into the WEB-INF directory, and copy the WelcomeServlet.class file into the classes directory. Thus, the directory and file structure under the webapps directory should be as shown in Fig. 26.11 (file names are in italics).After the files are placed in the proper directories, start the Tomcat server, open your browser and type the following URL

http://localhost:8080/jhtp6/servlets/WelcomeServlet.html

to load WelcomeServlet.html into the Web browser. Then click the Get HTML Document button to invoke the servlet. You should see the results shown in Fig. 26.8. You can try this servlet from several different Web browsers to demonstrate that the results are the same across Web browsers.

Common Programming Error 26.2

Actually, the HTML file in Fig. 26.8 was not necessary to invoke this servlet. A get request can be sent to a server simply by typing the URL in a browserexactly as you do when you request a Web page in the browser. In this example, you can type

http://localhost:8080/jhtp6/welcome1

in the Address or Location field of your browser to invoke the servlet directly.

Error-Prevention Tip 26.3