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:
- Provide the class name of the servlet
- 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:
- request parameters
- request attributes
- 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.
|
|