Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Developer's Guide

- Previous: Introducing Web Applications
- Next: Using JavaServer Pages

# Using Servlets

Application Server supports the Java Servlet Specification version 2.4.

Note –

Servlet API version 2.4 is fully backward compatible with version 2.3, so all existing servlets should work without modification or recompilation.

To develop servlets, use Sun Microsystems’ Java Servlet API. For information about using the Java Servlet API, see the documentation provided by Sun Microsystems at `http://java.sun.com/products/servlet/index.html`.

The Application Server provides the `wscompile` and `wsdeploy` tools to help you implement a web service endpoint as a servlet. For more information about these tools, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Reference Manual.

This section describes how to create effective servlets to control application interactions running on an Application Server, including standard-based servlets. In addition, this section describes the Application Server features to use to augment the standards.

This section contains the following topics:

- Invoking a Servlet with a URL

- Servlet Output

- Caching Servlet Results

- About the Servlet Engine

## Invoking a Servlet with a URL

You can call a servlet deployed to the Application Server by using a URL in a browser or embedded as a link in an HTML or JSP file. The format of a servlet invocation URL is as follows:

    http://server:port/context-root/servlet-mapping?name=value

The following table describes each URL section.

Table 5–1 URL Fields for Servlets Within an Application

URL element | Description
--- | ---
server`:`port | The IP address (or host name) and optional port number. To access the default web module for a virtual server, specify only this URL section. You do not need to specify the context-root or servlet-name unless you also wish to specify name-value parameters.
context-root | For an application, the context root is defined in the `context-root` element of the `application.xml` or `sun-application.xml` file. For an individually deployed web module, the context root is specified during deployment. For both applications and individually deployed web modules, the default context root is the name of the WAR file minus the `.war` suffix.
servlet-mapping | The `servlet-mapping` as configured in the `web.xml` file. You can use the `servlet-name` instead if you enable the `InvokerServlet`; see Using the default-web.xml File.
`?`name`=`value`...` | Optional request parameters.

In this example, `localhost` is the host name, `MortPages` is the context root, and `calcMortgage` is the servlet mapping:

    http://localhost:8080/MortPages/calcMortgage?rate=8.0&per=360&bal=180000

When invoking a servlet from within a JSP file, you can use a relative path. For example:

    <jsp:forward page="TestServlet"/>
    <jsp:include page="TestServlet"/>

## Servlet Output

`ServletContext.log` messages are sent to the server log.

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

To change these defaults using the Administration Console, select the Logger Settings component under the relevant configuration, then check or uncheck these boxes:

- Log Messages to Standard Error - If checked, `System.err` output is sent to the server log. If unchecked, `System.err` output is sent to the system default location only.

- Write to System Log - If checked, `System.out` output is sent to the server log. If unchecked, `System.out` output is sent to the system default location only.

For more information, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Administration Guide.

## Caching Servlet Results

The Application 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 Application Server caches the request results for a specific amount of time. In this way, if another data call occurs, the Application 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, it makes sense to cache a high level report showing demographic data taken from quiz results that is updated once an hour.

To define how an Application Server web application handles response caching, you edit specific fields in the `sun-web.xml` file.

Note –

A servlet that uses caching is not portable.

A sample caching application is in install-dir`/samples/webapps/apps/caching`.

For more information about JSP caching, see JSP Caching.

The rest of this section covers the following topics:

- Caching Features

- Default Cache Configuration

- Caching Example

- CacheKeyGenerator Interface

### Caching Features

The Application Server has the following web application response caching capabilities:

- Caching is configurable based on the servlet name or the URI.

- When caching is based on the URI, this includes user specified parameters in the query string. For example, a response from `/garden/catalog?category=roses` is different from a response from `/garden/catalog?category=lilies`. These responses are stored under different keys in the cache.

- Cache size, entry timeout, and other caching behaviors are configurable.

- Entry timeout is measured from the time an entry is created or refreshed. To override this timeout for an individual cache mapping, specify the `cache-mapping` subelement `timeout`.

- To determine caching criteria programmatically, write a class that implements the `com.sun.appserv.web.cache.CacheHelper` interface. For example, if only a servlet knows when a back end data source was last modified, you can write a helper class to retrieve the last modified timestamp from the data source and decide whether to cache the response based on that timestamp.

- To determine cache key generation programmatically, write a class that implements the `com.sun.appserv.web.cache.CacheKeyGenerator` interface. See CacheKeyGenerator Interface.

- All non-ASCII request parameter values specified in cache key elements must be URL encoded. The caching subsystem attempts to match the raw parameter values in the request query string.

- Since newly updated classes impact what gets cached, the web container clears the cache during dynamic deployment or reloading of classes.

- The following `HttpServletRequest` request attributes are exposed:

  - `com.sun.appserv.web.cachedServletName`, the cached servlet target

  - `com.sun.appserv.web.cachedURLPattern`, the URL pattern being cached

- Results produced by resources that are the target of a `RequestDispatcher.include()` or `RequestDispatcher.forward()` call are cached if caching has been enabled for those resources. For details, see the descriptions of the cache-mapping and dispatcher elements in the `sun-web.xml` file.

