InfoCenter Home >
6: Administer applications >
6.6: Tools and resources quick reference >
6.6.0: About user assistance >
6.6.0.4: Overview of editing property files by hand >
6.6.0.4.1: Dynamic caching of Servlets and JSPs >
6.6.0.4.1.2: Description of the servletcache.xml file

6.6.0.4.1.2: Description of the servletcache.xml file

Administrators identify the servlets to be cached in the servletcache.xml file. The servletcache.xml file is located in directory:

\WebSphere\AppServer\properties

Within the <servlet> element, you specify parameters that:
  • Identify the servlets to be cached
  • Determine how entry ids for servlets are created
  • Determine how servlet entries are deleted.
Typically, the servletcache.xml file contains multiple <servlet> elements.

Note:  The servletcache.xml file is read only once, at WebSphere Application Server startup. So if changes are made to the file, WebSphere Application Server must be restarted for the changes to take effect.

The DTD (document type definition) for the servletcache.xml file is specified in the servletcache.dtd file that ships with WebSphere Application Server and is located in directory:

\WebSphere\AppServer\properties

The servletcache.dtd file defines the root element, <servletcache>.

The servletcache.dtd file is included in the xml file through a DOCTYPE declaration, as for example:

<!DOCTYPE servletcache SYSTEM "servletcache.dtd">

Therefore, the beginning of the servletcache.xml file looks like:

 <?xml version="1.0"?>
<!DOCTYPE servletcache SYSTEM "servletcache.dtd">

Identifying what to cache

The cache parses the servletcache.xml file when WebSphere Application Server is started, and extracts a set of configuration parameters from each <servlet> element. Then each time a new servlet is initialized, the cache attempts to match the servlet with a servlet element to find the configuration information for that servlet.

You can specify the servlets to cache in two ways:

  1. Provide the class name of the servlet
  2. Provide the full URI for the servlet.

    Note:  The way you specify the servlet URI in the servletcache.xml file is different from the WebSphere Application Server convention where URIs are relative to the Web applications in which they are defined. In the servletcache.xml file, the URI begins with the hostname or IP address.

  • Servletimpl -

    Use this tag to cache a servlet class. The format of the <servletimlp> tag is:

    <servletimpl class="ClassName"/>
    The variable ClassName identifies the class to be cached. This class must extend HttpServlet.

    When a servlet class is initialized, dynacache matches the servlet with the set of config parameters declared in the <servlet> element. This comparison is made by matching strings. Subclasses of the specified servlet will not match this declaration.

  • Path -

    Use this tag to cache a servlet by its URI. The format of the <path> tag is:

    <path uri="web_path"/>
    The variable web_path identifies the full URI of the servlet, beginning with the hostname. It does not include any CGI variables. The web application's web path must be a part of this parameter. So to access a cacheable servlet with URL,
    http://servername.ibm.com/webappname/servlet/MyServlet?arg1=1&
    that servlet's path element is:
    <path uri="/webappname/servlet/MyServlet" />

    You can specify different path elements for the same servlet. Also, the same path can appear in two different <servlet> elements. When configuring a servlet invoked by path, dynacache uses the configuration from the first valid, matching <servlet> element.

The following table describes the differences between caching a servlet by class name versus caching a servlet or JSP by web path:

Caching a servlet by class name Caching a servlet by web path
Tags
<servlet>
<servletimpl class= "CalcServlet"/>
(other configuration information)
</servlet>
<servlet>
<path uri="/tools/Calc"/>
<path uri="/tools/servlet/CalcServlet"/>
<path uri="/tools/Calculator.jsp"/>
(other configuration information)
</servlet>
Behaviors
Whether defined through the administration client or loaded with InvokerServlet, this configuration would match any servlet of class, CalcServlet. However, even if class ScientificCalculatorServlet extended CalcServlet, this configuration would not match ScientificCalculatorServlet.
This configuration yields a different behavior.
    The first path catches any request for the /tools/Calc URI, regardless of the servlet's class.
    The second path, /tools/servlet/CalcServlet, matches any calls to the InvokerServlet for the CalcServlet class.
    The third path, /tools/Calculator.jsp, enables caching on a JSP implementation of the calculator.
Results
This general setup caches every servlet of class CalcServlet, across the entire server, regardless of the URI.
This specific setup caches the defined servlet Calc (which may or may not be part of the CalcServlet class), and only caches CalcServlet if it is specifically invoked.

Description of other configuration parameters in servletcache.xml

Within the <servlet> stanza, the administrator must define other elements that are used to build entries in the cache, or are required to remove entries.

The next two elements invalidate entries in the cache. See file, 6.6.0.4.1.3: Removing entries from a cache, for more information on clearing the cache.

  • Timeout -

    Determines when an entry is invalidated. If the <timeout> element is not present, then the <servlet> stanza that contains it, is invalidated and is not cached. The format of the <timeout> element is:

    <timeout seconds="time_in_cache"/>
    The variable, time_in_cache, is the length of time in seconds that indicates when an entry, after it is created, should be removed from the cache. This value is required. If this value is zero or a negative number, the entry does not timeout and is only removed when the cache is full or programmatically, from within an application.
  • Priority -

    Determines how long an entry stays in the cache. The format of the <priority> element is:

    <priority val="priority"/>
    The variable, priority, is a zero or positive integer designating the length of time an entry stays in the cache before being eligible for removal. If this element is not present, then the default_value, defined in the <priority> element in the dynacache.xml file, is used as the value for priority.

