Additional HCL Commerce data cache configuration

To refine the configuration of the HCL Commerce data cache, add a <CrossTransactionCache> element, or a <LocalTransactionCache> element to the <InstanceProperties> element of the HCL Commerce configuration file wc-server.xml.

Note: While migrating from WebSphere Commerce version 7 or 8 to HCL Commerce version 9.x, you must remove the CrossTransactionCache tag added to use the default values. If you have modified some of the values, review the reason for not using the default values, and decide whether to keep the custom values or accept the default values. However, using default values is recommended.

<CrossTransactionCache> element

The cross transaction cache holds data that persists across transactions until expired by DynaCache.

The following code demonstrates how the available elements are defined for the cross transaction cache. The possible values for an element are included, for instance [seconds|172800]. The value for this element can be any positive number (in seconds). The default value, which is in bold text, is 172800.

<CrossTransactionCache
  enabled="[true|false]"
  commandCaching="[on|off|default]"
  maxInactivityTime="[seconds|86400]"
  maxTimeToLive="[seconds|172800]"
  maxTimeToLiveForAutoCacheEntries="[seconds|0]"
  autoCacheableTableNames="string"
  notAutoCacheableTableNames="string"
  defaultResultSizeThreshold="[number|8]"
  clearUserOnLogoff="[true|false]" 
  clearUserDataCacheOnLogoff="[true|false]"
  maxInvalidationldsPerTransaction="[number|100000]"
  clearCacheOnMaxInvalidationIdsPerTransaction="[true|false]"
  reduceMemory="[true|false]"
  chunkSize="[number of rows|50]"
  delayAfterInvalidationMilliseconds="[milliseconds|0]"
  delayAfterInvalidationPercentBuffer="[percent|-1]"
  delayAfterInvalidationTuneIntervalSeconds="[seconds|60]"
  restCaching="[true|false]"
  reduceInvalidationIds="[true|false]"
  sizeable="[true|false]"
  CacheName="[disabled|DistributedMapName|commandCaching]"
  avoidConcurrentCacheMiss="[true|false]">
  
  <DistributedMapName
    enabled="[true|false]"
    maxInactivityTime="seconds"
    maxTimeToLive="seconds"
    maxTimeToLiveForAutoCacheEntries="[seconds|0]"
    reduceMemory="[true|false]"
    delayAfterInvalidationMilliseconds="[milliseconds|0]"
    delayAfterInvalidationPercentBuffer="[percent|-1]"
    delayAfterInvalidationTuneIntervalSeconds="[seconds|60]"
    restCaching="[true|false]"
    chunkSize="[number of rows|50]"
    avoidConcurrentCacheMiss="[true|false]">/>
  
  <CacheName
    enabled="[true|false]"
    maxInactivityTime="seconds"
    maxTimeToLive="seconds"
    maxTimeToLiveForAutoCacheEntries="[seconds|0]"
    reduceMemory="[true|false]"
    delayAfterInvalidationMilliseconds="[milliseconds|0]"
    delayAfterInvalidationPercentBuffer="[percent|-1]"
    delayAfterInvalidationTuneIntervalSeconds="[seconds|60]"
    restCaching="[true|false]"
    chunkSize="[number of rows|50]"
    avoidConcurrentCacheMiss="[true|false]">/>
    
</CrossTransactionCache>

Where:


