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:

  1. Identify the servlets to be cached
  2. Govern the creation of entry ids for servlets
  3. 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:

  1. By specifying the class name of the servlet, or
  2. 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:

  1. One of the cache's invalidation methods (see com.ibm.websphere.servlet.cache.Cache in Javadoc) was called directly, inside the servlet code
  2. Running a servlet triggered a rule based invalidation
  3. The timeout for the entry expired
  4. 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" />

    class_name: The full package and class name of a class entending com.ibm.servlet.dynacache.IdGenerator.

    See the "Custom Id and MetaData Generators" section for more information.

MetaDataGenerator

<metadatagenerator class="class_name" />

    class_name: The full package and class name of a class entending com.ibm.servlet.dynacache.MetaDataGenerator.

    See the "Custom Id and MetaData Generators" section for more information.

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

  1. <?xml version="1.0"?>
  2. <!DOCTYPE cacheUnit SYSTEM "dynacache.dtd">
  3. <servletCache>
  4. <servlet>
  5. <invalidateonly/>

    <servletimpl class="some.package.SomeClass"/>

      OR   <path uri="MyServlet" />

    <path uri="servlet/SomeClass"/>

  6. <timeout seconds= "timeout value" />

      OR   <metadatagenerator

    <priority value="priority value" />

    class="package.GeneratorClass" />

  7. <externalcache id="external cache group name">
  8. OR
  9. <request>
  10. <parameter id="parameter name"

         data_id="group identifier 1"

         invalidate="group identifier 2"

         ignorevalue="true|false"

         required="true|false" >

            <exclude value="exclude value"/>

    </parameter>

  11. <attribute id ="attribute name"

          method= "aMethodName"

          data_id="group identifier 1"

          invalidate="group identifier 2"

          ignorevalue="true|false"

          required="true|false" />

  12. </request>
  13. <session id="session attribute name"

          method="aMethodName"

          data_id="group identifier 1"

          invalidate="group identifier 2"

          ignorevalue="true|false"

          required="true|false" />

  14. cookie id="cookie name"

          method="aMethodName"

          data_id="group identifier 1"

          invalidate="group identifier 2"

          ignorevalue="true|false"

          required="true|false" />

  15. <idgenerator class="package.IdGeneratorClass" />
  16. <metadatagenerator class="package.MetaDataGeneratorClass"/>
  17. </servlet>
  18. </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

Go to previous article: Global administration Go to next article: Dynamic fragment cache XML examples

 

 
Go to previous article: Global administration Go to next article: Dynamic fragment cache XML examples