Sun ONE logo      Previous      Contents      Index      Next     

Sun ONE Web Server 6.1 Programmer's Guide to Web Applications

Chapter 2
Using Servlets

This chapter describes how to create effective servlets to control web application interactions running on a Sun ONE Web Server, including standard servlets. In addition, this chapter describes the Sun ONE Web Server features used to augment the standards.

This chapter has the following sections:

For information about internationalization issues for servlets, see Appendix A, "Internationalization Issues." For information about migrating legacy servlets, see Appendix B, "Migrating Legacy Servlets."

About Servlets



Servlets supported by the Sun ONE Web Server are based on the Java Servlet 2.3 specification.

The following list describes the fundamental characteristics of servlets.


This section includes the following topics:

Servlet Data Flow


The following illustration shows the information flow to and from the servlet. The steps are as follows:

  1. The servlet processes the client request.
  2. The servlet generates content.
  3. The servlet creates a response and either:
    1. Sends it back directly to the client
    2. - or -

    3. Dispatches the task to a JSP

The servlet remains in memory, available to process another request.

Figure 2-1  Servlet Data Flow Steps

Figure showing servlet data flow steps.

Servlet Types

There are two main servlet types, generic and HTTP:

For both servlet types, you implement the constructor method init() and the destructor method destroy() to initialize or deallocate resources.


Creating Servlets

To create a servlet, perform the following tasks:

The rest of this section discusses the following topics:

Creating the Class Declaration

To create a servlet, write a public Java class that includes basic I/O support as well as the package javax.servlet. The class must extend either GenericServlet or HttpServlet. Since Sun ONE Web Server servlets exist in an HTTP environment, the latter class is recommended. If the servlet is part of a package, you must also declare the package name so the class loader can properly locate it.