The next set of elements determines how requests are served.

  • Externalcache -

    Identifies external cache groups. The format of the <externalcache> element is:

    <externalcache id="group_name"/>
    The variable, group_name is the name of an external cache group defined in the dynacache.xml file.

    When serving external requests (that is, not when building servlet or JSP fragments), the generated page is copied to the external cache groups declared in the dynacache.xml file. This results in two parallel entries: one in WebSphere Application Server and another in the external caches. The external entry uses the full URI of the page as an id, and is timed out or invalidated at the same time as the local entry. To recap, when a page is cached, a copy of it is pushed to the external cache group identified by group_name.

  • MetaDataGenerator -

    Identifies a "user written" interface for handling invalidation, priority and external cache group. When a <metadatagenerator> is declared in the servletcache.xml file, it replaces the <timeout>, <priority>, and <externalcache> elements for a servlet.

    The format of the <metadatagenerator> tag is:

    <metadatagenerator class="class_name" />
    The variable, class_name, is the full package and class name of a class extending com.ibm.servlet.dynacache.MetaDataGenerator. See the programming documentation for more information on creating the MetaDataGenerator interface.

The next set of elements determines how cache entries are created.

  • Description of how cache entries are created -

    Each time a servlet is called, WebSphere Application Server generates a corresponding HttpServletRequest object. The cache uses information in that object to build an id string to represent the call.

    The value of the id string varies, depending on the tag information provided in the servletcache.xml file. It ranges from minimal default information (as for example the URI of the requested servlet), to user supplied combinations of request and session variables.

  • Using request and session variables

    When a servlet is called, the servlet receives variable information from three main sources:

    1. request parameters
    2. request attributes
    3. session parameters

    An administrator defines request and session variables, and then the cache uses the values of these variables to create ids for the entries. The request and session variables can also be used to group cache entries. The values of the variables are combined with id strings to generate data ids. Entries with specific data ids can join other, like entries in a group. Entries with specific data ids can also invalidate all existing members of that group. Using the <invalidate> tag, you can define an entry that does no caching, and only invalidates groups.

  • Request parameters and attributes -

    A client browser can set request parameters with CGI, when submitting a form. Servlets can set attributes on an HttpServletRequest object, and then forward or include that request to another servlet.

    The format of the <request>, <parameter>, and <attribute> elements is:

    <request>
    <parameter id="parameter_name"
    data_id="group_identifier"
    invalidate="group_identifier"
    required="true|false"/>
    <attribute id="attribute_name"
    method="method_name"
    data_id="group_identifier"
    required="true|false"/>
    </request>
    
    The variable, parameter_name, is the name of the request parameter. The value of parameter_name is used to generate cache entry ids.

    The variable, attribute_name, is the name of the request attribute. The output of one or more of this object's methods is used to generate cache entry ids.

    The variable, method, is the name of a method in this request attribute. The output of this method is used to generate cache entry ids. If this value is not specified, toString is assumed. This method does not take any arguments. Do not include parenthesis in the method name when defining this variable.

    The variable, group_identifier, is a string that, combined with the value of the request variable, generates a group name for the cache entry. If group_identifier is specified on the <data_id> element, the cache entry is placed in that group. If group_indentifier is used in an <invalidate> entry, the group is invalidated, and the entry is placed in the cache. If a group_identifier is not defined, these actions will not occur.

    The element, <required>, indicates whether a value must be present in the request. If <required> is set to true and either the <parameter> or <attribute> element is not present, or the method is missing in an <attribute> definition, the request is not cached. The <required> value defaults to false when not set.

    Note:  You can define unlimited <parameter> and <attribute> elements within a <request> element, but you can only define one <request> element per a <servlet> element.

  • Session parameters -

    The cache handles session parameters in the same way it handles attributes.

    The format of the <session> element is:

    <session id="session_parameter_name"
    method="method_name"
    data_id="group_identifier"
    invalidate="group_identifier"
    required="true|false"/>
    
    The variable, session_parameter_name, is the name of the session parameter. The value of session_parameter_name is used to generate cache entry ids.

    The variable, method, is the name of a method in this session parameter. The output of this method is used to generate cache entry ids. If this value is not specified, toString is assumed. This method does not take any arguments. Do not include parenthesis in the method name when defining this variable.

    The variable, group_identifier, is a string that, combined with the value of the session variable, generates a group name for the cache entry. If group_identifier is specified on the <data_id> element, the cache entry is placed in that group. If group_indentifier is used in an <invalidate> entry, the group is invalidated, and the entry is placed in the cache. If a group_identifier is not defined, these actions will not occur.

    The element, <required>, indicates whether a value must be present in the session. If <required> is set to true and either the < session parameter> element is not present or does not contain the specified method, the request is not cached. The <required> value defaults to false when not set.

    Note:  You can define unlimited <session parameter> elements within a <servlet> element.

  • Invalidateonly -

    When this tag is used, no caching is performed for the servlet. However, invalidations triggered by this servlet will take effect. This prevents caching of control servlets (which would prevent the servlets from being executed).

    The format of the <invalidateonly> element is:

    <invalidateonly />

  • IdGenerator -

    Identifies a "user written" interface for handling parameters, attributes and sessions. When an <idgenerator> element is declared in the servletcache.xml file, it replaces the <parameter>, <attribute>, and <session> elements for a servlet.

    The format of the <idgenerator> tag is:

    <idgenerator class="class_name" />
    The variable, class_name, is the full package and class name of a class extending com.ibm.servlet.dynacache.IdGeneratorClass. See the programming documentation for more information on creating the IdGenerator interface.
Go to previous article: Quick reference - dynacache.xml file Go to next article: Removing entries from the cache

 

 
Go to previous article: Quick reference - dynacache.xml file Go to next article: Removing entries from the cache