Previous      Contents      Index      Next
Sun Java System Application Server Platform Edition 8 Developer's Guide

Chapter 5
Deployment Descriptor Files

This chapter describes deployment descriptor files specific to Sun Java System Application Server in the following sections:

Sun Java System Application Server Descriptors
The sun-application.xml File
The sun-web.xml File
The sun-ejb-jar.xml File
The sun-cmp-mappings.xml File
The sun-application-client.xml file
The sun-acc.xml File
Web Service Elements

---

Sun Java System Application Server Descriptors

Sun Java System Application Server uses deployment descriptors in addition to the J2EE standard descriptors for configuring features specific to the Sun Java System Application Server. The sun-application.xml and sun-web.xml files are optional; all the others are required.

Each deployment descriptor (or XML) file has a corresponding schema (or DTD) file, which defines the elements, data, and attributes that the deployment descriptor file can contain. For example, the sun-application_1_4-0.dtd schema file defines the structure of the sun-application.xml file. All of the DTD files are located in the install_dir/lib/dtds directory.

Note	Do not edit the DTD files; their contents change only with new versions of Sun Java System Application Server.

For general information about DTD files and XML, see the XML specification at:

http://www.w3.org/TR/REC-xml

The following table lists the Sun Java System Application Server deployment descriptors and their DTD schema files.

Table 5-1  Sun Java System Application Server Descriptors 

Deployment Descriptor	DTD Schema File	Description
sun-application.xml	sun-application_1_4-0.dtd	Configures an entire J2EE application (EAR file).
sun-web.xml	sun-web-app_2_4-0.dtd	Configures a web application (WAR file).
sun-ejb-jar.xml	sun-ejb-jar_2_1-0.dtd	Configures an enterprise bean (EJB JAR file).
sun-cmp-mappings.xml	sun-cmp-mapping_1_1.dtd	Configures container-managed persistence for an enterprise bean.
sun-application-client.xml	sun-application-client_1_4-0.dtd	Configures an Application Client Container (ACC) client (JAR file).
sun-acc.xml	sun-application-client-container_1_0.dtd	Configures the Application Client Container.

Note	The Sun Java System Application Server deployment descriptors must be readable and writable by the file owners. In each deployment descriptor file, subelements must be defined in the order in which they are listed under each Subelements heading unless otherwise noted.

---

The sun-application.xml File

This section describes the XML elements in the sun-application.xml file and provides an example file in the following sections:

sun-application
web
web-uri
context-root
pass-by-reference
unique-id
security-role-mapping
role-name
principal-name
group-name
realm
Sample sun-application.xml File

sun-application

Defines Sun Java System Application Server specific configuration for an application. This is the root element; there can only be one sun-application element in a sun-application.xml file.

Subelements

The following table describes subelements for the sun-application element.

Table 5-2  sun-application Subelements 

Element	Required	Description
web	zero or more	Specifies the application’s web tier configuration.
pass-by-reference	zero or one	Determines whether EJB modules use pass-by-value or pass-by-reference semantics.
unique-id	zero or one	Contains the unique ID for the application.
security-role-mapping	zero or more	Maps a role in the corresponding J2EE XML file to a user or group.
realm	zero or one	Specifies an authentication realm.

web

Specifies the application’s web tier configuration.

Subelements

The following table describes subelements for the web element.

Table 5-3  web Subelements 

Element	Required	Description
web-uri	only one	Contains the web URI for the application.
context-root	only one	Contains the web context root for the application.

web-uri

Contains the web URI for the application. Must match the corresponding element in the application.xml file.

Subelements

none

context-root

Contains the web context root for the application. Overrides the corresponding element in the application.xml file.

If you are setting up load balancing, web module context roots must be unique within a cluster. See the Sun Java System Application Server Administration Guide for more information about load balancing.

Subelements

none

pass-by-reference

Specifies the passing method used by a servlet or enterprise bean calling a remote interface method in another bean that is co-located within the same process.

If false (the default if this element is not present), this application uses pass-by-value semantics.
If true, this application uses pass-by-reference semantics.

