DynaCacheInvalidation URL

The DynaCacheInvalidation command is a scheduled command that can be invoked on a URL to invalidate entries in the WebSphere Application Server dynamic cache.

The DynaCacheInvalidation command invalidates entries in the dynamic cache based on the dependency ID, cache ID, or template for a cached object that are recorded in the CACHEIVL table. The default cache invalidation interval is 4 minutes. You can change this default in the HCL Commerce Administration Console. In addition, this command can be started as a URL given the startTime and startTimeNanos parameters together or given the clear parameter alone. To run this command on the URL, you must log on to your store as an HCL Commerce site administrator.

Note: Ensure that you enable cache replication.

URL structure

http://host_name/path/
The fully qualified name of your Transaction server and the configuration path.


Parameter values

startTime|startTimeNanos
The startTime and startTimeNanos parameters are used to query the latest unprocessed rows in the CACHEIVL table. These parameters are used to construct a unique time stamp object with a milliseconds time value that can be used for the query. The time stamp value is the time that elapses since January 1, 1970, 00:00:00 GMT in milliseconds. When the DynaCacheInvalidation scheduled command first runs, startTime and startTimeNanos are set to 0 (zero).
startTime=milliseconds
This parameter is any positive integer that represents the part of the time stamp in milliseconds.
startTimeNanos=nanoseconds
This parameter is any positive integer that represents the fractional part of the time stamp in nanoseconds.
clear
The value of this parameter is set to true by default. The command starts the corresponding API to clear all the contents in the dynamic cache. Note that when clear is true, Near Real Time (NRT) updates will not be triggered in offline dataload jobs.
Using clear=true (or clearall in CACHEIVL) empties the base cache and all default Data Cache distributed maps. For custom distributed maps or servlet maps, the StringHolder or cache: method must be used.
isDistinct
By default, the value of this parameter is set to false. When set to true, this parameter limits the rows that return to a single row for each unique value found. Each row that return causes a cache invalidation request to be sent.
maxIndividualInvalidationsPerTable
Specify a positive number, the default is 100000. This parameter sets a limit on the number of individual invalidations to be processed in a table. When this limit is exceeded, an invalidation of all Commerce Data Cache entries with dependencies from that particular table occurs. This parameter setting causes the job to remove more data than necessary. maxIndividualInvalidationsPerTable helps DynaCacheInvalidation complete quickly when many rows are written to the CACHEIVL table.
maxSeconds
Specify a positive number, or zero to indicate no limit. The default is 90% of the DynaCacheInvalidationCMD scheduler job interval value. This value is stored in the SCCINTERVAL column of the SCHCONFIG table. This parameter specifies the maximum number of seconds for which a job instance must run. This value does not include the time that is spent waiting for an Update lock on the row of the SCHCONFIG table. This value also does not count the time that is spent waiting after the registries are refreshed. To adjust the wait time after the registries are refreshed, change the value for the waitSecondsAfterRefreshRegistry parameter. When the transaction reaches the maxSeconds limit, the job attempts to pause, leaving the remaining work incomplete. The incomplete work remains until the same job runs again. If the value in this column is zero, then maxSeconds=0 is used. Change the maxSeconds value that is based on your configured database transaction timeout and SCCINTERVAL value. The actual time that is used by the transaction can exceed the specified number.
maxSecondsPerTransaction
Specify a positive number. The default is 60. This parameter specifies the number of seconds a database transaction runs before the current database transaction attempts to commit and begin a new transaction. The actual time that a transaction runs can exceed this specified number. If isDistinct=true, the time can far exceed the specified number, since all found distinct rows must be processed in the same transaction.
enableRefreshRegistry
This parameter defaults to true. When this parameter is true, the DynaCacheInvalidation schedule job inspects each value in the DATAID column of the CACHEIVL database table. If the values in this column are in the form WCR+<registryName>, the scheduler job adds a broadcast scheduler job. This addition causes the specified registry to be refreshed on all currently running Transaction servers.
Tip: If the values in this column are in the form WCR+?, the scheduler job adds a broadcast scheduler job. This addition causes all registries to be refreshed on all currently running Transaction servers.
waitSecondsAfterRefreshRegistry
Specify a number that allows enough time for the broadcast job to complete on all servers. This parameter defaults to the minimum value of the cycleTime property of the com.ibm.commerce.scheduler.SchedulerComm component in the HCL Commerce instance wc-server.xml configuration file and the value of the SCCINTERVAL column in the SCHCONFIG database table for the DynaCacheInvalidation scheduler job. If that minimum value is null or less than or equal to zero, the value defaults to 600. When this waitSecondsAfterRefreshRegistry parameter specifies a value greater than or equal to zero, the DynaCacheInvalidation scheduler job pauses. It pauses for the specified number of seconds before the job issues DynaCache invalidations.
disableBaseCache
This parameter defaults to false. When this parameter is set to true, no invalidation ids are sent to the baseCache servlet cache instance.
maxInvalidationDataIds
This parameter defaults to Long.MAX_VALUE. When the specified number of CACHEIVL rows that contain invalidation ids are processed, any further such invalidation ids are not processed. Instead, the cache instance to which it would normally be sent is cleared. Use this parameter to limit the number of invalidation ids that can be issued. Clearing cache instances can have a significant performance impact.

