Configuring the dynamic cache service in cachespec.xml

The dynamic cache service is an in-memory cache system that has disk offload capability. Cacheable objects are defined in the cachespec.xml file.

You can find cachespec.xml inside the Web application archive (WAR), Web module WEB-INF directory, or enterprise bean WEB-INF directory. The Elasticsearch Query service version of the file is located in /opt/WebSphere/Liberty/usr/servers/default/apps/search-query.ear/search-query.war/WEB-INF/cachespec.xml. You can modify any version of the file, however the Query service version is not automatically preserved through Docker container updates. You must manually maintain this version to preserve your modifications to it.

A global cachespec.xml file can also be placed in the application server properties directory, but the recommended method is to place the cache configuration file with the deployment module. There is a sample cache configuration file (cachespec.sample.xml) in the WAS_installdir/properties directory. The cachespec.dtd file is available in the application server properties directory. The following sections detail the steps that are required to configure dynamic caching in the cachespec.xml file.

Enabling the dynamic cache service

In the production environment, both the dynamic cache service and servlet caching are enabled by default. If you enable dynamic caching in the authoring environment, you could encounter missed invalidations, and will not have access to the Preview Mode that you have in the production environment. In addition, in the case of the Elasticsearch Query service, baseCache is only enabled for the production environment. For more information about this parameter, see Integrating HCL Commerce version 9 with WebSphere eXtreme Scale.

Note: Servlet caching is disabled in the developer environment. To enable and use servlet caching, see Enabling the dynamic cache service and servlet caching.

Defining cache entry elements

The root element of the cachespec.xml file, <cache>, contains <cache-entry> elements. The WebSphere dynamic cache service parses the cachespec.xml file while the server starts, and extracts a set of configuration parameters from each <cache-entry> element.

Defining cache ID generation rules

As the dynamic cache service places objects in the cache, it labels them with unique identifying strings (cache IDs) constructed according to <cache-id> rules specified in the <cache-entry> elements. After an object with a particular cache ID is in the cache, a subsequent request for an object with the same cache ID is served from the cache. The <cache-id> rules define how to construct cache-IDs from information that is associated with an application server request, including how information might be obtained programmatically from CacheableCommand objects.

Each <cache-entry> can specify multiple <cache-id> elements to define multiple cache ID generation rules. They are executed in the order they appear in the <cache-entry> element until a rule generates a valid cache ID, or all the rules are run.
If none of the cache ID generation rules produce a valid cache ID, then the object is not cached.
Each <cache-id> element defines a rule for caching an object and is composed of the subelements <component>, <timeout>, <priority>, and <property>.
The <component> subelement can appear many times within the <cache-id>element. Each time that it specifies how to generate a component of a cache ID. There are several different types of component elements, such as parameter, session, attribute, locale, method, and field.

The following table lists the request attributes:


Request attributes	Description
`DC_curr`	User's preferred currency
`DC_lang`	User's preferred language
`DC_porg`	User's parent organization
`DC_cont`	User's current contract
`DC_mg`	User's explicit member groups
`DC_storeId`	Store identifier
`DC_userId`	User's identifier
`s`	Buyer's eligible contracts (only valid for Supply Chain business model)

The <timeout>,<priority>, and <property> subelements can be used to control cache entry expiry, cache eviction policy, and other generic properties for a cached object with an identifier generated by its enclosing <cache-id>element. For more information about the <cache-id> element, and its subelements, see the topic cachespec.xml.

The following <cache-entry>example uses a <cache-id>element to cache results that are created by a JSP and generate a cache ID with two components, "storeId" and "catalogId", obtained from parameters in the request object:


<cache-entry>
        <class>servlet</class>
        <name>/ToolTech/. .
./StoreCatalogDisplay.jsp</name>
        <property
name="save-attributes">false</property>
        <property name="store-cookies">false</property>
        <timeout>3600</timeout>
        <priority>3</priority>
        <cache-id>
                <component id="storeId" type="parameter">
                        <required>true</required>
                </component>
                <component id="catalogId" type="parameter">
                        <required>true</required>
                </component>
        </cache-id>
...
</cache-entry>

Defining dependency ID and invalidation ID generation rules

Dependency ID elements are used to specify additional cache group identifiers that associate multiple cache entries to the same group identifier.

Dependency IDs are generated by concatenating the dependency ID base string with the values returned by its component elements. If a required component returns a null value, then the entire dependency ID does not generate and is not used. You can validate dependency IDs explicitly through the WebSphere Dynamic Cache API, or use another cache-entry <invalidation> element. Dependency IDs are essential because invalidation cannot occur without them.

Invalidation IDs are used with dependency IDs to remove invalidated objects from the cache.

Invalidation IDs are generated according to rules specified by <invalidation> elements within <cache-entry> elements. When a request that matches a <cache-entry>element is received, its generated invalidation IDs are matched against the dependency IDs previously associated with cached objects. Cached objects with an associated dependency ID that is the same as one of the generated invalidation IDs are invalidated.

Each <cache-entry> element might contain several<invalidation> elements. Each <invalidation> element causes an invalidation ID to be generated when a request that matches its <cache-entry> element is received.

Each invalidation ID is generated by concatenating its invalidation ID base string with the values, each prefixed with a colon (":"), returned by its <component> subelements. If a required component returns a null value, then its part of the generated invalidation ID is discarded.

The following <cache-entry>example defines an <invalidation> element to generate an invalidation ID, "catalogId", when the CatalogUpdateCmdImpl command is run:


<cache-entry>
        <class>command</class>
               
<name>com.ibm.commerce.catalogmanagement.commands.CatalogUpdateCmdImpl</name>
        <invalidation>catalogId
                <component id="catalogId" type="parameter">
                        <required>true</required>
                </component>
        </invalidation>
</cache-entry>

In this example, when a request to run the specified command com.ibm.commerce.catalogmangement.commands.CatalogUpdateCmdImpl is received with parameters "storeId=10001&catalogId=10010", the generated invalidation ID is "catalogId:10010". That would cause any cached objects that are associated with a dependency ID of that value to be invalidated, effectively removing them from the cache.

Caching and the Elasticsearch Query service

Dynamic caching is enabled by default for the Elasticsearch Query service, in the Live environment only. Do not enable it for the Authoring environment, because you could encounter missed invalidations, and will not have access to the Preview Mode that you have in the Live environment.