Note	The pass-by-reference element only applies to remote calls. As defined in the EJB 2.1 specification, section 5.4, calls to local interfaces use pass-by-reference semantics. If the pass-by-reference element is set to its default value of false, the passing semantics for calls to remote interfaces comply with the EJB 2.1 specification, section 5.4. If set to true, remote calls involve pass-by-reference semantics instead of pass-by-value semantics, contrary to this specification. Portable programs should not assume that a copy of the object is made during such a call, and thus that it’s safe to modify the original. Nor should they assume that a copy is not made, and thus that changes to the object are visible to both caller and callee. When this element is set to true, parameters and return values should be considered read-only. The behavior of a program that modifies such parameters or return values is undefined.

When a servlet or enterprise bean calls a remote interface method in another bean that is co-located within the same process, by default the Sun Java System Application Server makes copies of all the call parameters in order to preserve the pass-by-value semantics. This increases the call overhead and decreases performance.

However, if the calling method does not mutate the object being passed as a parameter, it is safe to pass the object itself without making a copy of it. To do this, set the pass-by-reference value to true.

The setting of this element in the sun-application.xml file applies to all EJB modules in the application. For an individually deployed EJB module, you can set the same element in the sun-ejb-jar.xml file. If you want to use pass-by-reference at both the bean and application level, the bean level takes precedence. For more information about the sun-ejb-jar.xml file, see The sun-ejb-jar.xml File.

Subelements

none

unique-id

Contains the unique ID for the application. This value is automatically updated each time the application is deployed or redeployed. Do not edit this value.

Subelements

none

security-role-mapping

Maps roles to users and groups. At least one principal or group name is required, but you do not need to have one of each.

Subelements

The following table describes subelements for the security-role-mapping element.

Table 5-4  security-role-mapping Subelements 

Element	Required	Description
role-name	only one	Contains the role-name in the security-role element of the application.xml file.
principal-name	one or more if no group-name, otherwise zero or more	Contains the principal (user) name.
group-name	one or more if no principal-name, otherwise zero or more	Contains the group name.

role-name

Contains the role-name in the security-role element of the application.xml file.

Subelements

none

principal-name

Contains the principal (user) name.

Subelements

none

group-name

Contains the group name.

Subelements

none

realm

Contains the name of the realm used to process all authentication requests associated with this application. If this element is not specified or does not match the name of a configured realm, the default realm is used. For more information about realms, see “Realm Configuration” on page 44.

Subelements

none

Sample sun-application.xml File

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE sun-application PUBLIC '-//Sun Microsystems, Inc.//DTD Application Server 8.0 J2EE Application 1.4//EN' 'http://www.sun.com/software/appserver/dtds/sun-application_1_4-0.dtd'>

<sun-application>

  <unique-id>67488732739338240</unique-id>

</sun-application>

---

The sun-web.xml File

This section describes the XML elements in the sun-web.xml file and provides an example file in the following sections:

General Elements
Security Elements
Session Elements
Reference Elements
Caching Elements
Classloader Elements
JSP Elements
Internationalization Elements
Web Service Elements
Sample sun-web.xml File

General Elements

General elements are as follows:

sun-web-app
property
description
context-root

sun-web-app

Defines Sun Java System Application Server specific configuration for a web module. This is the root element; there can only be one sun-web-app element in a sun-web.xml file.

Subelements

The following table describes subelements for the sun-web-app element.

Table 5-5  sun-web-app Subelements 

Element	Required	Description
context-root	zero or one	Contains the web context root for the web application.
security-role-mapping	zero or more	Maps roles to users or groups in the currently active realm.
servlet	zero or more	Specifies a principal name for a servlet, which is used for the run-as role defined in web.xml.
session-config	zero or one	Specifies session manager, session cookie, and other session-related information.
ejb-ref	zero or more	Maps the absolute JNDI name to the ejb-ref in the corresponding J2EE XML file.
resource-ref	zero or more	Maps the absolute JNDI name to the resource-ref in the corresponding J2EE XML file.
resource-env-ref	zero or more	Maps the absolute JNDI name to the resource-env-ref in the corresponding J2EE XML file.
service-ref	zero or more	Specifies runtime settings for a web service reference.
cache	zero or one	Configures caching for web application components.
class-loader	zero or one	Specifies classloader configuration information.
jsp-config	zero or one	Specifies JSP configuration information.
locale-charset-info	zero or one	Specifies internationalization settings.
property	zero or more	Specifies a property, which has a name and a value.
message-destination	zero or more	Specifies the name of a logical message destination.
webservice-description	zero or more	Specifies a name and optional publish location for a web service.

