Chapter 6 Developing Web Applications

This chapter describes how web applications are supported in the Sun Java System Application Server and includes the following sections:

Introducing Web Applications

Internationalization Issues

The Server

To set the default locale of the entire Sun Java System Application Server, which determines the locale of the Administration Console, the logs, and so on, use the Administration Console. Select the Domain component, and type a value in the Locale field. For details, see the Sun Java System Application Server Administration Guide.

Servlets

This section explains how the Sun Java System Application Server determines the character encoding for the servlet request and the servlet response. For encodings you can use, see:

Servlet Request

When processing a servlet request, the server uses the following order of precedence, first to last, to determine the request character encoding:

Servlet Response

When processing a servlet response, the server uses the following order of precedence, first to last, to determine the response character encoding:

Virtual Servers

A virtual server, also called a virtual host, is a virtual web server that serves content targeted for a specific URL. Multiple virtual servers can serve content using the same or different host names, port numbers, or IP addresses. The HTTP service directs incoming web requests to different virtual servers based on the URL.

When you first install the Sun Java System Application Server, a default virtual server is created. (You can also assign a default virtual server to each new HTTP listener you create. For details, see the Sun Java System Application Server Administration Guide.)

Web applications and J2EE applications containing web components can be assigned to virtual servers. You can use the Administration Console to assign virtual servers:

Default Web Modules

A default web module can be assigned to the default virtual server and to each new virtual server. For details, see Virtual Servers. To access the default web module for a virtual server, point the browser to the URL for the virtual server, but do not supply a context root. For example:

A virtual server with no default web module assigned serves HTML or JSP content from its document root, which is usually domain_dir/docroot. To access this HTML or JSP content, point your browser to the URL for the virtual server, do not supply a context root, but specify the target file.

Classloader Delegation

The Servlet specification recommends that the Web Classloader look in the local classloader before delegating to its parent. To make the Web Classloader follow the delegation model in the Servlet specification, set delegate="false" in the class-loader element of the sun-web.xml file. It’s safe to do this only for a web module that does not interact with any other modules.

The default value is delegate="true", which causes the Web Classloader to delegate in the same manner as the other classloaders. Use delegate="true" for a web application that accesses EJB components or that acts as a web service client or endpoint. For details about sun-web.xml, see “The sun-web.xml File” on page 125.

Using the default-web.xml File

You can use the default-web.xml file to define features such as filters and security constraints that apply to all web applications, as follows:

The InvokerServlet allows use of the servlet-name instead of the servlet-mapping for invoking a servlet with a URL, as described in Invoking a Servlet with a URL. The InvokerServlet is commented out in the default-web.xml file. To re-enable the InvokerServlet, remove the comment indicators (), then restart the server.

Configuring Logging in the Web Container

For information about configuring logging and monitoring in the web container using the Administration Console, see the Sun Java System Application Server Administration Guide.

Configuring HTML Error Pages

To specify an error page (or URL to an error page) to be displayed to the end user, use the error-url attribute of the sun-web-app element in the sun-web.xml file. For example:

<sun-web-app error-url="webserver_install_dir/error/error1.html">
... subelements ...
</sun-web-app>

If the error-url attribute is specified, it overrides all other mechanisms configured for error reporting.

The Sun Java System Application Server provides the following options for specifying the error page.


Note	This attribute should not point to a URL on the Application Server instance, because the error-url cannot be loaded if the server is down. Instead, specify a URL that points to a location on the web server.

Using Servlets

Sun Java System Application Server supports the Java Servlet Specification version 2.4.

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:

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

Invoking a Servlet with a URL

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


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

Table 6-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:

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

Servlet Output

By default, the System.out and System.err output of servlets are sent to the server log, and during start-up 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:

For more information, see the Sun Java System Application Server Administration Guide.

Caching Servlet Results

