The cache parses the cachespec.xml file on startup, and extracts from each <cache-entry> element a set of configuration parameters. Every time a new servlet or other cacheable object initializes, the cache attempts to match each of the different cache-entry elements, to find the configuration information for that object. Different cacheable objects have different <class> elements. You can define the specific object a cache policy refers to using the <name> element.
The cachespec.xml file is found inside the WEB-INF directory of a Web module.
You can place a global cachespec.xml file in the appserver properties directory, but the recommended method is to place the cache configuration file with the deployment module. (To place the cache configuration file with the deployment module, use the to define the cacheable objects.
The root element of the cachespec.xml file is cache, which contains cache-entry elements.
The cachespec.dtd file is available in the appserver properties directory.
Each cache entry must specify certain basic information that the dynamic cache uses to process that entry. This section explains the function of each cache entry element of the cachespec.xml file including...
<class>command | servlet | webservice</class>
This element is required and governs how the appserver interprets the remaining cache policy definition. The value servlet refers to servlets and JSP (JSP) files deployed in the WebSphere Application Server servlet engine. The object class extends the servlet with special component types for Web services requests. Finally, the value command refers to classes using the WebSphere command programming model. The following examples illustrate the class element:<class>command</class> <class>servlet</class> <class>webservice</class>
where name is the fully qualified class name of the command, servlet, or object.
There are two ways to use <name> to specify a cacheable object...
- For commands and objects, this required element must include the package name, if any, and class name, including a trailing .class, of the configured object.
- For servlets and JSP files, if the cachespec.xml file is in the WAS properties directory, this required element must include the full URI of the JSP file or servlet to cache. For servlets and JSP files, if the cachespec.xml file is in the web application (.war), this required element can be relative to the specific web application (.war) context root.
Note that The preferred location of the cachespec.xml file is in the web application (.war), not the properties directory.
You can specify multiple <name> elements within a <cache-entry> if you have different mappings that refer to the same servlet.
The following examples illustrate the name element<name>com.companyname.MyCommand.class</name> <name>default_host:/servlet/snoop</name> <name>com.companyname.beans.MyJavaBean</name> <name>mywebapp/myjsp.jsp</name>
<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. Also, in non-distributed environments, not-shared is the only valid value. When enabling replication, the default value is shared-push only. This property does not affect distribution to Edge servers through the Edge fragment caching property.
Value Description not-shared Cache entries for this object are not shared among different appservers. 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 appservers or cooperating 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 appservers on demand. If an appserver gets a cache miss for this object, it queries the cooperating appservers to see if they have the object. If no appserver has a cached copy of the object, the original appserver executes 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 appservers on demand. When an appserver generates a cache entry, it broadcasts the cache ID of the created entry to all cooperating appservers. Each server then knows whether an entry exists for any given cache ID. On a given request for that entry, the appserver knows whether to generate the entry or pull it from somewhere else. These entries cannot store non-serializable data.
The following example shows a sharing policy<sharing-policy>not-shared</sharing-policy>
where key is the name of the property defined for this cache entry element, and value is the corresponding value.
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 Server. 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 appserver processing, but is typically only useful when the external HTTP request contains all the information needed to determine the entire tree of included fragments. 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.
To cache an object, the appserver must know how to generate a unique ID for different invocations of that object. These IDs are built either from user-written custom Java code or from rules defined in the cache policy of each cache entry. Each cache entry can have multiple cache ID rules that are executed in order until either:
- A rule returns a non-empty cache ID, or
- No more rules are left to execute.
If none of the cache ID generation rules produce a valid cache ID, the object is not cached.
Each cache-id element defines a rule for caching an object and is composed of the sub-elements component, timeout, priority, and property. The following example illustrates a cache-id<cache-id>component*| timeout? | priority? | property* </cache-id>
Use the component sub-element to generate a portion of the cache ID. Each component sub-element consists of the attributes id, type, and ignore-value, and the elements method, field, required, value, and not-value.
- Use the id attribute to identify the component.
- Use the type attribute to identify the type of component. The following table lists the values for the type.
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 HTTPSession 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 SOAPEnvelope Web service 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
- Use the ignore-value attribute to specify whether or not to use the value returned by this component in cache ID formation. This is an optional attribute with a default value of false. If the value is true, only the ID of the component is used when creating a cache ID, or no output is used when creating a dependency or invalidation ID.
- Use the method element to call a void method on a returned object. You can infinitely nest method and field objects in any combination. The method must be public and is not valid for edge-cacheable components. For example<component id="getUser" type="method"><method>getUserInfo <method>getName</method></method></component>
This method is equivalent to getUser().getUserInfo().getName()
- Use the field element to access a field in a returned object. You can infinitely nest method and field objects in any combination. The field must be public. Not valid for edge-cacheable components. For example<component id="getUser" type="method"><method>getUserInfo <field>name</field></method></component>
This method is equivalent to getUser().getUserInfo().name
- Use the required element to specify whether or not this component must return a non-null value for this cache ID for it to represent a valid cache. If set to true, this component must return a non-null value for this cache ID to represent a valid cache ID. If set to false, the default, a non-null value is used in the formation of the cache ID and a null value means that this component is not used at all in the ID formation. For example<required>true</required>
- Use the value element to specify values that must match to use this component in cache ID formation. For example<component id="getUser" type="method"><value>blue</value> <value>red</value> </component>
- Use the not-value element to specify values that must not match to use this component in cache ID formation. This method is similar to <value>, but instead prescribes the defined values from caching. Use multiple <not-value> elements when there is more than one invalid value. For example<component id="getUser" type="method"> <required>true</required> <not-value>blue</not-value> <not-value>red</not-value></component>
The component element can have either a method or a field element, or a value or a not-value element. The method and field elements apply only to commands. The following example illustrates the attributes of a component element<component id="isValid" type="method" ignore-value="true"><component>
The timeout sub-element is used to specify a time-to-live (TTL) value for the cache entry. For example,<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.
Use the priority sub-element to specify the priority of a cache entry in a cache. The priority weighting is used by the least recently used (LRU) algorithm, of the cache to decide which entries to remove from the cache if the cache runs out of storage space. For example,
where value is a positive integer between 1 and 255 inclusive.
Use the property sub-element to specify generic properties for the cache entry. For example,
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.
Use the idgenerator element to specify the class name loaded for the generation of the cache ID. The IdGenerator must implement the com.ibm.websphere.servlet.cache.IdGenerator interface. The IdGenerator must build and set cache IDs, group IDs and invalidation IDs. An example of the idgenerator element follows
(where classname= Fully qualified name of the class to use)<idgenerator> classname classname </idgenerator>
Use the metadatagenerator element to specify the class name loaded for the metadata generation cache ID. The MetadataGenerator class must implement the com.ibm.websphere.servlet.cache.MetaDataGenerator interface. The MetadataGenerator defines properties like timeout, external caching or generic properties. An example of the metadatagenerator element follows
(where classname= Fully qualified name of the class to use)<metadatagenerator> classname classname </metadatagenerator>