Additional WebSphere Commerce data cache configuration

To refine the configuration of the WebSphere Commerce data cache, add a <CrossTransactionCache> element, or a <LocalTransactionCache> element to the <InstanceProperties> element of the WebSphere Commerce configuration file.

For more information about the WebSphere Commerce configuration file, see Updating the WebSphere Commerce configuration file.

<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|500]"
  delayAfterInvalidationMilliseconds="[milliseconds|0]"
  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]"
    restCaching="[true|false]"
    chunkSize="[number of rows|500]"/>
  
  <CacheName
    enabled="[true|false]"
    maxInactivityTime="seconds"
    maxTimeToLive="seconds"
    maxTimeToLiveForAutoCacheEntries="[seconds|0]"
    reduceMemory="[true|false]"
    delayAfterInvalidationMilliseconds="[milliseconds|0]"
    restCaching="[true|false]"
    chunkSize="[number of rows|500]"/>
    
</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 Specify the number of seconds after which a cache entry expires and is removed from the cache.

This setting has no effect when command caching is used. Instead, use the <timeout> tag in the cachespec.xml file.

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 cache entries specific to a particular user are not removed from the cache when the user logs off.
  • Specify false if DC_userid:nnnn invalidation ids are not to be sent to the baseCache when the user with user IDnnnn 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|1000000
  • 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|500 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.
restCaching true|false This parameter allows you to disable caching while REST services are running. You need to do this for the WCUserDistributedMapCache and WCSessionDistributedMapCache DistributedMap object caches if the Domain Replication Service is not configured to replicate cache invalidation messages between all WebSphere Commerce application servers for those object caches.
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 WebSphere 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 WebSphere 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)
  • 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 WebSphere Commerce.

This setting does not implement the com.ibm.websphere.cache.Sizeable interface for the Price Rule cache prior to FEP7.
CacheName

For example, com.ibm.commerce.user.objsrc.OrganizationCache

 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"

maxTimeToLive="seconds"

maxTimeToLiveForAutoCacheEntries="seconds"

reduceMemory="[true|false]"

chunkSize="number of rows"

delayAfterInvalidationMilliseconds="milliseconds"

Specify enabled=false to prevent use of the DistributedMap whose name is services/cache/DistributedMapName.

Use the maxInactivityTime, maxTimeToLive, reduceMemory, chunkSize, and delayAfterInvalidationMilliseconds settings to override the corresponding global settings. They apply only to cache entries in the specified DistributedMap.
<CacheName/>

For example, <com.ibm.commerce.user.objsrc.OrganizationCache enabled="false"/>

 enabled="[true|false]"

maxInactivityTime="seconds"

maxTimeToLive="seconds"

maxTimeToLiveForAutoCacheEntries="seconds"

reduceMemory="[true|false]"

chunkSize="number of rows"

delayAfterInvalidationMilliseconds="milliseconds"

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, and delayAfterInvalidationMilliseconds 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.
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)
    • services/cache/WC*DistributedMapCache (all the "data cache" object cache instances)
    DynaCache disables this capability for a cache instance when DynaCache detects that a cache entry 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.

Default CrossTransactionCache Settings:

The following XML snippet shows the default CrossTransactionCache settings. Copy this snippet into your wc-server.xml file, in the InstanceProperties tag. Use it as a starting point when you enable only the logical caches that you choose.
Note: When you copy into the wc-server.xml file, ensure that there is only one CrossTransactionCache tag. If there is already an existing CrossTransactionCache tag in wc-server.xml, the data cache might already be configured with non-default settings.
Copy the snippet:

<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|1000000
  • 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|1000000
  • 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.objsrc.OrganizationCache

 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.