Attributes

none

Properties

The following table describes properties for the sun-web-app element.

Table 5-6  sun-web-app Properties 

Property	Default	Description
crossContextAllowed	true	If true, allows this web application to access the contexts of other web applications using the ServletContext.getContext()method.
tempdir	domain_dir/generated/j2ee-apps/app_name or domain_dir/generated/j2ee-modules/module_name	Specifies a temporary directory for use by this web module. This value is used to construct the value of the javax.servlet.context.tempdir context attribute. Compiled JSPs are also placed in this directory.
singleThreadedServletPoolSize	5	Specifies the maximum number of servlet instances allocated for each SingleThreadModel servlet in the web application.

property

Specifies a property, which has a name and a value. A property adds configuration information to its parent element that is one or both of the following:

Optional with respect to Sun Java System Application Server
Needed by a system or object that Sun Java System Application Server doesn’t have knowledge of, such as an LDAP server or a Java class

For example, a manager-properties element can include property subelements:

<manager-properties>
  <property name="reapIntervalSeconds" value="20" />
</manager-properties>

Which properties a manager-properties element uses depends on the value of the parent session-manager element’s persistence-type attribute. For details, see the description of the session-manager element.

Subelements

The following table describes subelements for the property element.

Table 5-7  property Subelements 

Element	Required	Description
description	zero or one	Specifies an optional text description of a property.

Attributes

The following table describes attributes for the property element.

Table 5-8  property Attributes 

Attribute	Default	Description
name	none	Specifies the name of the property.
value	none	Specifies the value of the property.

description

Contains data that specifies a text description of the containing element.

Subelements

none

Attributes

none

context-root

Contains the web context root for the web application. Overrides the corresponding element in the web.xml file.

If you are setting up load balancing, web module context roots must be unique within a cluster. See the Sun Java System Application Server Administration Guide for more information about load balancing.

Subelements

none

Security Elements

Security elements are as follows:

security-role-mapping
servlet
servlet-name
role-name
principal-name
group-name

security-role-mapping

Maps roles to users or groups in the currently active realm. See “Realm Configuration” on page 44 for how to define the currently active realm.

Subelements

The following table describes subelements for the security-role-mapping element.

Table 5-9  security-role-mapping Subelements 

Element	Required	Description
role-name	only one	Contains the role name.
principal-name	requires at least one principal-name or group-name	Contains a principal (user) name in the current realm.
group-name	requires at least one principal-name or group-name	Contains a group name in the current realm.

Attributes

none

servlet

Specifies a principal name for a servlet, which is used for the run-as role defined in web-xml.

Subelements

The following table describes subelements for the servlet element.

Table 5-10  servlet Subelements 

Element	Required	Description
servlet-name	only one	Contains the name of a servlet, which is matched to a servlet-name in web.xml.
principal-name	zero or one	Contains a principal (user) name in the current realm.
webservice-endpoint	zero or more	Specifies information about a web service endpoint.

Attributes

none

servlet-name

Contains data that specifies the name of a servlet, which is matched to a servlet-name in web.xml. This name must be present in web.xml.

Subelements

none

Attributes

none

role-name

Contains data that specifies the role-name in the security-role element of the web.xml file.

Subelements

none

Attributes

none

principal-name

Contains data that specifies a principal (user) name in the current realm.

Subelements

none

Attributes

none

group-name

Contains data that specifies a group name in the current realm.

Subelements

none

Attributes

none

Session Elements

Session elements are as follows:

session-config
session-manager
manager-properties
store-properties
session-properties
cookie-properties

session-config

Specifies session configuration information. Overrides the web container settings for an individual web application.

Subelements