However, invalidations will still occur for data cache related ids (TEMPLATE is NULL and DATAID starts with the WCT+, WCN+, WCD+, or WCR+ prefix). See the maxIndividualInvalidationsPerTable parameter to limit the issuing of data cache related invalidation ids.

cmdClearId
This parameter defaults to null. When the parameter is not set to null, this parameter specifies an invalidation id. This id is to be used instead of the value that is specified in the DATAID column of the CACHEIVL table for rows where the TEMPLATE column value starts with the cmd: prefix when the limit specified by the maxInvalidationDataIds parameter is exceeded.
localJVMOnly
This parameter defaults to false. Specify true to indicate that the DynaCacheInvalidation job is to assume that the invalidation ids it issues are effective for only the JVM in which it is running. When localJVMOnly is true, the following behavior changes apply. The startTime and startTimeNanos parameters are ignored, and they are not updated in the SCHCONFIG table. The time of last update is kept in memory only. The first time the job runs, the job does not use the startTime and startTimeNanos parameters. Instead, it uses the current time minus the value that is defined for the scheduler cycleTime setting in the wc-server.xml file. DATAID column values that cause registries to be refreshed do not cause a broadcast scheduler job to be added. Instead, registries for only the current JVM are refreshed, and the DynaCacheInvalidation command does not pause after refreshing registries.
disableDMap

This parameter defaults to false. When this parameter is set to true, no invalidation ids are sent for rows where the TEMPLATE column of the CACHEIVL table holds a value that starts with either the dmap: or the cache: prefix. When a value other than true or false is specified, the specified value is taken to be the JNDI name for a DistributedMap object cache. No invalidation ids are sent to this object cache for rows where the TEMPLATE column of the CACHEIVL table holds a value that starts with either the dmap: or the cache: prefix and indicates the specified JNDI name. To specify multiple JNDI names, specify the parameter name and its value multiple times, which are separated by an ampersand.