Element name	Possible values (default values in bold)	Usage
enabled	true\|false	Specify `false` to turn off cross transaction caching
commandCaching	on\|off\|default	Specify on to force the cross transaction cache to use command caching in the default baseCache DistributedMap. Specify off to prevent the cross transaction cache from using command caching. The default setting uses DistributedMap caching when the corresponding DistributedMap is found by using its JNDI name, and otherwise uses command caching in the default DistributedMap.
maxInactivityTime	`seconds`\|86400	Specify the number of seconds after which an inactive cache entry is removed from the cache due to inactivity. This setting has no effect when command caching is used. Instead, use the `<inactivity>` tag in the cachespec.xml file.
maxTimeToLive	`seconds`\|172800\|0	In order to prevent possible problems due to slight delays in propagation of invalidation messages, the default maxTimeToLive value for the following logical caches is zero (effectively disabling caching): `com.ibm.commerce.component.contextservice.commands.ContextDataSerValueCacheCmdImpl com.ibm.commerce.user.objects.MemberAccessBean com.ibm.commerce.user.objects.UserAccessBean com.ibm.commerce.user.objects.UserRegistryAccessBean com.ibm.commerce.membergroup.commands.ListMemberGroupsForUserCmdImpl com.ibm.commerce.marketing.promotion.runtime.PromotionArgumentSessionBeanPersistenceManager com.ibm.commerce.marketing.promotion.coupon.CouponSessionBeanPersistenceManager` Specifying a positive maxTimeToLive value overrides the default value (effectively re-enabling caching). If you choose to do so, consider also specifying a value for the delayAfterInvalidationMilliseconds setting (a different value can be specified for each logical cache). The delayAfterInvalidationMilliseconds setting can be used to allow time for invalidation message processing to complete before execution continues after the cached data is modified in the database. For example, you may start with a value of 500 milliseconds and then experiment to find a more optimal value.
autoCacheableTableNames notAutoCacheableTableNames	`string`	The autoCacheableTableNames and notAutoCacheableTableNames settings are defined only at the global level, and each is a white space delimited list of database table names, where spaces, new lines, and tabs are treated as white space. If a table name appears in both settings, then the notAutoCacheableTableNames setting has precedence. By default, the data cache assumes certain table names (such as USERS and ORDERS) also disqualify a query for auto caching, unless the names appear in the autoCacheableTableNames setting. By default, these string values are empty.
maxTimeToLiveForAutoCacheEntries	`seconds`\|0	When a positive number of seconds is specified, then certain qualifying JDBC query results are cached using the following logical caches: com.ibm.commerce.base.objects.ServerJDBCHelperBean com.ibm.commerce.foundation.internal.server.services.dataaccess.queryservice.XPathSQLProcessor com.ibm.commerce.foundation.server.services.dataaccess.JDBCQueryService com.ibm.commerce.foundation.internal.server.services.dataaccess.graphbuilderservice.jdbc.JDBCMediatorSupplyQuery To qualify for auto caching, a JDBC query should reference one or more of the table names included in the autoCacheableTableNames setting, and must not reference any of the table names included in the notAutoCacheableTableNames setting. Use the IBM Extended Cache Monitor to see which queries are being cached, and their dependency ids. By default, auto cached query results are cached in the object cache with JNDI name services/cache/WCMiscDistributedMapCache. While auto caching can improve performance, use this feature with care. Know which queries are being cached, and ensure an acceptable cache invalidation technique is used, such as a short time to live, or database triggers that add appropriate cache invalidation ids to the CACHEIVL table in the DATAID column.
defaultResultSizeThreshold	`number`\|8	When the size of the collection of objects to be cached in a cache entry exceeds the specified threshold value, dependency IDs are generated by using table names. To reduce the number of dependency IDs generated for the cache entry, column names and values are not used.
clearUserOnLogoff	true\|false	Specify `false` if DC_userid:nnnn invalidation ids are not to be sent to the baseCache when the user with user ID`nnnn` logs off.
clearUserDataCacheOnLogoff	true\|false	Specify `true` if data cache entries specific to a particular user are removed from the cache when the user logs off.
maxInvalidationldsPerTransaction	`number`\|100000	Specify the maximum number of cross transaction cache invalidation operations that can be run in a single transaction. Knowledge of each invalidation operation run must be retained during the current transaction. A long running transaction that runs too many invalidation operations can run out of memory. When the specified limit is reached, no further invalidationIDs are remembered for the cross transaction cache for the remainder of the current transaction. When the transaction completes: The entire cross transaction cache is cleared. The action that is specified by the clearCacheOnMaxInvalidationIdsPerTransaction configuration is taken.
clearCacheOnMaxInvalidationIdsPerTransaction	true\|false	Specifies the action when the maximum number of cross transaction cache invalidation operations, which are specified by the maxInvalidationIdsPerTransaction element, is exceeded. Specify true to clear the entire cross transaction cache after the current transaction ends. When this element is set to false, invalidations are issued immediately and are not remembered until the end of the current transaction. This setting leaves a small window of time during which stale data can be placed into the cache.
reduceMemory	true\|false	Specify `true` to reduce the memory footprint of the cross transaction cache.
chunkSize	`number of rows`\|50	Some database queries might return hundreds or even thousands of rows. The returned rows are split into multiple cache entries to maintain the cache memory footprint, and to help avoid problems that are related to running out of memory. This parameter specifies the number of rows to be cached in each cache entry.
delayAfterInvalidationMilliseconds	`milliseconds`\|0	This parameter allows for a small delay to be added before a response is sent to the client browser for any transaction that involves an invalidation. This delay can help prevent the client from making a subsequent request before the invalidation is fully processed on the server. If enabled by a value greater than `0`, then the delay that is used by your site is the larger value (a minimum delay) between delayAfterInvalidationMilliseconds and the value that is calculated by delayAfterInvalidationPercentBuffer, if that parameter is enabled by a non-negative value.
delayAfterInvalidationPercentBuffer	`percent`\|-1	This parameter defines a percentage time buffer, the `pc` value, that is added within a calculated (variable) delay value. The delay that is used by your site is then determined to be the larger value (a minimum delay) between the set delayAfterInvalidationMilliseconds delay value, and the variable delay value that is calculated using delayAfterInvalidationPercentBuffer. The calculation is done by deriving the real delay between when a transaction has ended and invalidation ids have been issued, and then adding the specified percentage time buffer (`pc`). The delay value is calculated at each period interval specified by delayAfterInvalidationTuneIntervalSeconds. At this interval, a sample of the time that it takes for a round trip invalidation message (the send and receive of a unique invalidation message) is taken to be used in the calculation. For positive values of delayAfterInvalidationPercentBuffer, the delay value is calculated as `rt` + (`rt`*`pc`/100). Where `rt` is the round trip time sample, and `pc` is the specified percent value. Accepted values: A negative number (`-1`) is specified to indicate that delayAfterInvalidationMilliseconds remains the delay that is used. This is the default value. By specifying `0`, the round trip time sample (`rt`), without an added buffer, is compared with delayAfterInvalidationMilliseconds to derive the delay that is used. By specifying a positive integer (`1` or greater), the round trip time sample, with the added percentage buffer, is compared with delayAfterInvalidationMilliseconds to derive the delay that is used. Note: This parameter requires that delayAfterInvalidationMilliseconds be set to a value greater than its default of `0`. Otherwise, no delay is used.
delayAfterInvalidationTuneIntervalSeconds	`seconds`\|60	The number of seconds between samples of how long it takes to send and receive an invalidation message. This value is used to derive the variable delay buffer for delayAfterInvalidationPercentBuffer.
restCaching	true\|false	This parameter allows you to disable caching while REST services are running.
reduceInvalidationIds	true\|false	Specify `true` to reduce the number of invalidation messages that are issued when cached data changes in the database. Systems with many HCL Commerce application server JVMs might benefit from this setting. However, some over-invalidation might occur. Measure the overall performance impact before you choose this setting for a production system.
sizeable	true\|false	Specify `true` to implement the com.ibm.websphere.cache.Sizeable interface for most cache entries that are used by the following HCL Commerce object caches: services/cache/DM_Cache (Marketing cache) services/cache/DM_UserCache (Marketing user behavior cache) dmap/IVCache (External Inventory availability cache) dmap/PriceCache (External Price cache) dmap/PR_Cache (Price Rule cache) services/cache/WC*DistributedMapCache (all the "data cache" object cache instances) Specifying true also implements the com.ibm.websphere.cache.Sizeable interface for most cacheable commands that are used by default by HCL Commerce.
`CacheName` For example, com.ibm.commerce.user.objects.OrganizationAccessBean	disabled\|`DistributedMapName` \|commandCaching	`CacheName` specifies a logical cache that is used by the Commerce Data Cache. `DistributedMapName` is a name that is prefixed with services/cache/. The `DistributedMapName` forms a JNDI name that is used to locate a DistributedMap that used to hold data for the specified logical cache. The actual DistributedMap used is the first of the following DistributedMap objects found to exist: `services/cache/CacheName` `services/cache/DistributedMapName` `services/cache/WCDistributedMapCache` the default baseCache DistributedMap See Logical cache names and the DistributedMaps they use by default. Specify disabled to prevent caching for the specified logical cache. Specify commandCaching to use command caching in the default baseCache DistributedMap.
avoidConcurrentCacheMiss	true\|false	Specify `true` to only allow one thread at a time to execute the same query with the same parameters.
<`DistributedMapName`/> For example, <WCUserDistributedMapCache enabled="false"/>	enabled="[true\|false]" maxInactivityTime="[`seconds`\|86400]" maxTimeToLive="[`seconds`\|172800]" maxTimeToLiveForAutoCacheEntries="[`seconds`\|0]" reduceMemory="[true\|false]" chunkSize="[`number of rows`\|50]" delayAfterInvalidationMilliseconds="[`milliseconds`\|0]" delayAfterInvalidationPercentBuffer="[`percent`\|-1]" delayAfterInvalidationTuneIntervalSeconds="[`seconds`\|60]" restCaching="[true\|false]" avoidConcurrentCacheMiss="[true\|false]">	Specify enabled=`false` to prevent use of the DistributedMap whose name is `services/cache/DistributedMapName`. Use the maxInactivityTime, maxTimeToLive, reduceMemory, chunkSize, delayAfterInvalidationMilliseconds, and restCaching settings to override the corresponding global settings. They apply only to cache entries in the specified DistributedMap.
<`CacheName`/> For example, <com.ibm.commerce.user.objects.OrganizationAccessBean enabled="false"/>	enabled="[true\|false]" maxInactivityTime="[`seconds`\|86400]" maxTimeToLive="[`seconds`\|172800]" maxTimeToLiveForAutoCacheEntries="`seconds`\|0" reduceMemory="[true\|false]" chunkSize="[`number of rows`]\|50" delayAfterInvalidationMilliseconds="[`milliseconds`\|0]" delayAfterInvalidationPercentBuffer="[`percent`\|-1]" delayAfterInvalidationTuneIntervalSeconds="[`seconds`\|60]" restCaching="[true\|false]" avoidConcurrentCacheMiss="[true\|false]">	Specify enabled=`false` to prevent caching for the specified logical cache unless commandCaching is explicitly specified for that logical cache. Use the maxInactivityTime, maxTimeToLive, reduceMemory, chunkSize, delayAfterInvalidationMilliseconds, and restCaching settings to override the corresponding global and DistributedMap settings. They apply only to cache entries for the specified logical cache. The maxInactivityTime and maxTimeToLive settings have no effect when command caching is used. Instead, use the `<inactivity>` and `<timeout>` tags in the cachespec.xml file.