The following table describes subelements for the session-config element.

Table 5-11  session-config Subelements 

Element	Required	Description
session-manager	zero or one	Specifies session manager configuration information.
session-properties	zero or one	Specifies session properties.
cookie-properties	zero or one	Specifies session cookie properties.

Attributes

none

session-manager

Specifies session manager information.

Subelements

The following table describes subelements for the session-manager element.

Table 5-12  session-manager Subelements 

Element	Required	Description
manager-properties	zero or one	Specifies session manager properties.
store-properties	zero or one	Specifies session persistence (storage) properties.

Attributes

The following table describes attributes for the session-manager element.

Table 5-13  session-manager Attributes 

Attribute	Default	Description
persistence-type	memory	(optional) Specifies the session persistence mechanism. Allowed values are memory and file. The ha and custom values are not implemented and should not be used.

manager-properties

Specifies session manager properties.

Subelements

The following table describes subelements for the manager-properties element.

Table 5-14  manager-properties Subelements 

Element	Required	Description
property	zero or more	Specifies a property, which has a name and a value.

Attributes

none

Properties

The following table describes properties for the manager-properties element.

Table 5-15  manager-properties Properties 

Property	Default	Description
reapIntervalSeconds	60	Specifies the number of seconds between checks for expired sessions. If the persistence-type attribute of the session-manager element is file, sessions are passivated if maxSessions has been exceeded. You should set this value lower than the frequency at which session data changes to prevent data inconsistency. For example, this value should be as low as possible (1 second) for a hit counter servlet on a frequently accessed website, or you could lose the last few hits each time you restart the server.
maxSessions	-1	Specifies the maximum number of sessions that can be in cache, or -1 for no limit. After this, an attempt to create a new session causes an IllegalStateException to be thrown. If the persistence-type attribute of the session-manager element is file, the session manager passivates sessions to the persistent store when this maximum is reached.
sessionFilename	none; state is not preserved across restarts	Specifies the absolute or relative path to the directory in which the session state is preserved between application restarts, if preserving the state is possible. A relative path is relative to the temporary directory for this web application. Applicable only if the persistence-type attribute of the session-manager element is memory.

store-properties

Specifies session persistence (storage) properties.

Subelements

The following table describes subelements for the store-properties element.

Table 5-16  store-properties Subelements 

Element	Required	Description
property	zero or more	Specifies a property, which has a name and a value.

Attributes

none

Properties

The following table describes properties for the store-properties element.

Table 5-17  store-properties Properties 

Property	Default	Description
directory	domain_dir/generated/jsp/j2ee-apps/appname/appname_war	Specifies the absolute or relative pathname of the directory into which individual session files are written. A relative path is relative to the temporary work directory for this web application. Applicable only if the persistence-type attribute of the session-manager element is file.

session-properties

Specifies session properties.

Subelements

The following table describes subelements for the session-properties element.

Table 5-18  session-properties Subelements 

Element	Required	Description
property	zero or more	Specifies a property, which has a name and a value.

Attributes

none

Properties

The following table describes properties for the session-properties element.

Table 5-19  session-properties Properties 

Property	Default	Description
timeoutSeconds	600	Specifies the default maximum inactive interval (in seconds) for all sessions created in this web module. If set to 0 or less, sessions in this web module never expire. If a session-timeout element is specified in the web.xml file, the session-timeout value overrides any timeoutSeconds value. If neither session-timeout nor timeoutSeconds is specified, the timeoutSeconds default is used. Note that the session-timeout element in web.xml is specified in minutes, not seconds.
enableCookies	true	Uses cookies for session tracking if set to true.
enableURLRewriting	true	Enables URL rewriting. This provides session tracking via URL rewriting when the browser does not accept cookies. You must also use an encodeURL or encodeRedirectURL call in the servlet or JSP.
idLengthBytes	16	Specifies the number of bytes in this web module’s session ID.

cookie-properties

Specifies session cookie properties.

Subelements

The following table describes subelements for the cookie-properties element.

Table 5-20  cookie-properties Subelements 

Element	Required	Description
property	zero or more	Specifies a property, which has a name and a value.