disableCmd
This parameter defaults to false. When this parameter is set to true, no invalidation ids are sent for rows where the TEMPLATE column of the CACHEIVL table holds a value that starts with the cmd: prefix. When a value other than true or false is specified, then the specified value is taken to be the fully qualified class name of a command that is not to be run for rows where the TEMPLATE column of the CACHEIVL table holds a value that starts with the cmd: prefix and ends with the specified class name. To specify multiple class names, specify the parameter name and its value multiple times, which are separated by an ampersand.
disableCache
This parameter defaults to false. When this parameter is set to true, no invalidation ids are sent for rows where the TEMPLATE column of the CACHEIVL table holds a value that starts with the cache: prefix. When a value other than true or false is specified, the specified value is taken to be the JNDI name for a servlet cache or a DistributedMap object cache. No invalidation ids are sent to this cache for rows where the TEMPLATE column of the CACHEIVL table holds a value that starts with the cache: pefix and includes the specified JNDI name. To specify multiple JNDI names, specify the parameter name and its value multiple times, which are separated by an ampersand.
maxInvalidationDataIdsPerSecond
This parameter defaults to Integer.MAX_VALUE (no limit). It specifies the maximum number of invalidation operations that are initiated per second. When the number of operations per second exceeds this limit, the DynaCacheInvalidation scheduler slows down processing until the rate falls below the specified maximum rate.
maxInvalidationDataIdsPerCachePerSecond
This parameter defaults to Integer.MAX_VALUE (no limit). It specifies the maximum number of invalidation operations that are initiated per second, for a particular cache. When the number of operations per second exceeds this limit, the DynaCacheInvalidation scheduler slows down processing. The scheduler slows down until the rate for that cache falls below the specified maximum rate.
maxInvalidationDataIdsPerCache
This parameter defaults to Long.MAX_VALUE (no limit). When the specified number of CACHEIVL rows that contain invalidation ids are processed for a particular cache instance, any further invalidation ids for that cache instance are not processed. Instead, the cache instance is cleared. Use this parameter to limit the number of invalidation ids that can be issued. Clearing cache instances can have a significant performance impact.
maxPercentInvalidationDataIdsPerCache
This parameter defaults to Integer.MAX_VALUE (no limit). When the number of CACHEIVL rows that are processed for a particular cache instance is divided by the number of cache entries in that cache instance, and exceeds the specified percentage threshold, any further invalidation ids are not processed. Instead, the cache instance is cleared. Use this parameter to limit the number of invalidation ids that can be issued. Clearing cache instances can have a significant performance impact. This parameter has no effect for CACHEIVL rows where the TEMPLATE column value starts with cmd:.
delayBaseCacheInvalidationMilliseconds

This parameter specifies the number of milliseconds to delay sending an invalidation ID to the baseCache servlet cache instance. Specify a number greater than zero to allow time for the object cache instance invalidation IDs to be processed before the baseCache servlet cache invalidation IDs are processed.

Note: Normally you specify either the startTime and startTimeNanos parameters together, or the clear parameter by itself. If you specify all three parameters, the command takes the clear parameter.

Example

The following example invalidates the cached objects in the CACHEIVL table for all rows, beginning from the first row:


   http://
host_name/path/DynaCacheInvalidation?startTime=0&startTimeNanos=0

The following example clears all the cached objects in the dynamic cache:


   http://
host_name/path/DynaCacheInvalidation?clear=true

The following example invalidates all cache entries that have any dependency on data from a particular table:


   http://
host_name/path/DynaCacheInvalidation?maxIndividualInvalidationsPerTable=100000

Behavior

  • The command reads rows from the CACHEIVL table in the HCL Commerce database. Only those rows that are not processed by the invalidation are fetched. Only those rows with a greater INSERTTIME than the last row processed in the last DynaCacheInvalidation job and a timestamp in CACHEIVL that is less than the current timestamp will be invalidated. The DynaCacheInvalidation job will overlook all other records.
  • If the WebSphere Application Server dynamic cache is disabled, the command takes no action.
  • If your HCL Commerce environment is clustered, the DynaCacheInvalidation scheduled job behavior does not change.
  • If the command runs on the URL with the clear=true parameter and value, or if the value of the TEMPLATE or DATAID columns for a processed row is "clearall, then the command clears all the cache content from the baseCache servlet cache and the data cache object caches.If the TEMPLATE column value for a processed row is NULL, then the DATAID column value is used to invalidate cache entries. If the DATAID column value does not start with one of the special value prefixes WCT+, WCN+, WCD+, and WCR+, then the value is sent as an invalidation id to the baseCache servlet cache using the com.ibm.websphere.cache.DistributedMap.invalidate method. Otherwise, the value is parsed to determine a table name and column values (or a registry name when the prefix is WCR+) and used to invalidate the appropriate data cache entries (or named registry).
  • If the TEMPLATE column value for a processed row is not NULL, and does not start with one of the special value prefixes dmap:, cmd:, and cache:, then the TEMPLATE column value is used to invalidate baseCache cache entries that are created by the specified template value, using the com.ibm.websphere.cache.Cache.invalidateByTemplate method.
