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 page that are recorded in the CACHEIVL table. The default cache invalidation interval is 10 minutes. We 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, we must log on to the store as a WebSphere 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=true

The value of this parameter is always set to true. The command starts the corresponding API to clear all the contents in the dynamic cache. Any other values are ignored.

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

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

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. See: ../../admin/refs/rdctrblshtdynacachesetting.htm#rdctrblshtdynacachesetting.

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. 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, WebSphere 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.

Related concepts
Cache invalidation