Attributes

none

Properties

The following table describes properties for the cookie-properties element.

Table 5-21  cookie-properties Properties 

Property	Default	Description
cookiePath	Context path at which the web module is installed.	Specifies the pathname that is set when the cookie is created. The browser sends the cookie if the pathname for the request contains this pathname. If set to / (slash), the browser sends cookies to all URLs served by the Sun Java System Application Server. You can set the path to a narrower mapping to limit the request URLs to which the browser sends cookies.
cookieMaxAgeSeconds	-1	Specifies the expiration time (in seconds) after which the browser expires the cookie.
cookieDomain	(unset)	Specifies the domain for which the cookie is valid.
cookieComment	Sun Java System Application Server Session Tracking Cookie	Specifies the comment that identifies the session tracking cookie in the cookie file. Applications can provide a more specific comment for the cookie.

Reference Elements

Reference elements are as follows:

resource-env-ref
resource-env-ref-name
resource-ref
res-ref-name
default-resource-principal
name
password
ejb-ref
ejb-ref-name
message-destination
message-destination-name
jndi-name

resource-env-ref

Maps the res-ref-name in the corresponding J2EE web.xml file resource-env-ref entry to the absolute jndi-name of a resource.

Subelements

The following table describes subelements for the resource-env-ref element.

Table 5-22   resource-env-ref Subelements 

Element	Required	Description
resource-env-ref-name	only one	Specifies the res-ref-name in the corresponding J2EE web.xml file resource-env-ref entry.
jndi-name	only one	Specifies the absolute jndi-name of a resource.

Attributes

none

resource-env-ref-name

Contains data that specifies the res-ref-name in the corresponding J2EE web.xml file resource-env-ref entry.

Subelements

none

Attributes

none

resource-ref

Maps the res-ref-name in the corresponding J2EE web.xml file resource-ref entry to the absolute jndi-name of a resource.

Subelements

The following table describes subelements for the resource-ref element.

Table 5-23  resource-ref Subelements 

Element	Required	Description
res-ref-name	only one	Specifies the res-ref-name in the corresponding J2EE web.xml file resource-ref entry.
jndi-name	only one	Specifies the absolute jndi-name of a resource.
default-resource-principal	zero or one	Specifies the default principal (user) for the resource.

Attributes

none

res-ref-name

Contains data that specifies the res-ref-name in the corresponding J2EE web.xml file resource-ref entry.

Subelements

none

Attributes

none

default-resource-principal

Specifies the default principal (user) for the resource.

If this element is used in conjunction with a JMS Connection Factory resource, the name and password subelements must be valid entries in the Sun Java™ System Message Queue broker user repository. See the “Security Management” chapter in the Sun Java System Message Queue Administrator’s Guide for details.

Subelements

The following table describes subelements for the default-resource-principal element.

Table 5-24  default-resource-principal Subelements 

Element	Required	Description
name	only one	Contains the name of the principal.
password	only one	Contains the password for the principal.

Attributes

none

name

Contains data that specifies the name of the principal.

Subelements

none

Attributes

none

password

Contains data that specifies the password for the principal.

Subelements

none

Attributes

none

ejb-ref

Maps the ejb-ref-name in the corresponding J2EE web.xml file ejb-ref entry to the absolute jndi-name of a resource.

Subelements

The following table describes subelements for the ejb-ref element.

Table 5-25   ejb-ref Subelements 

Element	Required	Description
ejb-ref-name	only one	Specifies the ejb-ref-name in the corresponding J2EE web.xml file ejb-ref entry.
jndi-name	only one	Specifies the absolute jndi-name of a resource.

Attributes

none

ejb-ref-name

Contains data that specifies the ejb-ref-name in the corresponding J2EE web.xml file ejb-ref entry.

Subelements

none

Attributes

none

message-destination

Specifies the name of a logical message-destination defined within an application. The message-destination-name matches the corresponding message-destination-name in the web.xml file.

Subelements

The following table describes subelements for the message-destination element.

Table 5-26  message-destination subelements  