### Default Cache Configuration

If you enable caching but do not provide any special configuration for a servlet or JSP, the default cache configuration is as follows:

- The default cache timeout is 30 seconds.

- Only the HTTP GET method is eligible for caching.

- HTTP requests with cookies or sessions automatically disable caching.

- No special consideration is given to `Pragma:`, `Cache-control:`, or `Vary:` headers.

- The default key consists of the Servlet Path (minus `pathInfo` and the query string).

- A “least recently used” list is maintained to evict cache entries if the maximum cache size is exceeded.

- Key generation concatenates the servlet path with key field values, if any are specified.

- Results produced by resources that are the target of a `RequestDispatcher.include()` or `RequestDispatcher.forward()` call are never cached.

### Caching Example

Here is an example cache element in the `sun-web.xml` file:

    <cache max-capacity="8192" timeout="60">
    <cache-helper name="myHelper" class-name="MyCacheHelper"/>
    <cache-mapping>
    	<servlet-name>myservlet</servlet-name>
    	<timeout name="timefield">120</timeout>
    	<http-method>GET</http-method>
    	<http-method>POST</http-method>
    </cache-mapping>
    <cache-mapping>
    	<url-pattern> /catalog/* </url-pattern>
    	<!-- cache the best selling category; cache the responses to
    	   -- this resource only when the given parameters exist. Cache
    	   -- only when the catalog parameter has 'lilies' or 'roses'
    	   -- but no other catalog varieties:
    	  -- /orchard/catalog?best&category='lilies'
    	  -- /orchard/catalog?best&category='roses'
    	  -- but not the result of
    	   -- /orchard/catalog?best&category='wild'
    	-->
    	<constraint-field name='best' scope='request.parameter'/>
    	<constraint-field name='category' scope='request.parameter'>
    		<value> roses </value>
    		<value> lilies </value>
    	</constraint-field>
    	 <!-- Specify that a particular field is of given range but the
    	   -- field doesn't need to be present in all the requests -->
    	<constraint-field name='SKUnum' scope='request.parameter'>
    		<value match-expr='in-range'> 1000 - 2000 </value>
    	</constraint-field>
    	<!-- cache when the category matches with any value other than
    	   -- a specific value -->
    	<constraint-field name="category" scope="request.parameter>
    		<value match-expr="equals" cache-on-match-failure="true">
           bogus
    		</value>
    	</constraint-field>
    </cache-mapping>
    <cache-mapping>
    	<servlet-name> InfoServlet </servlet-name>
    	<cache-helper-ref>myHelper</cache-helper-ref>
    </cache-mapping>
    </cache>

For more information about the `sun-web.xml` caching settings, see cache.

### CacheKeyGenerator Interface

The built-in default `CacheHelper` implementation allows web applications to customize the key generation. An application component (in a servlet or JSP) can set up a custom `CacheKeyGenerator` implementation as an attribute in the `ServletContext`.

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.

## About the Servlet Engine

Servlets exist in and are managed by the servlet engine in the Application Server. The servlet engine is an internal object that handles all servlet meta functions. These functions include instantiation, initialization, destruction, access from other components, and configuration management. This section covers the following topics:

- Instantiating and Removing Servlets

- Request Handling

### Instantiating and Removing Servlets

After the servlet engine instantiates the servlet, the servlet engine calls the servlet’s `init()` method to perform any necessary initialization. You can override this method to perform an initialization function for the servlet’s life, such as initializing a counter.

When a servlet is removed from service, the servlet engine calls the `destroy()` method in the servlet so that the servlet can perform any final tasks and deallocate resources. You can override this method to write log messages or clean up any lingering connections that won’t be caught in garbage collection.

### Request Handling

When a request is made, the Application Server hands the incoming data to the servlet engine. The servlet engine processes the request’s input data, such as form data, cookies, session information, and URL name-value pairs, into an `HttpServletRequest` request object type.

The servlet engine also creates an `HttpServletResponse` response object type. The engine then passes both as parameters to the servlet’s `service()` method.

In an HTTP servlet, the default `service()` method routes requests to another method based on the HTTP transfer method: `POST`, `GET`, `DELETE`, `HEAD`, `OPTIONS`, `PUT`, or `TRACE`. For example, HTTP `POST` requests are sent to the `doPost()` method, HTTP `GET` requests are sent to the `doGet()` method, and so on. This enables the servlet to process request data differently, depending on which transfer method is used. Since the routing takes place in the service method, you generally do not override `service()` in an HTTP servlet. Instead, override `doGet()`, `doPost()`, and so on, depending on the request type you expect.

To perform the tasks to answer a request, override the `service()` method for generic servlets, and the `doGet()` or `doPost()` methods for HTTP servlets. Very often, this means accessing EJB components to perform business transactions, then collating the information in the request object or in a JDBC `ResultSet` object.

- Previous: Introducing Web Applications
- Next: Using JavaServer Pages

- © 2010, Oracle Corporation and/or its affiliates