For details about response caching as it pertains to servlets, see Caching Servlet Results JSP Cache Tags
Caching elements are as follows:
Configures caching for web application components.
The following table describes subelements for the cache element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 6–25 cache Subelements
Element |
Required |
Description |
---|---|---|
zero or more |
Specifies a custom class that implements the CacheHelper interface. |
|
zero or one |
Allows you to change the properties of the default, built-in cache-helper class. |
|
zero or more |
Specifies a cache property, which contains a name and a value. |
|
zero or more |
Maps a URL pattern or a servlet name to its cacheability constraints. |
The following table describes attributes for the cache element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table 6–26 cache Attributes
Attribute |
Default Value |
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. Legal values are on, off, yes, no, 1, 0, true, false. |
The following table describes properties for the cache element. The left column lists the property name, the middle column indicates the default value, and the right column describes what the property does.
Table 6–27 cache Properties
Property Name |
Default Value |
Description |
---|---|---|
cacheClassName |
com.sun.appserv.web.cache.LruCache |
Specifies the fully qualified name of the class that implements the cache functionality. See The Table 6–28 |
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. |
The following table lists possible values of the cacheClassName property. The left column lists the value, and the right column describes the kind of cache the value specifies.
Table 6–28 cacheClassName Values
Value |
Description |
---|---|
com.sun.appserv.web.cache.LruCache |
A bounded cache with an LRU 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. |
Specifies a class that implements the CacheHelper interface. For details, see CacheHelper Interface
The following table describes subelements for the cache-helper element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 6–29 cache-helper Subelements
Element |
Required |
Description |
---|---|---|
zero or more |
Specifies a property, which contains a name and a value. |
The following table describes attributes for the cache-helper element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table 6–30 cache-helper Attributes
Attribute |
Default Value |
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. |
Allows you to change the properties of the built-in default cache-helper class.
The following table describes subelements for the default-helper element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 6–31 default-helper Subelements
Element |
Required |
Description |
---|---|---|
zero or more |
Specifies a property, which contains a name and a value. |
none
The following table describes properties for the default-helper element. The left column lists the property name, the middle column indicates the default value, and the right column describes what the property does.
Table 6–32 default-helper Properties
Property Name |
Default Value |
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 searches 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. For more information, see CacheKeyGenerator Interface |
Maps a URL pattern or a servlet name to its cacheability constraints.
The following table describes subelements for the cache-mapping element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 6–33 cache-mapping Subelements
Element |
Required |
Description |
---|---|---|
requires one servlet-name or url-pattern |
Contains the name of a servlet. |
|
requires one servlet-name or url-pattern |
Contains a servlet URL pattern for which caching is enabled. |
|
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. |
|
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 |
|
zero or one if cache-helper-ref is not used |
Specifies a field that gives the application component, programmatic way to refresh a cached entry. |
|
zero or more if cache-helper-ref is not used |
Contains an HTTP method that is eligible for caching. |
|
zero or more if cache-helper-ref is not used |
Specifies a component of the key used to look up and extract cache entries. |
|
zero or more if cache-helper-ref is not used |
Specifies a cacheability constraint for the given url-pattern or servlet-name. |
none
Contains data that specifies a servlet URL pattern for which caching is enabled. See the Java Servlet 2.3 specification, section SRV 11.2 for applicable patterns.
none
none
Contains data that specifies the name of the cache-helper used by the parent cache-mapping element.
none
none
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.
none
The following table describes attributes for the timeout element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table 6–34 timeout Attributes
Attribute |
Default Value |
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 |
context.attribute |
(optional) Specifies the scope in which the input parameter can be present. Allowed values are context.attribute, request.header, request.parameter, request.cookie, session.id, and session.attribute. |
Specifies a field that gives the application component a programmatic way to refresh a cached entry.
none
The following table describes attributes for the refresh-field element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table 6–35 refresh-field Attributes
Attribute |
Default Value |
Description |
---|---|---|
name |
none |
Specifies the input parameter name. If the parameter is present in the specified scope and it’s value is true, the cache will be refreshed. |
scope |
request.parameter |
(optional) Specifies the scope in which the input parameter can be present. Allowed values are context.attribute, request.header, request.parameter, request.cookie, session.id, and session.attribute. |
Contains data that specifies an HTTP method that is eligible for caching. The default is GET.
none
none
Specifies a component of the key used to look up and extract cache entries. The web container searches 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.
none
The following table describes attributes for the key-field element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table 6–36 key-field Attributes
Attribute |
Default Value |
Description |
---|---|---|
name |
none |
Specifies the input parameter name. |
scope |
request.parameter |
(optional) Specifies the scope in which the input parameter can be present. Allowed values are context.attribute, request.header, request.parameter, request.cookie, session.id, and session.attribute. |
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.
The following table describes subelements for the constraint-field element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.
Table 6–37 constraint-field Subelements
Element |
Required |
Description |
---|---|---|
zero or more |
Contains a value to be matched to the input parameter value. |
The following table describes attributes for the constraint-field element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table 6–38 constraint-field Attributes
Attribute |
Default Value |
Description |
---|---|---|
name |
none |
Specifies the input parameter name. |
scope |
request.parameter |
(optional) Specifies the scope in which the input parameter can be present. Allowed values are context.attribute, request.header, request.parameter, request.cookie, session.id, and session.attribute. |
cache-on-match |
true |
(optional) If true, caches the response if matching succeeds. Overrides the same attribute in a value subelement. |
cache-on-match-failure |
false |
(optional) If true, caches the response if matching fails. Overrides the same attribute in a value subelement. |
Contains data that specifies a value to be matched to the input parameter value. The matching is case sensitive. For example:
<value match-expr="in-range">1-60</value>
none
The following table describes attributes for the value element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.
Table 6–39 value Attributes
Attribute |
Default Value |
Description |
---|---|---|
match-expr |
equals |
(optional) Specifies the type of comparison performed with the value. Allowed values are equals, not-equals, greater, lesser, and in-range. If match-expr is greater or lesser, the value must be a number. If match-expr is in-range, the value must be of the form n1-n2, where n1 and n2 are numbers. |
cache-on-match |
true |
(optional) If true, caches the response if matching succeeds. |
cache-on-match-failure |
false |
(optional) If true, caches the response if matching fails. |