This chapter describes how web applications are supported in the Sun Java System Application Server and includes the following sections:
For general information about web applications, see “Part One: The Web Tier” in the Java EE 5 Tutorial.
Application Server supports the Java Servlet Specification version 2.5.
Servlet API version 2.5 is fully backward compatible with versions 2.3 and 2.4, 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 9 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:
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 8–1 URL Fields for Servlets Within an Application
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"/>
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 Admin Console, select the Application Server component, and the Logging tab, then check or uncheck this box:
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, click the Help button in the Admin Console from the Logging page.
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.
A servlet that uses caching is not portable.
For Javadoc tool pages relevant to caching servlet results, go to http://glassfish.dev.java.net/nonav/javaee5/api/index.html and click on the com.sun.appserv.web.cache package.
For information about JSP caching, see JSP Caching.
The rest of this section covers the following topics:
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 The 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 cache-mapping in Sun Java System Application Server Platform Edition 9 Application Deployment Guide and dispatcher in Sun Java System Application Server Platform Edition 9 Application Deployment Guide. These are elements in the sun-web.xml file.
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.
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 in Sun Java System Application Server Platform Edition 9 Application Deployment Guide.
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 in Sun Java System Application Server Platform Edition 9 Application Deployment Guide.
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:
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.
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.
The Application Server supports the following JSP features:
JavaServer Pages (JSP) Specification version 2.1
Precompilation of JSP files, which is especially useful for production servers
JSP tag libraries and standard portable tags
For information about creating JSP files, see Sun Microsystem’s JavaServer Pages web site at http://java.sun.com/products/jsp/index.html.
For information about Java Beans, see Sun Microsystem’s JavaBeans web page at http://java.sun.com/beans/index.html.
This section describes how to use JavaServer Pages (JSP files) as page templates in an Application Server web application. This section contains the following topics:
Application Server supports tag libraries and standard portable tags. For more information, see the JavaServer Pages Standard Tag Library (JSTL) page at http://java.sun.com/products/jsp/jstl/index.jsp.
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 JavaServerTM 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 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. JSP caching is described in the following topics:
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.
Web applications that use this tag library without bundling it 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>
to this:
<jvm-options> -Dcom.sun.enterprise.taglibs=appserv-jstl.jar,jsf-impl.jar,appserv-tags.jar </jvm-options>
and this:
<jvm-options> -Dcom.sun.enterprise.taglisteners=jsf-impl.jar </jvm-options>
to this:
<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 Platform Edition 9 Administration Reference.
Refer to these tags in JSP files as follows:
<%@ taglib prefix="prefix" uri="Sun ONE Application Server Tags" %>
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>.
JSP caching is available in three different scopes: request, session, and application. The default is application. To use a cache in request scope, a web application must specify the com.sun.appserv.web.taglibs.cache.CacheRequestListener in its web.xml deployment descriptor, as follows:
<listener> <listener-class> com.sun.appserv.web.taglibs.cache.CacheRequestListener </listener-class> </listener>
Likewise, for a web application to utilize a cache in session scope, it must specify the com.sun.appserv.web.taglibs.cache.CacheSessionListener in its web.xml deployment descriptor, as follows:
<listener> <listener-class> com.sun.appserv.web.taglibs.cache.CacheSessionListener </listener-class> </listener>
To utilize a cache in application scope, a web application need not specify any listener. The com.sun.appserv.web.taglibs.cache.CacheContextListener is already specified in the appserv-tags.tld file.
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.
The following table describes attributes for the cache tag.
Table 8–2 The cache Attributes
Attribute |
Default |
Description |
---|---|---|
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. |
|
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. |
|
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. |
|
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. |
|
application |
(optional) The scope of the cache. Can be request, session, or application. See Caching Scope. |
The following example represents a cached JSP file:
<%@ 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>
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.
The following table describes attributes for the flush tag.
Table 8–3 The flush Attributes
Attribute |
Default |
Description |
---|---|---|
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. |
|
application |
(optional) The scope of the cache. Can be request, session, or application. See Caching Scope. |
To flush the entry with key="foobar":
<mypfx:flush key="foobar"/>
To flush the entire cache:
<c:if test="${empty sessionScope.clearCache}"> <mypfx:flush /> </c:if>
Application Server provides the following ways of compiling JSP 2.1 compliant source files into servlets:
JSP files are automatically compiled at runtime.
The asadmin deploy command has a precompilejsp option. For details, see the Sun Java System Application Server Platform Edition 9 Reference Manual.
The sun-appserv-jspc Ant task allows you to precompile JSP files; see The sun-appserv-jspc Task.
The jspc command line tool allows you to precompile JSP files at the command line. For details, see the Sun Java System Application Server Platform Edition 9 Reference Manual.
This chapter describes how to create and manage a session that allows users and transaction information to persist between interactions.
This chapter contains the following sections:
This section covers the following topics:
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. For more about the properties you can configure, see session-properties in Sun Java System Application Server Platform Edition 9 Application Deployment Guide and cookie-properties in Sun Java System Application Server Platform Edition 9 Application Deployment Guide.
For information about configuring default session properties for the entire web container, see Chapter 7, Java EE Containers, in Sun Java System Application Server Platform Edition 9 Administration Guide.
Make sure that multiple threads don’t simultaneously modify the same session object in conflicting ways.
This is especially likely to occur in web applications that use HTML frames where multiple servlets are executing simultaneously on behalf of the same client. A good solution is to ensure that one of the servlets modifies the session and the others have read-only access.
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.
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, the default
The file Persistence Type, which uses a file to store session data
If the session manager configuration contains an error, the error is written to the server log and the default (memory) configuration is used.
For more information, see session-manager in Sun Java System Application Server Platform Edition 9 Application Deployment Guide.
This persistence type is not designed for a production environment that requires session persistence. 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.
To specify the memory persistence type for the entire web container, use the configure-ha-persistence command. For details, see the Sun Java System Application Server Platform Edition 9 Reference Manual.
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 availability settings for the web application.
<sun-web-app> ... <session-config> <session-manager persistence-type=memory /> <manager-properties> <property name="sessionFilename" value="sessionstate" /> </manager-properties> </session-manager> ... </session-config> ... </sun-web-app>
The only manager property that the memory persistence type supports is sessionFilename, which is listed under manager-properties in Sun Java System Application Server Platform Edition 9 Application Deployment Guide.
For more information about the sun-web.xml file, see The sun-web.xml File in Sun Java System Application Server Platform Edition 9 Application Deployment Guide.
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. However, it is useful for a development system with a single server instance.
Make sure the delete option is set in the server.policy file, or expired file-based sessions might not be deleted properly. For more information about server.policy, see The server.policy File.
To specify the file persistence type for the entire web container, use the configure-ha-persistence command. For details, see the Sun Java System Application Server Platform Edition 9 Reference Manual.
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 availability 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>
The file persistence type supports all the manager properties listed under manager-properties in Sun Java System Application Server Platform Edition 9 Application Deployment Guide except sessionFilename, and supports the directory store property listed under store-properties in Sun Java System Application Server Platform Edition 9 Application Deployment Guide.
For more information about the sun-web.xml file, see The sun-web.xml File in Sun Java System Application Server Platform Edition 9 Application Deployment Guide.
This section includes summaries of the following topics:
This section covers internationalization as it applies to the following:
To set the default locale of the entire Application Server, which determines the locale of the Admin Console, the logs, and so on, use the Admin Console. Select the Application Server component, the Advanced tab, and the Domain Attributes tab, then type a value in the Locale field. For details, click the Help button in the Admin Console.
This section explains how the Application Server determines the character encoding for the servlet request and the servlet response. For encodings you can use, see http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html.
When processing a servlet request, the server uses the following order of precedence, first to last, to determine the request character encoding:
A hidden field in the form, specified by the form-hint-field attribute of the parameter-encoding element in the sun-web.xml file
The default-charset attribute of the parameter-encoding element in the sun-web.xml file
The default, which is ISO-8859-1
For details about the parameter-encoding element, see parameter-encoding in Sun Java System Application Server Platform Edition 9 Application Deployment Guide.
When processing a servlet response, the server uses the following order of precedence, first to last, to determine the response character encoding:
The default, which is ISO-8859-1
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 Application Server, a default virtual server is created. You can also assign a default virtual server to each new HTTP listener you create. Open the HTTP Service component under the relevant configuration in the Admin Console, select HTTP Listeners, and select or create an HTTP listener. Then select from the Default Virtual Server drop-down list. For details, click the Help button in the Admin Console.
Web applications and Java EE applications containing web components can be assigned to virtual servers.
Deploy the application or web module and assign the desired virtual server to it.
For more information, see Sun Java System Application Server Platform Edition 9 Application Deployment Guide.
In the Admin Console, open the HTTP Service component under the relevant configuration.
Open the Virtual Servers component under the HTTP Service component.
Select the virtual server to which you want to assign a default web module.
Select the application or web module from the Default Web Module drop-down list.
For more information, see Default Web Modules.
For details, click the Help button in the Admin Console from the Virtual Servers page.
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:
http://myvserver:3184/
A virtual server with no default web module assigned serves HTML or JavaServer PagesTM (JSPTM) 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.
For example:
http://myvserver:3184/hellothere.jsp
The Servlet specification recommends that the Web class loader look in the local class loader before delegating to its parent. To make the Web class loader 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 class loader to delegate in the same manner as the other class loaders. 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 in Sun Java System Application Server Platform Edition 9 Application Deployment Guide.
For general information about class loaders, see Chapter 2, Class Loaders.
You can use the default-web.xml file to define features such as filters and security constraints that apply to all web applications.
The mime-mapping elements in default-web.xml are global and inherited by all web applications. You can override these mappings or define your own using mime-mapping elements in your web application's web.xml file. For more information about mime-mapping elements, see the Servlet specification.
Place the JAR file for the filter, security constraint, or other feature in the domain-dir/lib directory.
Edit the domain-dir/config/default-web.xml file to refer to the JAR file.
Restart the server.
For information about configuring logging and monitoring in the web container using the Admin Console, click the Help button in the Admin Console from the Logging or Monitor tab on the Application Server page.
In all Editions of the Application Server, the Enumeration from request.getHeaders() contains multiple elements (one element per request header) instead of a single, aggregated value.
The header names used in HttpServletResponse.addXXXHeader() and HttpServletResponse.setXXXHeader() are returned as they were created.
You can specify that a request for an old URL is treated as a request for a new URL. This is called redirecting a URL.
To specify a redirected URL for a virtual server, use the redirect_n property, where n is a positive integer that allows specification of more than one. This property is a subelement of a virtual-server element in the domain.xml file. For more information about this element, see virtual-server in Sun Java System Application Server Platform Edition 9 Administration Reference. Each of these redirect_n properties is inherited by all web applications deployed on the virtual server.
The value of each redirect_n property has two components, which may be specified in any order:
The first component, from, specifies the prefix of the requested URI to match.
The second component, url-prefix, specifies the new URL prefix to return to the client. The from prefix is simply replaced by this URL prefix.
For example:
<property name="redirect_1" value="from=/dummy url-prefix=http://etude"/> |