The Sun Java System 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 Sun Java System Application Server caches the request results for a specific amount of time. In this way, if another data call occurs, the Sun Java System 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 a Sun Java System Application Server web application handles response caching, you edit specific fields in the sun-web.xml file.

Caching Features

Sun Java System Application Server 8 has the following web application response caching capabilities:


Note	A servlet that uses caching is not portable.

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 cache helper class. 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. See CacheHelper Interface.

To determine cache key generation programmatically, write a cache key generator class. 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

<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>
    
    <constraint-field name='best' scope='request.parameter'/>
    <constraint-field name='category' scope='request.parameter'>
      <value> roses </value>
      <value> lilies </value>
    </constraint-field>
    
    <constraint-field name='SKUnum' scope='request.parameter'>
      <value match-expr='in-range'> 1000 - 2000 </value>
    </constraint-field>
    
    <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>

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 =
                  "com.sun.appserv.web.cachedServletName";
  public static final String ATTR_CACHE_MAPPED_URL_PATTERN =
                  "com.sun.appserv.web.cachedURLPattern";

  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 cachebale?
   * @param request incoming <code>HttpServletRequest</code> object
   * @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 be refreshed?
   * @param request incoming <code>HttpServletRequest</code> object
   * @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.
   * @param request incoming <code>HttpServletRequest</code> object
   * @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 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” on page 161.

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
   * @param request incoming <code>HttpServletRequest</code>
   * @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);
}

About the Servlet Engine

Servlets exist in and are managed by the servlet engine in the Sun Java System 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

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 Sun Java System 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.

Servlets and Threads

By default, each new request is processed in its own thread. For servlets, this is less resource intensive than instantiating a new servlet copy in memory for each request.

Avoid threading issues, since each thread operates in the same memory space where servlet object variables can overwrite each other. Servlets should be programmed so that they are thread-safe, so that a single servlet instance can handle multiple simultaneous requests.

If a servlet is specifically written as a single thread, the servlet engine creates a pool of servlet instances to be used for incoming requests. If a request arrives when all instances are busy, it is queued until an instance becomes available. The number of pool instances is configurable in the sun-web.xml file, in the singleThreadedServletPoolSize property of the sun-web-app element.

Using JavaServer Pages

For information about creating JSP pages, see Sun Microsystem’s JavaServer Pages web site at:

For information about Java Beans, see Sun Microsystem’s JavaBeans web page at:

This section describes how to use JavaServer Pages (JSP pages) as page templates in a Sun Java System Application Server web application. This section contains the following topics:

JSP Tag Libraries and Standard Portable Tags

Sun Java System Application Server supports tag libraries and standard portable tags. For more information, see the JavaServer Pages Standard Tag Library (JSTL) page:

Web applications don’t need to bundle copies of the jsf-impl.jar or appserv-jstl.jar JSP tag libraries (in install_dir/lib) to use JavaServer™ Faces technology or JSTL, respectively. These tag libraries are automatically available to all web applications.

However, the install_dir/lib/appserv-tags.jar tag library for JSP caching is not automatically available to web applications. See JSP Caching, next.

JSP Caching

JSP caching lets you cache tag invocation results within the Java engine. Each can be cached using different cache criteria. For example, suppose you have invocations to view stock quotes, weather information, and so on. The stock quote result can be cached for 10 minutes, the weather report result for 30 minutes, and so on.

For more information about response caching as it pertains to servlets, see Caching Servlet Results.

JSP caching is implemented by a tag library packaged into the install_dir/lib/appserv-tags.jar file, which you can copy into the WEB-INF/lib directory of your web application. The appserv-tags.tld tag library descriptor file is in the META-INF directory of this JAR file.


Note	Web applications that use this tag library are not portable.

To allow all web applications to share this tag library, change the following elements in the domain.xml file. Change this:

<jvm-options>-Dcom.sun.enterprise.taglibs=appserv-jstl.jar,jsf-impl.jar</jvm-options>

