2.3. The Servlet Life Cycle

In Section 2.1 (The Advantages of Servlets Over “Traditional” CGI), I referred to the fact that only a single instance of a servlet gets created, with each user request resulting in a new thread that is handed off to doGet or doPost as appropriate. I’ll now be more specific about how servlets are created and destroyed, and how and when the various methods are invoked. I give a quick summary here, then elaborate in the following subsections.

When the servlet is first created, its init method is invoked, so init is where you put one-time setup code. After this, each user request results in a thread that calls the service method of the previously created instance. Multiple concurrent requests normally result in multiple threads calling service simultaneously, although your servlet can implement a special interface (SingleThreadModel) that stipulates that only a single thread is permitted to run at any one time. The service method then calls doGet, doPost, or another do Xxx method, depending on the type of HTTP request it received. Finally, when the server decides to unload a servlet, it first calls the servlet’s destroy method.

The init Method

The init method is called when the servlet is first created; it is not called again for each user request. So, it is used for one-time initializations, just as with the init method of applets. The servlet is normally created when a user first invokes a URL corresponding to the servlet, but you can also specify that the servlet be loaded when the server is first started (see Section 5.5, “ Initializing and Preloading Servlets and JSP Pages ”).

The init method definition looks like this:

public void init() throws ServletException {
  // Initialization code... 
} 

One of the most common tasks that init performs is reading server-specific initialization parameters. For example, the servlet might need to know about database settings, password files, server-specific performance parameters, hit count files, or serialized cookie data from previous requests. Initialization parameters are particularly valuable because they let the servlet deployer (e.g., the server administrator), not just the servlet author, customize the servlet.

To read initialization parameters, you first obtain a ServletConfig object by means of getServletConfig, then call getInitParameter on the result. Here is an example:

public void init() throws ServletException {
  ServletConfig config = getServletConfig(); 
  String param1 = config.getInitParameter("parameter1"); 
} 

Notice two things about this code. First, the init method uses getServletConfig to obtain a reference to the ServletConfig object. Second, ServletConfig has a getInitParameter method with which you can look up initialization parameters associated with the servlet. Just as with the getParameter method used in the init method of applets, both the input (the parameter name) and the output (the parameter value) are strings.

You read initialization parameters by calling the getInitParameter method of ServletConfig. But how do you set them? That’s the job of the web.xml file, called the deployment descriptor. This file belongs in the WEB-INF directory of the Web application you are using, and it controls many aspects of servlet and JSP behavior. Many servers provide graphical interfaces that let you specify initialization parameters and control various aspects of servlet and JSP behavior. Although those interfaces are server specific, behind the scenes they use the web.xml file, and this file is completely portable. Use of web.xml is discussed in detail in Chapter 4 (Using and Deploying Web Applications) and Chapter 5 (Controlling Web Application Behavior with web.xml), but for a quick preview, web.xml contains an XML header, a DOCTYPE declaration, and a web-app element. For the purpose of initialization parameters, the web-app element should contain a servlet element with three subelements: servlet-name, servlet-class, and init-param. The servlet-name element is the name that you want to use to access the servlet. The servlet-class element gives the fully qualified (i.e., including packages) class name of the servlet, and init-param gives names and values to initialization parameters.

For example, Listing 2.7 shows a web.xml file that gives a value to the initialization parameter called parameter1 of the OriginalServlet class that is in the somePackage package. However, the initialization parameter is available only when the servlet is accessed with the registered servlet name (or a custom URL as described in Section 5.3). So, the param1 variable in the previous code snippet would have the value "First Parameter Value" when the servlet is accessed by means of http://host/servlet/SomeName, but would have the value null when the servlet is accessed by means of http://host/servlet/somePackage.OriginalServlet.

Core Warning Initialization parameters are not available to servlets that are accessed by means of their default URL. A registered name or custom URL must be used.

For more information on the web.xml file, including new parameters available with servlets version 2.3, see Chapter 5 (Controlling Web Application Behavior with web.xml). For specific details on initialization parameters and a complete working example, see Section 5.5 (Initializing and Preloading Servlets and JSP Pages).

Listing 2.7. web.xml (Excerpt illustrating initialization parameters)

<?xml version="1.0" encoding="ISO-8859-1"?> 
<!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>
							<servlet-name>SomeName</servlet-name>
							<servlet-class>somePackage.OriginalServlet</servlet-class>
							<init-param>
							<param-name>parameter1</param-name>
							<param-value>First Parameter Value</param-value>
							</init-param>
							</servlet> 
  <!-- ... --> 
