InfoCenter Home >
6: Administer applications >
6.6: Tools and resources quick reference >
6.6.0: About user assistance >
6.6.0.16: Dynamic fragment cache configuration >
6.6.0.16.2: Policy configuration
6.6.0.16.2: Policy configuration
Cache policies can be configured using the XML configuration file,
servletcache.xml, or the Application Assembly Tool.
This article describes building the XML file, which currently supports more
caching features than the AAT.
Unless stated otherwise, the XML elements have identical counterparts
in the AAT. See the Application Assembly Tool documentation to learn how
to build cache policies with the AAT.
XML configuration
Administrators define the servlets to be cached inside the
servletcache.xml file. The servletcache.xml file, like the
dynacache.xml file, is located in the
product_installation/properties
directory.
The root element of this XML file is <servletCache>, which contains <servlet> elements.
Within the <servlet> element, you
specify parameters that:
- Identify the servlets to be cached
- Govern the creation of entry ids for servlets
- Describe how entries generated from servlets are deleted from the cache
Typically you declare several <servlet> elements
inside a servletcache.xml file.
Just like the dynacache.xml file, the servletcache.xml file is read only
once, when WebSphere Application Server is first started. So if changes are made
to the file, WebSphere Application Server must be restarted for the changes to take effect.
The DTD for the servletcache.xml file is specified in the servletcache.dtd file, which ships with
WebSphere Application Server and is located in the
product_installation\properties directory.
The servletcache.dtd file defines the root element <servletCache>. The servletcache.dtd file
is included in the servletcache.xml file through the DOCTYPE declaration.
The beginning of the servletcache.xml should have the following processing instructions:
<?xml version="1.0"?>
<!DOCTYPE servletCache SYSTEM "servletcache.dtd">
Identifying What to Cache
The cache will parse the servletcache.xml file on startup, and
extract from each <servlet> element a set of configuration
parameters. Then, every time a new servlet is initialized, the cache attempts to
match that servlet to each of the different servlet elements to find the
configuration information for that servlet.
You can specify which servlets to cache in two ways:
- By specifying the class name of the servlet, or
- By using the servlet's full URI, beginning after the host name/IP address
To cache a servlet class, use the <servletimpl> tag.
- Servletimpl
-
<servletimpl class="ClassName" />
ClassName: The class to be cached.
This class must extend HttpServlet.
Whenever a servlet of the specified class is initialized, the dynamic caching function
will match that servlet with the element configuration.
Note: This comparison is done by matching strings;
subclasses of the specified servlet implementation will not match this declaration.
Defining servlets by class name is not supported by the Application Assembly Tool.
Alternatively, you can specify a web path for your servlets.
You do this with the <path> tag.
- Path
-
<path uri="web_path" />
web_path: The full URI of the servlet, from the hostname
to the CGI variable, but not including the CGI variable.
The Web application's Web path must be a part of this parameter.
So if you access a cacheable servlet with the URL
http://servername.ibm.com/webappname/servlet/MyServlet?arg1=1&....
then that servlet's path element should read
<path uri="/webappname/servlet/MyServlet" />
You can specify different path elements referring to the same servlet.
Also, the same path can appear in two different <servlet> elements,
but when configuring a servlet invoked from that path, dynacache will use the
configuration from the first valid <servlet> element that matches.
<servlet>
<servletImpl class="CalcServlet" />
:
(other config info)
:
</servlet>
This configuration will match any servlet of class CalcServlet.
Also, if class ScientificCalculatorServlet extends CalcServlet,
ScientificCalculatorServlets will not match this element |
<servlet>
<path uri="/tools/Calc" />
<path uri="/tools/servlet/CalcServlet" />
<path uri="/tools/Calculator.jsp" />
:
(other config info)
:
</servlet>
This configuration yields slightly different behavior.
In it we are working within a hypothetical tools Web application.
The first path will catch any request for the /tools/Calc URI, regardless of that
servlet's class.
The second path will catch any calls to the Invoker Servlet for
the CalcServlet class.
The third path allows you to cache on a JSP implementation of the calculator.
|
This example of a general setup will cache every servlet
of class CalcServlet across the entire server, regardless of the URI |
This example of a specific setup will cache
the GUI defined servlet Calc (which may or may not be of the CalcServlet class),
and will only cache CalcServlets if they are specifically invoked |
Removing entries from the cache
After you declare which servlets to cache, defining how to cache those servlets has
two parts:
- Building unique entries for different requests, and
- Removing those entries at the appropriate time
You can do this using the servletcache.xml file, or by writing your own class
to handle invalidation.
The cache removes entries in the following circumstances:
- One of the cache's invalidation methods (see com.ibm.websphere.servlet.cache.Cache in Javadoc)
was called directly, inside the servlet code
- Running a servlet triggered a rule based invalidation
- The timeout for the entry expired
- The cache was full and a new entry replaced an old one
The first case is not relevant in this context, as it is done programmatically
inside an application.
The second case results from the "invalidate" attribute used with a cache variable,
and third and fourth cases are configured using the <timeout> and <priority> tags.
- Timeout
-
-
<timeout seconds="time_in_cache" />
time_in_cache: The length of time, in seconds, after creation of an entry,
that it should be removed from the cache.
This value is required. If this value is zero or negative, the entry will not timeout,
and can only be removed when the cache is full or programmatically from within
an application.
If the <timeout> element is not present, then the <servlet> element in
which it is contained will be invalidated, and will not be cached.
When entries with a positive timeout are created,
the timeout is added to the current time to determine when the entry will be
invalidated. When that time is reached, if the entry remains in the cache,
the cache will force its invalidation.
- Priority
-
<priority val="priority" />
priority: This value is a zero or positive integer, designating
the length of time an entry will stay in the cache before becoming eligible
for removal. If this element is not present, then the default value,
defined in the dynacache.xml file, will be used.
Priority is an extension of the Least Recently Used caching algorithm.
It represents the number of cycles through the LRU algorithm an entry is guaranteed
to stay in the cache. On each cycle of the algorithm, the priority of an entry is
decremented. Once it reaches zero, it is eligible to be invalidated.
If an entry is requested while in the cache, its priority is reset to this value,
keeping it in the cache longer. Therefore, a higher priority will provide a
relatively longer availability for an entry, and more frequently requested entries
will stay in the cache longer, with an entry's timeout as a hard cap.
In a high volume application where space in the cache is at a premium,
designers should consider increasing the priority of a servlet or JSP if
calculating its output is significantly harder than average, or if it
will be executed much more often than average.
Note: Priority values should be kept low, as higher values
will not yield a relative improvement, but will use extra LRU cycles. Declaring a servlet
with priority 3 and another with priority 4 will generate the same invalidation
behavior as servlets with priority 1 and 2, only marginally slower.
When dealing with caches in the thousands of entries and greater,
that slowdown becomes significant.
Use the timeout variable to guarantee the
validity of an entry. Use priority to rank the relative importance of that entry.
Giving all elements equal priority results in a standard LRU cache that
increases performance significantly, but you can tailor the cache's
operation to the application with careful use of the priority variable.
- Externalcache
-
<externalcache id="group_name" />
group_name: The name of an external cache group defined in the
global configuration of the cache.
When this page is cached, a copy of it will now be pushed to this external
cache group. See the external cache
article for more information.
- IdGenerator
-
<idgenerator class="class_name" />
- MetaDataGenerator
-
<metadatagenerator class="class_name" />
Specifying how to cache
Each time a servlet is called and WebSphere Application Server generates a
corresponding HttpServletRequest object, the cache uses information
in that object to build an id string to represent the call.
A servlet's cache policy contains the rules that determine which pieces of
information are used in that id string.
It always contains certain default information, such as the URI of the requested
fragment and its character encoding. The rules give extra information about
what variables should be used in the id, and how they should be treated.
Using cache variables
A cache variable is a generic term for a variable whose data should
be used in caching a fragment.
The four types of cache variables that correspond to the main sources of input
for a fragment are:
- request parameters
- request attributes
- session attributes
- cookies
A client browser can set request parameters with CGI when submitting a form,
while a servlet can set attributes on an HttpServletRequest object,
then forward or include that request to another servlet.
Finally, WebSphere Application Server can maintain session attributes
that a servlet might want to access, and set cookies for later servlets to process.
In addition to building cache ids, these variables are used to control
the following:
- grouping of cache entries
- the invalidation of other groups
- determining whether to cache a servlet based on that variable's value
The cache can decide whether or not to cache an invocation depending on the value
of its input variables using the <exclude> tag.
Groups are handled by data ids, which consist of strings specified
in the cache variable combined with the variable's value.
Using the data_id attribute builds a group name and adds a servlet's
cache entries to that group.
The invalidate attribute causes the eviction of a group from the cache.
It is possible to have an entry that does no caching, and only invalidates groups. The <invalidateonly> tag is provided to save processing time for this case.
The syntax for the various attibutes follow.
- Request, Parameter, and Attribute
-
<request>
<parameter id="parameter_name"
data_id="group_identifier"
invalidate="group_identifier"
ignorevalue="true|false"
required="true|false" >
<exclude value="exclude_value"/>
</parameter>
<attribute id="attribute_name"
method="method_name"
data_id="group_identifier"
invalidate="group_identifier"
ignorevalue="true|false"
required="true|false" >
<exclude value="exclude_value"/>
</attribute>
</request>
parameter_name: The name of a request parameter,
the value of which will be used to generate cache entry ids.
attribute_name: The name of a request attribute.
The output of one or more of this object's methods will be used to generate
cache entry ids.
method: The name of a method in this request attribute.
The output of this method will be used to generate cache entry ids.
If this value is not specified "toString" is assumed.
This method may not take any arguments, and parenthesis should not be included
in the method.
group_identifier: A string that, when combined with the value of this
request variable, generates a group name for this cache entry.
If used by a "data_id" attribute, this cache entry will be placed in that group.
If used in an "invalidate" entry, then that group will be invalidated, and this
entry will then be placed in the cache. If this variable is not present, the group id
will not be used, and neither action will occur.
ignorevalue: Indicates whether this variable's value is relevant to
the cache id, or whether only the variable's presence is important.
If true, the cache id will reflect that the variable was present, but
its value will not be used. This value defaults to false when not set.
required: Indicates whether this value must be present in the request.
If this is set to true and either the parameter/attribute is not present or
(when defining an attribute) does not contain the specified method,
then this request will not be cached. This value defaults to false when not set.
You can define unlimited parameter and attribute objects within a <request>
element, but you should only define one <request> element per <servlet>
element.
The cache's handling of session attributes is identical to its handling of request attributes.
- Session
-
<session id="session_attribute_name"
method="method_name"
data_id="group_identifier"
invalidate="group_identifier"
ignorevalue="true|false"
required="true|false" >
<exclude value="exclude_value"/>
</session>
session_attribute_name: The name of a session attribute,
the value of which will be used to generate cache entry ids.
method: The name of a method in this session attribute.
The output of this method is used to generate cache entry ids.
If this value is not specified "toString" is assumed.
This method may not take any arguments, and parenthesis should not be included
in the method.
group_identifier: A string that, when combined with the value of
this request variable, generates a group name for this cache entry.
If used by a "data_id" attribute, this cache entry will be placed in that group.
If used in an "invalidate" entry, then that group will be invalidated, and this
entry will then be placed in the cache. If this variable is not present, the
group id will not be used, and neither action will occur.
ignorevalue: Indicates whether this variable's value is relevant to the
cache id, or if only the variable's presence is important.
If true, the cache id will reflect that the variable was present,
but its value will not be used. This value defaults to false when not set.
required: Indicates whether this value must be present in the session.
If this is set to true and either the session parameter is not present or does not
contain the specified method, then this request is not cached.
This value defaults to false when not set.
As with request parameters/attributes, there can be any number of session attributes
declared in a servlet.
- Invalidateonly
-
<invalidateonly />
When this tag is used, no caching is performed for this servlet,
though invalidations triggered by it will take effect.
- Exclude
-
The <exclude/> tag attaches to a cache variable and is used to keep
a servlet from being cached when that variable is present on the request.
It can only be applied for certain values, or for all values of a cache variable.
When the exclude tag is used without its "value" attribute, no caching is performed
for this servlet when the variable is present.
Alternatively, users can repeat the <exclude> tag with the "value"
attribute defined several times to specify a set of values that keep the servlet
from being cached. This helps prevent caching of control servlets.
exclude_value: When the cache variable is present on a request
and its value is equal to this, the servlet is not cached.
For example, the following setup indicates that whenever the request parameter
"nocache" is present, the servlet should not be cached:
<servlet>
<path uri="/myServlet"/>
<timeout seconds="-1" />
<request>
<parameter id="nocache" >
<exclude/>
</parameter>
</request>
</servlet>
In this example, the servlet will be cached unless the request parameter "cache"
is present and its value equals "no" or "false":
<servlet>
<path uri="/myServlet" />
<timeout seconds="-1" />
<request>
<parameter id="cache" >
<exclude value="no"/>
<exclude value="false"/>
</parameter>
</request>
</servlet>
Exclude tags can be applied to any cache variable.
Notes:
Invalidating has a higher performance cost than caching.
Avoid using the same variable to invalidate a group and to group an entry.
You will see less performance benefit than when just using the variable to define a group id.
Data_id and invalidate tags that are within the same <servlet> element
should have different values, usually. If they have the same value,
the group is invalidated, and the entry for the current servlet is
put into that group. The invalidate tag that corresponds to a data_id will occur
in different <servlet> elements.
Quick Reference of the servletcache.xml file
- <?xml version="1.0"?>
- <!DOCTYPE cacheUnit SYSTEM "dynacache.dtd">
- <servletCache>
- <servlet>
- <invalidateonly/>
<servletimpl class="some.package.SomeClass"/> |
OR <path uri="MyServlet" />
|
|
<path uri="servlet/SomeClass"/>
|
-
<timeout seconds= "timeout value" /> |
OR <metadatagenerator |
<priority value="priority value" /> |
class="package.GeneratorClass" /> |
- <externalcache id="external cache group name">
- OR
- <request>
- <parameter id="parameter name"
|
data_id="group identifier 1" |
|
invalidate="group identifier 2" |
|
ignorevalue="true|false" |
|
required="true|false" > |
<exclude value="exclude value"/> |
</parameter> |
- <attribute id ="attribute name"
|
method= "aMethodName" |
|
data_id="group identifier 1" |
|
invalidate="group identifier 2" |
|
ignorevalue="true|false" |
|
required="true|false" /> |
- </request>
- <session id="session attribute name"
|
method="aMethodName" |
|
data_id="group identifier 1" |
|
invalidate="group identifier 2" |
|
ignorevalue="true|false" |
|
required="true|false" /> |
- cookie id="cookie name"
|
method="aMethodName" |
|
data_id="group identifier 1" |
|
invalidate="group identifier 2" |
|
ignorevalue="true|false" |
|
required="true|false" /> |
- <idgenerator class="package.IdGeneratorClass" />
- <metadatagenerator class="package.MetaDataGeneratorClass"/>
- </servlet>
- </servletCache>
Notes:
Line 6: Timeout < 1 implies the value will not time out. Required.
Line 10: The method, called from the request parameter, defaults to toString, and required defaults to false.
Line 10: The exclude tag can be used in any of the four cache variable types.
Line 10: The method called on the request attribute defaults to toString, and required defaults to false.
Line 13: The method called on the session attribute defaults to toString, and required defaults to false.
Line 14: The method called on the cookie defaults to toString, and required defaults to false.
Line 8: OR applies to lines 10-15
|
|