<jvm-options>-Dcom.sun.enterprise.taglibs=appserv-jstl.jar,jsf-impl.jar,appserv-tags.jar </jvm-options>

<jvm-options>-Dcom.sun.enterprise.taglisteners=jsf-impl.jar,appserv-tags.jar</jvm-options>

For more information about the domain.xml file, see the Sun Java System Application Server Reference.

Subsequently, the cache tags are available as <prefix:cache> and <prefix:flush>. For example, if your prefix is mypfx, the cache tags are available as <mypfx:cache> and <mypfx:flush>.

cache

The cache tag caches the body between the beginning and ending tags according to the attributes specified. The first time the tag is encountered, the body content is executed and cached. Each subsequent time it is run, the cached content is checked to see if it needs to be refreshed and if so, it is executed again, and the cached data is refreshed. Otherwise, the cached data is served.

Attributes

Table 6-2 cache Attributes
Attribute	Default	Description
key	ServletPath_Suffix	(optional) The name used by the container to access the cached entry. The cache key is suffixed to the servlet path to generate a key to access the cached entry. If no key is specified, a number is generated according to the position of the tag in the page.
timeout	60s	(optional) The time in seconds after which the body of the tag is executed and the cache is refreshed. By default, this value is interpreted in seconds. To specify a different unit of time, add a suffix to the timeout value as follows: s for seconds, m for minutes, h for hours, d for days. For example, 2h specifies two hours.
nocache	false	(optional) If set to true, the body content is executed and served as if there were no cache tag. This offers a way to programmatically decide whether the cached response is sent or whether the body has to be executed, though the response is not cached.
refresh	false	(optional) If set to true, the body content is executed and the response is cached again. This lets you programmatically refresh the cache immediately regardless of the timeout setting.

Example

<%@ taglib prefix="mypfx" uri="Sun ONE Application Server Tags" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>

<mypfx:cache         key="${sessionScope.loginId}"
        nocache="${param.nocache}"
        refresh="${param.refresh}"
        timeout="10m">
  <c:choose>
    <c:when test="${param.page == 'frontPage'}">
      <%-- get headlines from database --%>
    </c:when>
    <c:otherwise>
      ...
    </c:otherwise>
  </c:choose>
</mypfx:cache>

<mypfx:cache timeout="1h">
<h2> Local News </h2>
<%-- get the headline news and cache them --%>
</mypfx:cache>

flush

Forces the cache to be flushed. If a key is specified, only the entry with that key is flushed. If no key is specified, the entire cache is flushed.

Attributes

Table 6-3 flush Attributes
Attribute	Default	Description
key	ServletPath_Suffix	(optional) The name used by the container to access the cached entry. The cache key is suffixed to the servlet path to generate a key to access the cached entry. If no key is specified, a number is generated according to the position of the tag in the page.

Examples

Compiling JSP Pages: The Command-Line Compiler

Sun Java System Application Server provides the following ways of compiling JSP 2.0 compliant source files into servlets:

The jspc command line tool is located under install_dir/bin (make sure this directory is in your path). The format of the jspc command is as follows:

Table 6-4 File Specifiers for the jspc Command
File Specifier	Description
files	One or more JSP files to be compiled.
-webapp dir	A directory containing a web application. All JSP pages in the directory and its subdirectories are compiled. You cannot specify a WAR, JAR, or ZIP file; you must first extract it to an open directory structure.
-uriroot dir	Same as -webapp.

