Caching Elements
For details about response caching as it pertains to servlets, see Caching Servlet Results JSP Cache Tags
Caching elements are as follows:
cache
Configures caching for web application components.
Subelements
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. |
Attributes
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. |
Properties
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. |
Cache Class Names
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. |
cache-helper
Specifies a class that implements the CacheHelper interface. For details, see CacheHelper Interface
Subelements
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. |
Attributes
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. |
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. 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. |
Attributes
none
Properties
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 |
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. 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. |
Attributes
none
url-pattern
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.
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. 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. |
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. 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. |
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 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.
Subelements
none
Attributes
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. |
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. 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. |
Attributes
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. |
value
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>
Subelements
none
Attributes
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. |
- © 2010, Oracle Corporation and/or its affiliates