SRV.3.3 Servlet Life Cycle

A servlet is managed through a well-defined life cycle that defines how it is loaded, instantiated and initialized , handles requests from clients , and how it is taken out of service. This life cycle is expressed in the API by the init , service , and destroy methods of the javax.servlet.Servlet interface that all servlets must, directly or indirectly through the GenericServlet or HttpServlet abstract classes, implement.

SRV.3.3.1 Loading and Instantiation

The servlet container is responsible for loading and instantiating a servlet. The instantiation and loading can occur when the engine is started or it can be delayed until the container determines that it needs the servlet to service a request.

First, a class of the servlet's type must be located by the servlet container. If needed, the servlet container loads a servlet using normal Java class loading facilities from a local file system, a remote file system, or other network services.

After the container has loaded the Servlet class, it instantiates an object instance of that class for use.

It is important to note that there can be more than one instance of a given Srvlet class in the servlet container. For example, this can occur where there was more than one servlet definition that utilized a specific servlet class with different initialization parameters. This can also occur when a servlet implements the SingleThreadModel interface and the container creates a pool of servlet instances to use.

SRV.3.3.2 Initialization

After the servlet object is loaded and instantiated, the container must initialize the servlet before it can handle requests from clients. Initialization is provided so that a servlet can read any persistent configuration data, initialize costly resources (such as JDBC based connection), and perform any other one-time activities. The container initializes the servlet by calling the init method of the Servlet interface with a unique (per servlet definition) object implementing the ServletConfig interface. This configuration object allows the servlet to access name -value initialization parameters from the servlet container's configuration information. The configuration object also gives the servlet access to an object implementing the ServletContext interface which describes the runtime environment that the servlet is running within. See Chapter SRV.4, "Servlet Context," for more information about the ServletContext interface.

SRV.3.3.2.1 Error Conditions on Initialization

During initialization, the servlet instance can signal that it is not to be placed into active service by throwing an UnavailableException or ServletException . If a servlet instance throws an exception of this type, it must not be placed into active service and the instance must be immediately released by the servlet container. The destroy method is not called in this case as initialization was not considered to be successful.

After the instance of the failed servlet is released, a new instance may be instantiated and initialized by the container at any time. The only exception to this rule is if the UnavailableException is thrown by the failed servlet, which indicates the minimum time of unavailability. In this case, the container must wait for the minimum time of unavailability to pass before creating and initializing a new servlet instance.

SRV.3.3.2.2 Tool Considerations

When a tool loads and introspects a web application, it may load and introspect member classes of the web application. This will trigger static initialization methods to be executed. Because of this behavior, a developer should not assume that a servlet is in an active container runtime unless the init method of the Servlet interface is called. For example, this means that a servlet should not try to establish connections to databases or Enterprise JavaBeans component architecture containers when its static (class) initialization methods are invoked.

SRV.3.3.3 Request Handling

After the servlet is properly initialized, the servlet container may use it to handle requests. Each request is represented by a request object of type ServletRequest and the servlet can create a response to the request by using the provided object of type ServletResponse . These objects are passed as parameters to the service method of the Servlet interface. In the case of an HTTP request, the container must provide the request and response objects as implementations of HttpServletRequest and HttpServletResponse .

It is important to note that a servlet instance may be created and placed into service by a servlet container but may handle no requests during its lifetime.

SRV.3.3.3.1 Multithreading Issues

During the course of servicing requests from clients, a servlet container may send multiple requests from multiple clients through the service method of the servlet at any one time. This means that the developer must take care to make sure that the servlet is properly programmed for concurrency.

If a developer wants to prevent this default behavior, he can program the servlet to implement the SingleThreadModel interface. Implementing this interface will guarantee that only one request thread at a time will be allowed in the service method. A servlet container may satisfy this guarantee by serializing requests on a servlet or by maintaining a pool of servlet instances. If the servlet is part of an application that has been marked as distributable, the container may maintain a pool of servlet instances in each VM that the application is distributed across.

If a developer defines a service method (or methods such as doGet or doPost which are dispatched from the service method of the HttpServlet abstract class) with the synchronized keyword, the servlet container will, by necessity of the underlying Java runtime, serialize requests through it. However, the container must not create an instance pool as it does for servlets that implement the SingleThreadModel. It is strongly recommended that developers not synchronize the service method or any of the HttpServlet service methods such as doGet, doPost, etc.

SRV.3.3.3.2 Exceptions During Request Handling

A servlet may throw either a ServletException or an UnavailableException during the service of a request. A ServletException signals that some error occurred during the processing of the request and that the container should take appropriate measures to clean up the request. An UnavailableException signals that the servlet is unable to handle requests either temporarily or permanently.

If a permanent unavailability is indicated by the UnavailableException , the servlet container must remove the servlet from service, call its destroy method, and release the servlet instance.

If temporary unavailability is indicated by the UnavailableException , then the container may choose not to route any requests through the servlet during the time period of the temporary unavailability. Any requests refused by the container during this period must be returned with a SERVICE_UNAVAILABLE (503) response status along with a Retry-After header indicating when the unavailability will terminate. The container may choose to ignore the distinction between a permanent and temporary unavailability and treat all UnavailableExceptions as permanent, thereby removing a servlet that throws any UnavailableException from service.

SRV.3.3.3.3 Thread Safety

A developer should note that implementations of the request and response objects are not guaranteed to be thread safe. This means that they should be used only in the scope of the request handling thread. References to the request and response objects should not be given to objects executing in other threads as the behavior may be nondeterministic.

SRV.3.3.4 End of Service

The servlet container is not required to keep a servlet loaded for any period of time. A servlet instance may be kept active in a servlet container for a period of only milliseconds , for the lifetime of the servlet container (which could be measured in days, months, or years ), or for any amount of time in between.

When the servlet container determines that a servlet should be removed from service (for example, when a container wants to conserve memory resources, or when it itself is being shut down), it must allow the servlet to release any resources it is using and save any persistent state. To do this the servlet container calls the destroy method of the Servlet interface.

Before the servlet container can call the destroy method, it must allow any threads that are currently running in the service method of the servlet to either complete or exceed a server defined time limit before the container can proceed with calling the destroy method.

Once the destroy method is called on a servlet instance, the container may not route any more requests to that particular instance of the servlet. If the container needs to enable the servlet again, it must do so with a new instance of the servlet's class.

After the destroy method completes, the servlet container must release the servlet instance so that it is eligible for garbage collection.