Table 6-5 jspc Options
Option	Description
-d dir	Specifies the output directory for the compiled JSP pages. Package directories are automatically generated based on the directories containing the uncompiled JSP pages. The default is the directory specified by the java.io.tmpdir system property, or the current directory if this property is undefined.
-p name	Specifies the name of the target package for all specified JSP pages, which is prepended to the package component derived from the directory in which the JSP pages are located. The default is org.apache.jsp.
-c name	Specifies the target class name of the first JSP compiled. Subsequent JSP pages are unaffected. Useful only with the files file specifier.
-v	Enables verbose mode.
-mapped	Generates separate write calls for each HTML line and comments that describe the location of each line in the JSP file. By default, all adjacent write calls are combined and no location comments are generated.
-die [code]	Returns the error number specified by code if an error occurs. If the code is absent or unparseable it defaults to 1. If the code is not 0, any exception during precompilation causes a call to java.lang.System.exit() with the specified code.
-webinc file	Creates partial servlet mappings for the -webapp option, which can be pasted into a web.xml file.
-webxml file	Creates an entire web.xml file for the -webapp option.
-ieplugin class_id	Specifies the Java plug-in COM class ID for Internet Explorer. Used by the <jsp:plugin> tags.
-xpoweredBy	Causes an X-Powered-By: JSP/2.0 response header to be added to JSP generated responses. This is useful for gathering statistical information about JSP technology.
-trimSpaces	Trims spaces in template text between actions and directives.

For example, this command compiles all the JSP files in the web application under webappdir into class files under webappdir/classes and creates the web.xml file:

To use these precompiled JSP pages in a web application, put the classes under webappdir/classes into a JAR file, place the JAR file under WEB-INF/lib, and and copy the generated web.xml file to WEB-INF/web.xml.

The presence of both the precompiled classes and the servlet mappings in web.xml prevents the JSP compiler from being invoked when the JSP page is accessed.

Creating and Managing User Sessions

This chapter describes how to create and manage a session that allows users and transaction information to persist between interactions.

Configuring Sessions

To configure whether and how sessions use cookies and URL rewriting, edit the session-properties and cookie-properties elements in the sun-web.xml file for an individual web application. See “session-properties” on page 216 and “cookie-properties” on page 160 for more about the properties you can configure.

For information about configuring default session properties for the entire web container, see the Sun Java System Application Server Administration Guide.

Session Managers

A session manager automatically creates new session objects whenever a new session starts. In some circumstances, clients do not join the session, for example, if the session manager uses cookies and the client does not accept cookies.

Sun Java System Application Server offers these session management options, determined by the session-manager element’s persistence-type attribute in the sun-web.xml file:

The memory Persistence Type

This persistence type is not designed for a production environment. It provides no session persistence. However, you can configure it so that the session state in memory is written to the file system prior to server shutdown.


Note	If the session manager configuration contains an error, the error is written to the server log and the default (memory) configuration is used.

To specify the memory persistence type for the entire web container, use the configure-ha-persistence command. For details, see the Utility Reference.

To specify the memory persistence type for a specific web application, edit the sun-web.xml file as in the following example. The persistence-type property is optional, but must be set to memory if included. This overrides the web container settings for the web application.

<sun-web-app>
  ...
  <session-config>
    <session-manager persistence-type=memory>
      <manager-properties>
        <property name="reapIntervalSeconds" value="20" />
      </manager-properties>
    </session-manager>
    ...
  </session-config>
  ...
</sun-web-app>

The file Persistence Type

This persistence type provides session persistence to the local file system, and allows a single server domain to recover the session state after a failure and restart. The session state is persisted in the background, and the rate at which this occurs is configurable. The store also provides passivation and activation of the session state to help control the amount of memory used. This option is not supported in a production environment.

To specify the file persistence type for the entire web container, use the configure-ha-persistence command. For details, see the Utility Reference.

To specify the file persistence type for a specific web application, edit the sun-web.xml file as in the following example. Note that persistence-type must be set to file. This overrides the web container settings for the web application.

<sun-web-app>
  ...
  <session-config>
    <session-manager persistence-type=file>
      <store-properties>
        <property name=directory value=sessiondir />
      </store-properties>
    </session-manager>
    ...
  </session-config>
  ...
</sun-web-app>

Previous Contents Index Next
Sun Java System Application Server Platform Edition 2004Q4 Beta Developer's Guide