Defining the invalidation policies in cachespec.xml

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

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:

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>

Feedback