Improving performance in the Authoring environment

You can use the following endpoint and sample message body to tune the cache performance of your Authoring environment. The method is to change the cache's maximum TTL using a POST or PATCH call:

https://dataQueryHost:dataQueryPort/search/resources/api/v2/configuration?nodeName=component&envType=auth

Values in the sample request body are given in seconds. These values can be adjusted for each cache as required.

Considerations for the sizeable element

When all of your cache entries for a cache instance implement the com.ibm.websphere.cache.Sizeable interface, DynaCache is able to control the cache memory footprint. For more information, see Dynamic cache service settings.
A cache entry that implements the com.ibm.websphere.cache.Sizeable interface provides an estimate of its memory footprint to DynaCache. This estimate allows DynaCache to control the overall memory footprint of each cache instance. The accuracy of this estimate can vary. Observed estimates for the following object caches are slightly higher than the actual memory footprint.
- services/cache/DM_Cache (Marketing cache)
- services/cache/DM_UserCache (Marketing user behavior cache)
- dmap/IVCache (External Inventory availability cache)
- dmap/PriceCache (External Price cache)
- dmap/PR_Cache (Price Rule cache)
- services/cache/WC*DistributedMapCache (all the "data cache" object cache instances)
DynaCache disables this capability for a cache instance when it detects a cache entry, in that instance, that does not implement the com.ibm.websphere.cache.Sizeable interface in a cache instance. For example, custom cacheable commands in the baseCache. When this capability is disabled, a message like the following is placed in the SystemOut.log:
```
DYNA1067E: The cache size in MB feature is disabled because the cached object is not sizeable.
```
While DynaCache automatically implements the com.ibm.websphere.cache.Sizeable interface for servlet (JSP) cache entries, the sizes that are calculated for these entries can be underestimated. For example, the actual memory footprint of the baseCache servlet cache can be larger than the calculated memory footprint that is reported by the cache monitor application. Because of this underestimating of the required memory size, you are not recommended to specify the memory size in MB for servlet cache instances.
The normal cache maximum size setting is also used to limit the number of cache entries that are kept in memory. Specify a sufficient maximum size setting for each cache instance, to control the memory footprint and prevent potential out of memory conditions.