Element	Required	Description
message-destination-name	only one	Specifies the name of a logical message destination defined within the corresponding web.xml file.
jndi-name	only one	Specifies the jndi-name of the associated entity.

Attributes

none

message-destination-name

Contains data that specifies the name of a logical message destination defined within the corresponding web.xml file.

Subelements

none

Attributes

none

jndi-name

Contains data that specifies the absolute jndi-name of a URL resource or a resource in the domain.xml file.

Subelements

none

Attributes

none

Caching Elements

For details about response caching as it pertains to servlets and JSP caching, see “Caching Servlet Results” on page 268 and “JSP Caching” on page 276.

Caching elements are as follows:

cache
cache-helper
default-helper
cache-mapping
url-pattern
timeout
http-method
key-field
constraint-field
value

cache

Configures caching for web application components.

Subelements

The following table describes subelements for the cache element.

Table 5-27  cache Subelements 

Element	Required	Description
cache-helper	zero or more	Specifies a custom class that implements the CacheHelper interface.
default-helper	zero or one	Allows you to change the properties of the default, built-in cache-helper class.
property	zero or more	Specifies a cache property, which has a name and a value.
cache-mapping	zero or more	Maps a URL pattern or a servlet name to its cacheability constraints.

Attributes

The following table describes attributes for the cache element.

Table 5-28  cache Attributes 

Attribute	Default	Description
max-entries	4096	(optional) Specifies the maximum number of entries the cache can contain. Must be a positive integer.
timeout-in-seconds	30	(optional) Specifies the maximum amount of time in seconds that an entry can remain in the cache after it is created or refreshed. Can be overridden by a timeout element.
enabled	false	(optional) Determines whether servlet and JSP caching is enabled.

Properties

The following table describes properties for the cache element.

Table 5-29  cache Properties 

Property	Default	Description
cacheClassName	com.sun.appserv.web.cache.LruCache	Specifies the fully qualified name of the class that implements the cache functionality. The cacheClassName Values table below lists possible values.
MultiLRUSegmentSize	4096	Specifies the number of entries in a segment of the cache table that should have its own LRU (least recently used) list. Applicable only if cacheClassName is set to com.sun.appserv.web.cache.MultiLruCache.
MaxSize	unlimited; Long.MAX_VALUE	Specifies an upper bound on the cache memory size in bytes (KB or MB units). Example values are 32 KB or 2 MB. Applicable only if cacheClassName is set to com.sun.appserv.web.cache.BoundedMultiLruCache.

Cache Class Names

The following table lists possible values of the cacheClassName property.

Table 5-30  cacheClassName Values 

Value	Description
com.sun.appserv.web.cache.LruCache	A bounded cache with an LRU (least recently used) cache replacement policy.
com.sun.appserv.web.cache.BaseCache	An unbounded cache suitable if the maximum number of entries is known.
com.sun.appserv.web.cache.MultiLruCache	A cache suitable for a large number of entries (>4096). Uses the MultiLRUSegmentSize property.
com.sun.appserv.web.cache.BoundedMultiLruCache	A cache suitable for limiting the cache size by memory rather than number of entries. Uses the MaxSize property.

cache-helper

Specifies a class that implements the CacheHelper interface. For details, see “CacheHelper Interface” on page 271.

Subelements

The following table describes subelements for the cache-helper element.

Table 5-31  cache-helper Subelements 

Element	Required	Description
property	zero or more	Specifies a property, which has a name and a value.

Attributes

The following table describes attributes for the cache-helper element.

Table 5-32  cache-helper Attributes 

Attribute	Default	Description
name	default	Specifies a unique name for the helper class, which is referenced in the cache-mapping element.
class-name	none	Specifies the fully qualified class name of the cache helper, which must implement the com.sun.appserv.web.CacheHelper interface.

default-helper

Allows you to change the properties of the built-in default cache-helper class.

Subelements

The following table describes subelements for the default-helper element.

Table 5-33  default-helper Subelements 

Element	Required	Description
property	zero or more	Specifies a property, which has a name and a value.

Attributes

none

Properties

The following table describes properties for the default-helper element.

Table 5-34  default-helper Properties 