The following example header shows the HTTP servlet declaration called myServlet:

     import javax.servlet.*;
     import javax.servlet.http.*;

     public class myServlet extends HttpServlet {
servlet methods...

Overriding Methods

Next, override one or more methods to provide servlet instructions to perform its intended task. All processing by a servlet is done on a request-by-request basis and happens in the service methods, either service() for generic servlets or one of the doOperation() methods for HTTP servlets. This method accepts incoming requests, processing them according to the instructions you provide, and directs the output appropriately. You can create other methods in a servlet as well.

Overriding Initialize

Override the class initializer init() to initialize or allocate resources for the servlet instance's life, such as a counter. The init() method runs after the servlet is instantiated but before it accepts any requests. For more information, see the servlet API specification.


All init() methods must call super.init(ServletConfig) to set their scope. This makes the servlet's configuration object available to other servlet methods. If this call is omitted, a 500 SC_INTERNAL_SERVER_ERROR displays in the browser when the servlet starts up.

The following example of the init() method initializes a counter by creating a public integer variable called thisMany:

public class myServlet extends HttpServlet {
        int thisMany;
public void init (ServletConfig config) throws ServletException
           thisMany = 0;

Now other servlet methods can access the variable.

Overriding Destroy

Override the class destructor destroy() to write log messages or to release resources that have been opened in the servlet's life cycle. Resources should be appropriately closed and dereferenced so that they are recycled or garbage collected. The destroy() method runs just before the servlet itself is deallocated from memory. For more information, see the servlet API specification.

For example, the destroy() method could write a log message like the following, based on the example for "Overriding Initialize" above:

out.println("myServlet was accessed " + thisMany " times.\n");

Overriding Service, Get, and Post

When a request is made, the Sun ONE Web Server hands the incoming data to the servlet engine to process the request. The request includes form data, cookies, session information, and URL name-value pairs, all in a type HttpServletRequest object called the request object. Client metadata is encapsulated as a type HttpServletResponse object called the response object. The servlet engine passes both objects as the servlet's service() method parameters.

The default service() method in an HTTP servlet routes the request to another method based on the HTTP transfer method (POST, GET, and so on). For example, HTTP POST requests are routed to the doPost() method, HTTP GET requests are routed to the doGet() method, and so on. This enables the servlet to perform different request data processing depending on the transfer method. Since the routing takes place in service(), there is no need to generally override service() in an HTTP servlet. Instead, override doGet(), doPost(), and so on, depending on the expected request type.

The automatic routing in an HTTP servlet is based simply on a call to request.getMethod(), which provides the HTTP transfer method. In a Sun ONE Web Server, request data is already preprocessed into a name-value list by the time the servlet sees the data, so simply overriding the service() method in an HTTP servlet does not lose any functionality. However, this does make the servlet less portable, since it is now dependent on preprocessed request data.

Override the service() method (for generic servlets) or the doGet() or doPost() methods (for HTTP servlets) to perform tasks needed to answer the request. Very often, this means collating the needed information (in the request object or in a JDBC result set object), and then passing the newly generated content to a JSP for formatting and delivery back to the client.

Most operations that involve forms use either a GET or a POST operation, so for most servlets you override either doGet() or doPost(). Implement both methods to provide for both input types or simply pass the request object to a central processing method, as shown in the following example:

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

All request-by-request traffic in an HTTP servlet is handled in the appropriate doOperation() method, including session management, user authentication, JSPs, and accessing Sun ONE Web Server features.

If a servlet intends to call the RequestDispatcher method include() or forward(), be aware the request information is no longer sent as HTTP POST, GET, and so on. In other words, if a servlet overrides doPost(), it may not process anything if another servlet calls it, if the calling servlet happens to receive its data through HTTP GET. For this reason, be sure to implement routines for all possible input types, as explained above. RequestDispatcher methods always call service().

For more information, see "Calling a Servlet Programmatically."


Arbitrary binary data, such as uploaded files or images, can be problematic, because the web connector translates incoming data into name-value pairs by default. You can program the web connector to properly handle these kinds of data and package them correctly in the request object.

Accessing Parameters and Storing Data

Incoming data is encapsulated in a request object. For HTTP servlets, the request object type is HttpServletRequest. For generic servlets, the request object type is ServletRequest. The request object contains all request parameters, including your own request values called attributes.

To access all incoming request parameters, use the getParameter() method. For example:

String username = request.getParameter("username");

Set and retrieve values in a request object using setAttribute() and getAttribute(), respectively. For example:

request.setAttribute("favoriteDwarf", "Dwalin");

Handling Sessions and Security

From a web server's perspective, a web application is a series of unrelated server hits. There is no automatic recognition if a user has visited the site before, even if their last interaction was seconds before. A session provides a context between multiple user interactions by remembering the application state. Clients identify themselves during each interaction by a cookie, or, in the case of a cookie-less browser, by placing the session identifier in the URL.

A session object can store objects, such as tabular data, information about the application's current state, and information about the current user. Objects bound to a session are available to other components that use the same session.

For more information, see "Session Managers."

After a successful login, you should direct a servlet to establish the user's identity in a standard object called a session object that holds information about the current session, including the user's login name and any additional information to retain. Application components can then query the session object to obtain user authentication.

For more information about providing a secure user session for your application, see "Securing Web Applications."

Handling Threading Issues

By default, servlets are not thread-safe. The methods in a single servlet instance are usually executed numerous times simultaneously (up to the available memory limit). Each execution occurs in a different thread, though only one servlet copy exists in the servlet engine.

This is efficient system resource usage, but is dangerous because of the way Java manages memory. Because variables belonging to the servlet class are passed by reference, different threads can overwrite the same memory space as a side effect. To make a servlet (or a block within a servlet) thread-safe, do one of the following:

Delivering Client Results


Creating a Servlet Response Page





PrintWriter output = response.getWriter();
output.println("Hello, World\n");


ServletOutputStream output = response.getOutputStream();

Creating a JSP Response Page


For more information about JSPs, see "Using JavaServer Pages."

Invoking Servlets


Calling a Servlet with a URL




Table 2-1  URL Fields for Servlets within a Web Application  

URL Element












Optional servlet name-value parameters.

In this example, leMort is the host name, MortPages is the context root, and calcMortgage is the servlet name: 60&bal=180000

Calling a Servlet Programmatically




Servlet Output

By default, the System.out and System.err output of servlets is sent to the server log, and during startup server log messages are echoed to the System.err output. Also by default, on Windows, there is no console created for the System.err output.

You can change these defaults using the Administration interface. For more information, see “Setting Error Logging Options” in Chapter 10 of the Sun ONE Web Server 6.1 Administrator’s Guide.

Caching Servlet Results

The Sun ONE Web Server can cache the results of invoking a servlet, a JSP, or any URL pattern to make subsequent invocations of the same servlet, JSP, or URL pattern faster. The Sun ONE Web Server caches the request results for a specific amount of time. In this way, if another data call occurs, the Sun ONE Web Server can return the cached data instead of performing the operation again. For example, if your servlet returns a stock quote that updates every 5 minutes, you set the cache to expire after 300 seconds.

Whether to cache results and how to cache them depends on the data involved. For example, it makes no sense to cache the results of a quiz submission, because the input to the servlet is different each time. However, you could cache a high-level report showing demographic data taken from quiz results that is updated once an hour.

You can define how a Sun ONE Web Server web application handles response caching by editing specific fields in the sun-web.xml file. In this way, you can create programmatically standard servlets that still take advantage of this valuable Sun ONE Web Server feature.

For more information about JSP caching, see "JSP Cache Tags."


For information about caching static file content, see the nsfc.conf file, described in the Sun ONE Web Server 6.1 Administrator's Configuration File Reference.

The rest of this section covers the following topics:

Caching Features

Sun ONE Web Server 6.1 has the following web application response caching capabilities:

Default Cache Configuration


Caching Example


      <servlet-name>myservlet</servlet name>
        -- this resource only when the given parameters exist. cache
        -- but no other catalog varieties:
        -- but not the result of
        <value> roses </value>
        <value> lilies </value>
        -- a specific value -->
        <value match-expr="equals" cache-on-match-failure="true">bogus</value>
      <servlet-name> InfoServlet </servlet name>

For more information about the sun-web.xml caching settings, see "Caching Elements."

CacheHelper Interface

Here is the CacheHelper interface:

package com.sun.appserv.web.cache;
import java.util.Map
import javax.servlet.ServletContext;
import javax.servlet.http.HttpServletRequest;
/** CacheHelper interface is an user-extensible interface to customize:
 * a) the key generation b) whether to cache the response.
public interface CacheHelper {
// name of request attributes
   public static final String ATTR_CACHE_MAPPED_SERVLET_NAME =
   public static final String ATTR_CACHE_MAPPED_URL_PATTERN =
public static final int TIMEOUT_VALUE_NOT_SET = -2;
/** initialize the helper
    * @param context the web application context this helper belongs to
    * @exception Exception if a startup error occurs
   public void init(ServletContext context, Map props) throws Exception;
/** getCacheKey: generate the key to be used to cache this request
    * @param request incoming <code>HttpServletRequest</code> object
    * @returns the generated key for this requested cacheable resource.
   public String getCacheKey(HttpServletRequest request);
/** isCacheable: is the response to given request cacheable?
    * @returns <code>true</code> if the response could be cached. or
    * <code>false</code> if the results of this request must not be cached.
   public boolean isCacheable(HttpServletRequest request);
/** isRefreshNeeded: is the response to given request to be refreshed?
    * @returns <code>true</code> if the response needs to be refreshed.
    * or return <code>false</code> if the results of this request
    * don't need to be refreshed.
   public boolean isRefreshNeeded(HttpServletRequest request);
/** get timeout for the cached response.
    * @returns the timeout in seconds for the cached response; a return
    * value of -1 means the response never expires and a value of -2 indicates
    * helper cannot determine the timeout (container assigns default timeout)
public int getTimeout(HttpServletRequest request);
    * Stop the helper from active use
    * @exception Exception if an error occurs
   public void destroy() throws Exception;

CacheKeyGenerator Interface


The name of the context attribute is configurable as the value of the cacheKeyGeneratorAttrName property in the default-helper element of the sun-web.xml deployment descriptor. For more information, see "default-helper."

Here is the CacheKeyGenerator interface:

package com.sun.appserv.web.cache;
import javax.servlet.ServletContext;
import javax.servlet.http.HttpServletRequest;
/** CacheKeyGenerator: a helper interface to generate the key that
 * is used to cache this request.
 * Name of the ServletContext attribute implementing the
 * CacheKeyGenerator is configurable via a property of the
 * default-helper in sun-web.xml:
 * <default-helper>
 * <property
 * name="cacheKeyGeneratorAttrName"
 * value="com.acme.web.MyCacheKeyGenerator" />
 * </default-helper>
 * Caching engine looks up the specified attribute in the servlet
 * context; the result of the lookup must be an implementation of the
 * CacheKeyGenerator interface.
public interface CacheKeyGenerator {
/** getCacheKey: generate the key to be used to cache the
    * response.
    * @param context the web application context
    * @returns key string used to access the cache entry.
    * if the return value is null, a default key is used.
   public String getCacheKey(ServletContext context,
                           HttpServletRequest request);

Maximizing Servlet Performance

Consider the following guidelines for improving servlet performance:

Previous      Contents      Index      Next     

Copyright 2004 Sun Microsystems, Inc. All rights reserved.