The cache parses the cachespec.xml file when the server starts, and extracts a set of configuration parameters from each <cache-entry> element. Every time a new servlet or other cacheable object initializes, the cache attempts to match each of the <cache-entry> elements to find the configuration information for that object. The <cache-entry> elements can be inside the root <cache> element or inside a <cache-instance> element. Cache entries that are in the <root> element are cached with the default cache instance. Cache entries that are in the <cache-instance> element are cached in that particular cache instance. Different cacheable objects have different <class> elements. You can define the specific object a cache policy refers to using the <name> element.
Location
Place the cachespec.xml file with the deployment module. Use an assembly tool to define the cacheable objects. See Assembling applications for more information about assembling applications. You can also place a global cachespec.xml file in the application server properties directory.
The cachespec.dtd file is available in the application server properties directory. The cachespec.dtd file defines the legal structure and the elements that can be in your cachespec.xml file.
Usage notes
Cachespec.xml elements
The root element of the cachespec.xml file is <cache> and contains <cache-instance> and <cache-entry> elements. The <cache-entry> elements can also be placed inside of <cache-instance> elements to make that cache entry a part of a cache instance that is other than the default.
cache-instance
<cache-instance name="cache_instance_name"></cache-instance>
The name attribute is the Java Naming and Directory Interface (JNDI) name of the cache instance that is set in the administrative console.
Each <cache-instance> element must contain at least one <cache-entry> element. A cache entry that is matched within a <cache-instance> element is cached in the servlet cache instance that is specified by the name attribute. If identical <cache-entry> elements exist across <cache-instance> elements then the first <cache-entry> element that is matched is used.
cache-entry
With the current version of WebSphere Application Server, you can define multiple cache policies for a single servlet. For example, if you define multiple mappings for a servlet in the web.xml file, you can create a cache entry for each one of the mappings.
class
<class>command | servlet | webservice | JAXRPCClient | static</class>
This element is required and specifies how the application server interprets the remaining cache policy definition. The value servlet refers to servlets and JavaServer Pages (JSP) files that are deployed in the WebSphere Application Server servlet engine. The webservice class extends the servlet with special component types for Web services requests. The JAXRPCClient is used to define a cache entry for the Web services client cache. The value command refers to classes using the WebSphere command programming model. The value static refers to files that contain static content. The following examples illustrate the class element:
<class>command</class> <class>servlet</class> <class>webservice</class> <class>JAXRPCClient</class> <class>static</class>
name
<name>name</name>
You can specify multiple <name> elements within a <cache-entry> if you have different mappings that refer to the same servlet.
<name>com.mycompany.MyCommand.class</name> <name>default_host:/servlet/snoop</name> <name>com.mycompany.beans.MyJavaBean</name> <name>mywebapp/myjsp.jsp</name> <name>/soap/servlet/soaprouter</name> <name>http://remotecompany.com:9080/service/getquote</name> <name>mywebapp/myLogo.gif</name>
sharing-policy
<sharing-policy> not-shared | shared-push | shared-pull | shared-push-pull</sharing-policy>
When working within a cluster with a distributed cache, these values determine the sharing characteristics of entries created from this object. If this element is not present, a not-shared value is assumed. In single server environments, not-shared is the only valid value. When enabling replication, the default value is not-shared . This property does not affect distribution to Edge Side Include processors through the Edge fragment caching property. See for more information.
Value | Description |
not-shared | Cache entries for this object are not shared among different application servers. These entries can contain non-serializable data. For example, a cached servlet can place non-serializable objects into the request attributes, if the <class> type supports it. |
shared-push | Cache entries for this object are automatically distributed to the dynamic caches in other application servers or cooperating Java Virtual Machines (JVMs). Each cache has a copy of the entry at the time it is created. These entries cannot store non-serializable data. |
shared-pull | Cache entries for this object are shared between application servers on demand. If an application server gets a cache miss for this object, it queries the cooperating application servers to see if they have the object. If no application server has a cached copy of the object, the original application server runs the request and generates the object. These entries cannot store non-serializable data. This mode of sharing is not recommended. |
shared-push-pull | Cache entries for this object are shared between application servers on demand. When an application server generates a cache entry, it broadcasts the cache ID of the created entry to all cooperating application servers. Each server then knows whether an entry exists for any given cache ID. On a given request for that entry, the application server knows whether to generate the entry or pull it from somewhere else. These entries cannot store non-serializable data. |
<sharing-policy>not-shared</sharing-policy>
property
<property name="key">value</property>
where key is the name of the property for this cache entry element, and value is the corresponding value.
You can set optional properties on a cacheable object, such as a description of the configured servlet. The class determines valid properties of the cache entry. At this time, the following properties are defined:
Property | Valid classes | Value |
ApplicationName | All | Overrides the J2EEName application ID so that multiple applications can share a common cache ID namespace. |
EdgeCacheable | Servlet | True or false. Default is false. If the property is true, then the given servlet or JSP file is externally requested from an Edge Side Include processor. Whether or not the servlet or JSP file is cacheable depends on the rest of the cache specification. |
ExternalCache | Servlet | Specifies the external cache name. The external cache name needs to match the external cache group name. |
consume-subfragments | Servlet or Web service | True or false. Default is false. When a servlet is cached, only the content of that servlet is stored, and includes placeholders for any other fragments to which it includes or forwards. Consume-subfragments (CSF) tells the cache not to stop saving content when it includes a child servlet. The parent entry, the one marked CSF, includes all the content from all fragments in its cache entry, resulting in one big cache entry that has no includes or forwards, but the content from the whole tree of entries. This can save a significant amount of application server processing, but is typically only useful when the external HTTP request contains all the information needed to determine the entire tree of included fragments. |
do-not-consume | Servlet or Web service | True or false. Default is false. When a fragment parent has the consume-subfragment property set to true the child fragment content is saved in the cache entry of the parent. Do-not-consume (DNC) tells the cache to stop saving the content for this fragment in the parent cache-entry and create a placeholder instead for the include or forward. |
alternate_url | Servlet | Specifies the alternate URL used to invoke the servlet or JSP file. The property is valid only if the EdgeCacheable property also is set for the cache entry. |
persist-to-disk | All | True or false. Default is true. When this property is set to false, the cache entry is not written to the disk when overflow or server stopping occurs. |
save-attributes | Servlet | True or false. Default is true. When this
property is set to false, the request attributes are not saved with the cache
entry. Use the <exclude> element to specify the request attributes that
do not apply to the save-attributes property. For example, to save only the attr1 attribute
with the cache entry:
<property name="save-attributes">false <exclude>attr1</exclude> </property>To save all attributes except the attr1 attribute in the cache entry, set the property to true in the preceding sample. If you do not use the <exclude> element, either all or no request attributes are saved with the cache entry. |
delay-invalidations | command | True or false. When this property is set to true, the commands that are invalidating cached objects based on the invalidation rules in this cache entry invalidate the cache entries after running. By default, the invalidation occurs before the command runs. |
cache-id
<cache-id>component*| timeout? | inactivity? | priority? | property* | idgenerator? | metadatagenerator?</cache-id>
component sub-element
Use the component sub-element to generate a portion of the cache ID. The component sub-element consists of the attributes id, type, and ignore-value, and the elements index,method, field, required, value, and not-value.
Type | Valid classes | Meaning |
---|---|---|
method | command | Calls the indicated method on the command or object |
field | command | Retrieves the named field in the command or object |
parameter | servlet | Retrieves the named parameter value from the request object |
parameter-list | servlet | Retrieves a list of values for the named parameter |
session | servlet | Retrieves the named value from the HTTP Session |
cookie | servlet | Retrieves the named cookie value |
attribute | servlet | Retrieves the named request attribute |
header | servlet and Web service | Retrieves the named request header |
pathInfo | servlet | Retrieves the pathInfo from the request |
servletpath | servlet | Retrieves the servlet path |
locale | servlet | Retrieves the request locale |
requestType | servlet | Retrieves the HTTP request method from the request. |
tiles_attribute | servlet | Retrieves the value of an attribute from a tile. |
SOAPEnvelope | Web service and Web services client cache | Retrieves the SOAPEnvelope from a Web services request. An ID attribute of Hash uses a Hash of the SOAPEnvelope, while Literal uses the SOAPEnvelope as received. |
SOAPAction | Web service | Retrieves the SOAPAction header, (if available), for a Web services request. |
serviceOperation | Web service | Retrieves the service operation for a Web services request |
serviceOperationParameter | Web service | Retrieves the specified parameter from a Web services request |
operation | Web services client cache | An operation type in the Web Services Description Language (WSDL) file. The id attribute is ignored and the value is the operation or method name. If the namespace of the operation is specified, the value should be formatted as namespaceOfOperation:nameOfOperation |
part | Web services client cache | An input message part of in the WSDL file or a request parameter. Its id attribute is the part or parameter name, and the value is the part or parameter value. |
SOAPHeaderEntry | Web services client cache | Retrieves special information in the Simple Object Access Protocol
(SOAP) header of the Web services request. The id attribute specifies
the name of the entry. In addition, the entry of the SOAP header in the SOAP
request must have the "actor" attribute which contains com.ibm.websphere.cache.
For example:<soapenv:Header> <getQuote soapenv:actor="com.ibm.websphere.cache">IBM</getQuote> </soapenv:Header> |
<component id="getUser" type="method"><method>getUserInfo <method>getName</method></method></component>
This method is equivalent to getUser().getUserInfo().getName()
<cache-entry> <class>servlet</class> <name>xxx.jsp</name> <cache-id> . . <component id="users" type="attribute"> <required>true</required> </component> . . </cache-id> <dependency-id>dep <component id="users" type="attribute"> <required>true</required> </component> </dependency-id> </cache-entry>The cache id contains the string users: a,b. The dependency id is dep: a,b.
<cache-entry> <class>servlet</class> <name>xxx.jsp</name> <cache-id> . . <component id="users" type="attribute"> <required>true</required> </component> . . </cache-id> <dependency-id>dep <component id="users" type="attribute" multipleIDs="true"> <required>true</required> </component> </dependency-id> </cache-entry>The cache policy will generates the following dependency IDs:
<cache-entry> <class>servlet</class> <name>xxx.jsp</name> <cache-id> . . <component id="users" type="attribute"> <required>true</required> <index>1</index> </component> . . </cache-id> <dependency-id>dep <component id="users" type="attribute" multipleIDs="true"> <required>true</required> </component> </dependency-id> </cache-entry>The above cache policy generates the following component to be used in the cache ID: users: b. Use the <method> element to call a void method on a returned object.
<component id="getUser" type="method"><method>getUserInfo <field>name</field></method></component>
This method is equivalent to getUser().getUserInfo().name
<required>true</required>
<component id="getUser" type="method"><value>blue</value> <value>red</value> </component>
<component id="getUser" type="method"> <required>true</required> <not-value>blue</not-value> <not-value>red</not-value></component>
<component id="isValid" type="method" ignore-value="true"><component>
timeout sub-element
<timeout>value</timeout>
where value is the amount of time, in seconds, to keep the cache entry. If 0, or a negative value is specified, the cache entry is kept indefinitely.
inactivity sub-element
<inactivity>value</inactivity>where value is the amount of time, in seconds, to keep the cache entry in the cache after the last cache hit.
priority sub-element
<priority>value</priority>
where value is a positive integer between 1 and 255 inclusive.
Samples
<cache-id> <component id="timeout" type="parameter"> <required>true</required> </component> <timeout>180</timeout> <inactivity>35</inactivity> <priority>1</priority> </cache-id>
<cache-id> <component id="timeout" type="parameter"> <required>true</required> </component> <inactivity>600</inactivity> <priority>1</priority> </cache-id>
<cache-id> <component id="timeout" type="parameter"> <required>true</required> </component> <timeout>180</timeout> <inactivity>600</inactivity> <priority>1</priority> </cache-id>
property sub-element
<property name="key">value</property>
where key is the name of the property to define, and value is the corresponding value.
<property name="description">The Snoop Servlet</property>
Property | Valid classes | Meaning |
sharing-policy/timeout/priority | All | Overrides the settings for the containing cache entry when the request matches this cache ID. |
EdgeCacheable | servlet | Overrides the settings for the containing cache entry when the request matches this cache ID. |
idgenerator and metadatagenerator sub-elements
<idgenerator> classname </idgenerator>Classname is the fully qualified name of the class to use. Define this generator class in a shared library.
<metadatagenerator> classname </metadatagenerator>In this example, classname is the fully qualified name of the class to use. Define this generator class in a shared library.
dependency-id element
Use the dependency-id element to specify additional cache identifiers that associate multiple cache entries to the same group identifier.
The value of the dependency-id element is generated by concatenating the dependency ID base string with the values returned by its component elements. If a required component returns a null value, the entire dependency does not generate and is not used. Validate the dependency IDs explicitly through the dynamic cache API, or use the invalidation element. Multiple dependency ID rules can exist in one cache-entry element. All dependency rules execute separately.
invalidation element
<invalidation>component* | invalidationgenerator? </invalidation>
invalidationgenerator sub-element
<invalidationgenerator>classname</invalidationgenerator>In this example, classname is the fully qualified name of the class that implements the com.ibm.websphere.cache.webservices.InvalidationGenerator interface. Define this generator class in a shared library.
Related tasks
Configuring cacheable objects with the cachespec.xml file
Related reference
Example: Configuring the dynamic cache