Java Servlet Specification
|
   
|
| C H A P T E R 2 |
|
The Servlet Interface |
The Servlet interface is the central abstraction of the Java Servlet API. All servlets implement this interface either directly or, more commonly, by extending a class that implements the interface. The two classes in the Java Servlet API that implement the Servlet interface are GenericServlet and HttpServlet. For most purposes, developers will extend HttpServlet to implement their servlets.
The basic Servlet interface defines a service method for handling client requests. This method is called for each request that the servlet container routes to an instance of a servlet.
The handling of concurrent requests to a web application generally requires that the web developer design servlets that can deal with multiple threads executing within the service method at a particular time.
Generally the web container handles concurrent requests to the same servlet by concurrent execution of the service method on different threads.
The HttpServlet abstract subclass adds additional methods beyond the basic Servlet interface that are automatically called by the service method in the HttpServlet class to aid in processing HTTP-based requests. These methods are:
The doPut and doDelete methods allow servlet developers to support HTTP/1.1 clients that employ these features. The doHead method in HttpServlet is a specialized form of the doGet method that returns only the headers produced by the doGet method.
The HttpServlet interface defines the getLastModified method to support conditional GET operations. A conditional GET operation requests a resource be sent only if it has been modified since a specified time. In appropriate situations, implementation of this method may aid efficient utilization of network resources.
The servlet declaration which is part of the deployment descriptor of the web application containing the servlet, as described in Chapter 13 controls how the servlet container provides instances of the servlet.
The servlet container must use only one instance per servlet declaration.
A servlet is managed through a well defined life cycle that defines how it is loaded and instantiated, is initialized, handles requests from clients, and 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 implement directly or indirectly through the GenericServlet or HttpServlet abstract classes.
Refer to the Runtime Environment Specification, Java Card Platform, Version 3.0.1, Connected Edition for more details on the lifetime of servlet objects specific to the Java Card Platform.
The servlet container is responsible for loading and instantiating servlets. The loading and instantiation can occur when the container is started, or delayed until the container determines the servlet is needed to service a request.
When the servlet engine is started, needed servlet classes must be located by the servlet container. The servlet container loads the servlet class using the class loading facilities of the runtime environment.
After loading the Servlet class, the container instantiates it for use.
After the servlet object is instantiated, the container must initialize the servlet before it can handle requests from clients. Initialization is provided so that a servlet can read persistent configuration data, initialize costly resources, and perform other one-time activities. The container initializes the servlet instance by calling the init method of the Servlet interface with a unique (per servlet declaration) object implementing the ServletConfig interface. This configuration object allows the servlet to access name-value initialization parameters from the web application’s configuration information. The configuration object also gives the servlet access to an object (implementing the ServletContext interface) that describes the servlet’s runtime environment. See Chapter 3 for more information about the ServletContext interface.
During initialization, the servlet instance can throw an UnavailableException or a ServletException. In this case, the servlet must not be placed into active service and must be released by the servlet container. The destroy method is not called as it is considered unsuccessful initialization.
A new instance may be instantiated and initialized by the container after a failed initialization. The exception to this rule is when an UnavailableException indicates a minimum time of unavailability, and the container must wait for the period to pass before creating and initializing a new servlet instance.
The triggering of static initialization methods when a tool loads and introspects a web application is to be distinguished from the calling of the init method. Developers should not assume a servlet is in an active container runtime until the init method of the Servlet interface is called. For example, a servlet should not try to establish connections to other services when only static (class) initialization methods have been invoked.
After a servlet is properly initialized, the servlet container may use it to handle client requests. Requests are represented by request objects of type ServletRequest. The servlet fills out a response to requests by calling methods of a 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 objects provided by the container are of types HttpServletRequest and HttpServletResponse.
Note that a servlet instance placed into service by a servlet container may handle no requests during its lifetime.
A servlet container may send concurrent requests through the service method of the servlet. To handle the requests, the servlet developer must make adequate provisions for concurrent processing with multiple threads in the service method.
If the init method (or methods such as doGet or doPost which are dispatched to the service method of the HttpServlet abstract class) has been defined with the synchronized keyword, the servlet container cannot use an instance pool approach, but must serialize requests through it. It is strongly recommended that developers not synchronize the service method (or methods dispatched to it) in these circumstances because of detrimental effects on performance. It is recommended that a developer take other means to resolve those issues instead of synchronizing the service method, such as avoiding the usage of an instance variable or synchronizing the block of the code accessing those resources.
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. Any requests refused by the container by that cause must be returned with a SC_NOT_FOUND (404) response.
If temporary unavailability is indicated by the UnavailableException, the container may choose to not 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 SC_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.
Implementations of the request and response objects are not guaranteed to be thread safe. This means that they should only be used within 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 resulting behavior may be nondeterministic. If the thread created by the application uses the container-managed objects, such as the request or response object, those objects must be accessed only within the servlet’s service life cycle and such a thread itself should have a life cycle within the life cycle of the servlet’s service method because accessing those objects after the service method ends may cause undeterminable problems. Because the request and response objects are not thread safe, if those objects were accessed in the multiple threads, the access should be synchronized or be done through the wrapper to add the thread safety by, for instance, synchronizing the call of the methods to access the request attribute or by using a local output stream for the response object within a thread.
The servlet container is not required to keep a servlet loaded for any particular period of time. A servlet instance may be kept active in a servlet container for a period of milliseconds, for the lifetime of the servlet container (which could be a number of days, months, or years), or any amount of time in between.
When the servlet container determines that a servlet should be removed from service, it calls the destroy method of the Servlet interface to allow the servlet to release any resources it is using and save any persistent state. For example, the container may do this when it wants to conserve memory resources, or when it is unloading an application.
Before the servlet container calls the destroy method, it must allow any threads that are currently running in the service method of the servlet to complete execution, or exceed a server-defined time limit.
Once the destroy method is called on a servlet instance, the container may not route other requests to that 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.
| Java Servlet Specification
|
5-30-09 |
|
Copyright © 2009 Sun Microsystems, Inc. All rights reserved.