Property	Default	Description
cacheKeyGeneratorAttrName	Uses the built-in default cache-helper key generation, which concatenates the servlet path with key-field values, if any.	The caching engine looks in the ServletContext for an attribute with a name equal to the value specified for this property to determine whether a customized CacheKeyGenerator implementation is used. An application may provide a customized key generator rather than using the default helper. See “CacheKeyGenerator Interface” on page 273.

cache-mapping

Maps a URL pattern or a servlet name to its cacheability constraints.

Subelements

The following table describes subelements for the cache-mapping element.

Table 5-35  cache-mapping Subelements 

Element	Required	Description
servlet-name	requires one servlet-name or url-pattern	Contains the name of a servlet.
url-pattern	requires one servlet-name or url-pattern	Contains a servlet URL pattern for which caching is enabled.
cache-helper-ref	required if timeout, refresh-field, http-method, key-field, and constraint-field are not used	Contains the name of the cache-helper used by the parent cache-mapping element.
timeout	zero or one if cache-helper-ref is not used	Contains the cache-mapping specific maximum amount of time in seconds that an entry can remain in the cache after it is created or refreshed.
refresh-field	zero or one if cache-helper-ref is not used	Specifies a field that gives the application component a programmatic way to refresh a cached entry.
http-method	zero or more if cache-helper-ref is not used	Contains an HTTP method that is eligible for caching.
key-field	zero or more if cache-helper-ref is not used	Specifies a component of the key used to look up and extract cache entries.
constraint-field	zero or more if cache-helper-ref is not used	Specifies a cacheability constraint for the given url-pattern or servlet-name.

Attributes

none

url-pattern

Contains data that specifies a servlet URL pattern for which caching is enabled. See the Servlet 2.3 specification section SRV. 11.2 for applicable patterns.

Subelements

none

Attributes

none

cache-helper-ref

Contains data that specifies the name of the cache-helper used by the parent cache-mapping element.

Subelements

none

Attributes

none

timeout

Contains data that specifies the cache-mapping specific maximum amount of time in seconds that an entry can remain in the cache after it is created or refreshed. If not specified, the default is the value of the timeout attribute of the cache element.

Subelements

none

Attributes

The following table describes attributes for the timeout element.

Table 5-36  timeout Attributes 

Attribute	Default	Description
name	none	Specifies the timeout input parameter, whose value is interpreted in seconds. The field’s type must be java.lang.Long or java.lang.Integer.
scope	request.attribute	(optional) Specifies the scope from which the input parameter is to be retrieved. Allowed values are context.attribute, request.header, request.parameter, request.cookie, request.attribute, and session.attribute.

refresh-field

Specifies a field that gives the application component a programmatic way to refresh a cached entry.

Subelements

none

Attributes

The following table describes attributes for the refresh-field element.

Table 5-37  refresh-field Attributes 

Attribute	Default	Description
name	none	Specifies the input parameter name.
scope	request.parameter	(optional) Specifies the scope from which the input parameter is to be retrieved. Allowed values are context.attribute, request.header, request.parameter, request.cookie, session.id, and session.attribute.

http-method

Contains data that specifies an HTTP method that is eligible for caching. The default is GET.

Subelements

none

Attributes

none

key-field

Specifies a component of the key used to look up and extract cache entries. The web container looks for the named parameter, or field, in the specified scope.

If this element is not present, the web container uses the Servlet Path (the path section that corresponds to the servlet mapping that activated the current request). See the Servlet 2.3 specification, section SRV 4.4, for details on the Servlet Path.

Subelements

none

Attributes

The following table describes attributes for the key-field element.

Table 5-38  key-field Attributes 

Attribute	Default	Description
name	none	Specifies the input parameter name.
scope	request.parameter	(optional) Specifies the scope from which the input parameter is to be retrieved. Allowed values are context.attribute, request.header, request.parameter, request.cookie, session.id, and session.attribute.

constraint-field

Specifies a cacheability constraint for the given url-pattern or servlet-name.

All constraint-field constraints must pass for a response to be cached. If there are value constraints, at least one of them must pass.

Subelements

The following table describes subelements for the constraint-field element.