<LocalTransactionCache> element

The local transaction cache holds cache entries in memory for the duration of a single database transaction.

<LocalTransactionCache
       enabled="[true|false]"
       maxSize="[number|50000]"
       maxInvalidationldsPerTransaction="[number|50000]"
       CacheName="[disabled|enabled]"/>

Where:


Element name	Possible values (defaults in bold)	Usage
enabled	true\|false	Specify false to turn off local transaction caching. Do not turn off local transaction caching, except as part of problem determination. Note: Never turn off local transaction caching without also turning off cross transaction caching.
maxSize	`number`\|50000	Specify the maximum number of cache entries that can be remembered for the duration of a transaction. Each cache entry remains in memory until the current transaction completes. A long running transaction that creates too many cache entries can run out of memory. When the specified limit is reached, the transaction cache stops creating cache entries for the remainder of the current transaction. This setting prevents an out of memory condition.
maxInvalidationldsPerTransaction	`number`\|50000	Specify the maximum number of cache invalidation operations that can be run in a single transaction. Knowledge of each invalidation operation that is executed must be retained for the duration of the current transaction. A long running transaction that executes too many invalidation operations can run out of memory. When the specified limit is reached, the entire transaction cache is cleared and knowledge of individual invalidation operations is removed from memory. This setting prevents an out of memory condition. Use of the cross transaction cache is suspended for the remainder of the transaction. All cache entries are considered to be invalidated for the remainder of the transaction.
`CacheName` For example: com.ibm.commerce.user.objects.OrganizationAccessBean	disabled\|enabled	`CacheName` specifies the name of a logical cache. Specify disabled to prevent caching in the specified logical cache. Do not turn off local transaction caching, except as part of problem determination. Note: Never turn off local transaction caching for a logical cache without also turning off cross transaction caching for the same logical cache.