WebSphere Application Server dynamic caching supports the configuration of cache invalidation through the use of the cachespec.xml file. Invalidation policies can be dynamically defined in the same cachespec.xml that is used for configuring the cacheable objects, found inside the Web Application Archive (WAR) WEB-INF or enterprise bean WEB-INF directory. For detailed information of the cachespec.xml syntax, see the topic "Cachespec.xml file" in the WebSphere Application Server Information Center.
Invalidation rules can be specified within a cache-entry with an <invalidation> tag that defines an event that must invalidate the corresponding cache entries, or with a <timeout> tag that configures the duration to keep the cache entries. They are defined in exactly the same manner as dependency IDs and the IDs generated by the invalidation rules are used to invalidate cache entries that have those same dependency IDs. Multiple invalidation rules can exist per cache-entry. All invalidation rules execute separately.
The following sections discusses the syntax of these invalidation rules in cachespec.xml and shows examples on how to apply the rules in WebSphere Commerce for the following:
- Servlet-based invalidation rules
- Command-based invalidation rules
- Timeout and priority invalidation rules
Servlet-based invalidation rules
Servlet-based invalidation means that invalidation rules are triggered when the servlet passes through its service method. This method of invalidation provided by WebSphere Application Server dynamic caching is to invalidate other cache entries upon execution of a servlet request. Since WebSphere Commerce only supplies a single servlet (com.ibm.commerce.server.RequestServlet), the pathinfo component must be used as a filtering mechanism to catch a specific URI call.
Syntax in cachespec.xml
<cache-entry> <class>servlet</class> <name>servlet_name</name> <invalidation>invalidation_id <component id="" type="pathinfo"> .... </component> </invalidation> </cache-entry>
In the above example cachespec.xml file, note the following:
- <class>
- A value of "servlet" indicates that the invalidation is triggered by a servlet.
- <invalidation>
- An element that is used to identify the event that triggers the invalidation and what cache entries with the specified ID to invalidate.
- pathinfo
- In WebSphere Commerce, all servlet requests go through a single controller servlet which is either: com.ibm.commerce.server.RequestServlet.class or com.ibm.commerce.tools.common.ToolsRequestServlet.class.
To identify an unique request URI, the "pathinfo" component type can be used to filter the pathinfo name from the request.
An example of polices defined in cachespec.xml
To invalidate the interest item list cache page identified by its reference number when an InterestItemDelete URL is issued to delete catalog entries from the list:
<cache-entry> <class>servlet</class> <name>com.ibm.commerce.server.RequestServlet.class</name> <invalidation>listId <component id="" type="pathinfo" ignore-value="true"> <required>true</required> <value>/InterestItemDelete</value> </component> <component id="listId" type="parameter"> <required>true</required> </component> </invalidation> </cache-entry>
The example above specifies a policy to invalidate any cache entries that can be identified by the same listId. It intercepts calls to the InterestItemDelete URI which deletes catalog entries from an interest item list, and generates the invalidation ID based on the listId parameter value provided to the URI. Upon execution of the servlet, dynamic cache compares the invalidation IDs with each of the dependency IDs for the same identifier and value. Any cache entries that are associated with such dependency IDs are removed.
Command-based invalidation rules
Command-based invalidation means that the invalidation rules are executed upon execution of a command which extends from the WebSphere Commerce Command Framework API. Invalidation IDs for command-based invalidation are constructed based on methods and fields provided by the commands. In this way, this method invalidates other cache entries as a side effect of running a command. It provides an event-driven mechanism to trigger the invalidation at the command level in WebSphere Commerce. Users can examine the business logic written in a command and identify specific cache objects that might be affected upon successful execution of the command and then define the invalidation rules accordingly.
One criteria of such commands is that they must implement the WebSphere Commerce Programming Model. The methods and the fields in the commands that handle the input parameters must be externalized if the invalidation IDs are going to be generated based on those input parameters.
Refer to the WebSphere Application Server documentation for details of this support. See also, Writing commands for command-based invalidation.
Syntax in cachespec.xml
<cache-entry> <class>command</class> <name>fully_qualified_class_name_of_the_command</name> <invalidation>invalidation_rules</invalidation> </cache-entry>
In the above example cachespec.xml file, note the following:
- <class>
- A value of command indicates that the invalidation is triggered by a command.
- <name>
- Contains the fully qualified path of the command.
Example of polices defined in cachespec.xml
To invalidate the product display page cached by its reference number when the CatalogEntryUpdate command is invoked to change the catalog entry:
<cache-entry> <class>command</class> <name>com.ibm.commerce.catalogmanagement.commands.CatalogEntryUpdateCmdImpl</name> <invalidation>productId <component id="getCatentryId" type="method"> <required>true</required> </component> </invalidation> </cache-entry>
The example above specifies a policy to invalidate any cache entries that can be identified by the same productId. It intercepts calls to the CatalogEntryUpdate command which update a catalog entry and generates the invalidation ID based on the value returned by the getCatentryId method. Upon execution of the servlet, dynamic cache compares the invalidation IDs with each of the dependency IDs for the same identifier and value. Any cache entries associated with such dependency IDs are removed.
When building the command-based invalidation polices in cachespec.xml, keep in mind the following restrictions:
- Only the methods invoked by the command that return the input instance variables can be used in the method component.
- All the methods that are used to construct the invalidation IDs, must be provided in the command interface and be implemented.
- The methods to be used in the method component must only return single value.
- The request attributes component type cannot be used.
Timeout and priority-based invalidation rules
The timeout mechanism using the <timeout> tag in a policy provides a simple way to remove any cache entries after a preset duration. The mechanism is useful when it is not feasible to set up specific invalidation rules or trigger events that are timed to remove the cache entries.
The WebSphere Application Server dynamic caching service automatically removes cache entries when the cache is full based on a modified Least Recently Used (LRU) algorithm, in which a priority weighting using the <priority> tag is used to decide which entries to remove from the cache. The higher the priority value for a particular cache entry relative to other cache entries, the longer this cache entry tends to stay in the cache relative to others.
Rather than removing the entries from memory when the cache becomes full, you can configure disk offload and have the entries copied onto the file system for use later. (The location is configurable.) Cache entries will also be off-loaded to disk upon server shut down and can be reused when the server is restarted. In addition, the following dynamic cache service settings also affect the invalidation process:
- Cache Size
- Determines the maximum number of entries the cache holds.
- Default Priority
- Determines by default, how long an entry stays in a full cache
- Disk offload
- Specifies whether disk offload is enabled, and disk offload location.
Syntax in cachespec.xml
<cache-entry> ....... <cache-id> <component >.......</component> <priority>priority_value</priority> <timeout>time_in_cache</timeout> </cache-id> </cache-entry>
Example of policies defined in cachespec.xml
To remove the shopping cart cache content 3600 seconds after it is created or used:
<cache-id> <component id="" type="pathinfo"> <required>true</required> <value>/OrderItemDisplay</value> </component> <component id="orderId" type="parameter"> <required>true</required> </component> <timeout>3600</timeout> </cache-id>