Additional behavior information
  • The startTime|startTimeNanos name-value pair is converted to a real time and any row in the CACHEIVL table that has an INSERTTIME after the converted startTime/startTimeNanos is executed.
  • To run the DynaCacheInvalidation job immediately, complete one of the following tasks:
    • In the Administration Console, set the time for the DynaCacheInvalidation job to an earlier time than the current time.
    • Update the SCHACTIVE table.

Only those rows with a greater INSERTTIME than the last row processed in the last DynaCacheInvalidation job and a timestamp in CACHEIVL that is less than the current timestamp will be invalidated. The DynaCacheInvalidation scheduler job will overlook all other records. When the job finds a value in the TEMPLATE column that starts with the dmap: prefix for a new row, the job uses the rest of the value that follows the prefix as a JNDI name. This name specifies a DistributedMap object cache instance. If the specified object cache does not exist, no action is taken. If the specified object cache does exist, then the value of the DATAID column is sent to the specified object cache as an invalidation id string. If you define the DistributedMap in a cacheinstances.properties file, the first forward slash of the JDNI name should be omitted.

For example, if the distributed map is defined in the cacheinstances.properties file as cache.instance.0=/services/cache/MyCustomMapCache, then the string in the TEMPLATE column of the CACHEIVL table should be dmap:services/cache/MyCustomMapCache.

If the scheduler job locates a value in the TEMPLATE column that starts with cmd: prefix for a new row, the job uses the rest of the value that follows the prefix as a Java class name. If the specified Java class is not an instance of com.ibm.commerce.dynacache.commands.StringHolderCmdImpl, no action is taken. If the specified Java class is an instance of a subclass of com.ibm.commerce.dynacache.commands.StringHolderCmdImpl, then an instance of that class is created and its setString method is called which passes the value of the DATAID column, and the command instance is executed.

A custom servlet cache can cause the specified DATAID value to be sent as an invalidation to a servlet cache instance. This invalidation can be sent by specifying that command in the cachespec.xml file for the custom servlet cache instance. For example:
<cache-instance name="instance2"> 
<cache-entry>
  <class>command</class> 
  <name>com.ibm.commerce.dynacache.commands.StringHolderCmdImpl</name>
  <invalidation> 
    <component type="method" id="getString> 
    </component> 
  </invalidation> 
</cache-entry> 
<!-- *************************************************************************** --> 
<!-- * Place the cache-entry tags for the servlet cache instance here. * -->
<!-- *************************************************************************** --> 
</cache-instance>
Since a command cannot be defined for more than one servlet cache instance, HCL Commerce includes three subclasses of com.ibm.commerce.dynacache.commands.StringHolderCmdImpl. These subclasses can be used to cause invalidations in up to three more custom servlet cache instances:
  • com.ibm.commerce.dynacache.commands.StringHolder1
  • com.ibm.commerce.dynacache.commands.StringHolder2
  • com.ibm.commerce.dynacache.commands.StringHolder3
The DynaCacheInvalidation scheduler job looks in the CACHEIVL table for recently added rows. When the job finds a value in the TEMPLATE column that begins with the cache: prefix for a new row, the job uses the remaining value that follows the prefix as a colon delimited list of JNDI names. Each JNDI name specifies either a servlet cache instance or a DistributedMap object cache instance. If a specified cache does not exist, no action is taken for that cache. For each specified cache that does exist, the value of the DATAID column is sent to the specified object cache as an invalidation id string, unless it is the special clearall string, in which case the cache is cleared.
Note: The JNDI names that you specify should not be prefixed with a forward slash. For example, if a distributed map is defined in the cacheinstances.properties file as cache.instance.0=/services/cache/MyCustomMapCache, then the string in the TEMPLATE column of the CACHEIVL table should be cache:services/cache/MyCustomMapCache.

Exception conditions

DynaCacheInvalidation throws an ECException if there are problems when the invalidation executes the SQL, or if there is a system error.