DynaCacheInvalidation URL

The DynaCacheInvalidation command invalidates entries in the dynamic cache based on the dependency ID, cache ID, or template for a cached page that are recorded in the CACHEIVL table. The default cache invalidation interval is 10 minutes. You can change this default in the WebSphere 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 a WebSphere Commerce site administrator.

URL structure

http://host_name/path/

The fully qualified name of your WebSphere Commerce 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 WebSphere Commerce 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 WebSphere 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.

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: prefix 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.

Example

The following example invalidates the cached pages 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 pages 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 WebSphere Commerce database. Only those rows that are not processed by the invalidation are fetched. The rows are selected by filtering (on their time stamp field values in the CACHEIVL table) against the time stamp of the previous invocation of the command.
• If the WebSphere Application Server dynamic cache is disabled, the command takes no action.
• If your WebSphere 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.

The DynaCacheInvalidation scheduler job looks in the CACHEIVL table for recently added rows. 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.

<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>

Exception conditions

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