</web-app> 

The service Method

Each time the server receives a request for a servlet, the server spawns a new thread (perhaps by reusing an idle Thread from a thread pool) and calls service. The service method checks the HTTP request type (GET, POST, PUT, DELETE, etc.) and calls doGet, doPost, doPut, doDelete, etc., as appropriate. A GET request results from a normal request for a URL or from an HTML form that has no METHOD specified. A POST request results from an HTML form that specifically lists POST as the METHOD. Other HTTP requests are generated only by custom clients. If you aren’t familiar with HTML forms, see Chapter 16 of Core Servlets and JavaServer Pages (available in PDF at http://www.moreservlets.com).

Now, if you have a servlet that needs to handle both POST and GET requests identically, you may be tempted to override service directly rather than implementing both doGet and doPost. This is not a good idea. Instead, just have doPost call doGet (or vice versa), as below.

public void doGet(HttpServletRequest request, 
                  HttpServletResponse response) 
    throws ServletException, IOException {
  // Servlet code 
} 

public void doPost(HttpServletRequest request, 
                   HttpServletResponse response) 
    throws ServletException, IOException {
  doGet(request, response); 
} 

Although this approach takes a couple of extra lines of code, it has several advantages over directly overriding service. First, you can later add support for other HTTP request methods by adding doPut, doTrace, etc., perhaps in a subclass. Overriding service directly precludes this possibility. Second, you can add support for modification dates by adding a getLastModified method. Since getLastModified is invoked by the default service method, overriding service eliminates this option. Finally, you get automatic support for HEAD, OPTION, and TRACE requests.

Core Approach If your servlet needs to handle both GET and POST identically, have your doPost method call doGet , or vice versa. Don’t override service.

The doGet, doPost, and doXxx Methods

These methods contain the real meat of your servlet. Ninety-nine percent of the time, you only care about GET or POST requests, so you override doGet and/or doPost. However, if you want to, you can also override doDelete for DELETE requests, doPut for PUT, doOptions for OPTIONS, and doTrace for TRACE. Recall, however, that you have automatic support for OPTIONS and TRACE.

In versions 2.1 and 2.2 of the servlet API, there is no doHead method. That’s because the system automatically uses the status line and header settings of doGet to answer HEAD requests. In version 2.3, however, doHead was added so that you can generate responses to HEAD requests (i.e., requests from custom clients that want just the HTTP headers, not the actual document) more quickly—without building the actual document output.

The SingleThreadModel Interface

Normally, the system makes a single instance of your servlet and then creates a new thread for each user request, with multiple concurrent threads running if a new request comes in while a previous request is still executing. This means that your doGet and doPost methods must be careful to synchronize access to fields and other shared data, since multiple threads may access the data simultaneously. If you want to prevent this multithreaded access, you can have your servlet implement the SingleThreadModel interface, as below.

public class YourServlet extends HttpServlet 
    implements SingleThreadModel {
  ... 
} 

If you implement this interface, the system guarantees that there is never more than one request thread accessing a single instance of your servlet. In most cases, it does so by queuing all the requests and passing them one at a time to a single servlet instance. However, the server is permitted to create a pool of multiple instances, each of which handles one request at a time. Either way, this means that you don’t have to worry about simultaneous access to regular fields (instance variables) of the servlet. You do, however, still have to synchronize access to class variables (static fields) or shared data stored outside the servlet.

Synchronous access to your servlets can significantly hurt performance (latency) if your servlet is accessed frequently. When a servlet waits for I/O, the server remains idle instead of handling pending requests. So, think twice before using the SingleThreadModel approach.

Core Warning Avoid implementing SingleThreadModel for high-traffic servlets. Use explicit synchronized blocks instead.

The destroy Method

The server may decide to remove a previously loaded servlet instance, perhaps because it is explicitly asked to do so by the server administrator, or perhaps because the servlet is idle for a long time. Before it does, however, it calls the servlet’s destroy method. This method gives your servlet a chance to close database connections, halt background threads, write cookie lists or hit counts to disk, and perform other such cleanup activities. Be aware, however, that it is possible for the Web server to crash. So, don’t count on destroy as the only mechanism for saving state to disk. Activities like hit counting or accumulating lists of cookie values that indicate special access should also proactively write their state to disk periodically.