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.
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).
- 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 istrue
, Near Real Time (NRT) updates will not be triggered in offline dataload jobs. - 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 andSCCINTERVAL
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 formWCR+<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 andDATAID
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 theTEMPLATE
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 theTEMPLATE
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 theTEMPLATE
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 theTEMPLATE
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.
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 theTEMPLATE
column value for a processed row is NULL, then theDATAID
column value is used to invalidate cache entries. If theDATAID
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 theTEMPLATE
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
startTime|startTimeNanos
name-value pair is converted to a real time and any row in the CACHEIVL table that has anINSERTTIME
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.
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>
- com.ibm.commerce.dynacache.commands.StringHolder1
- com.ibm.commerce.dynacache.commands.StringHolder2
- com.ibm.commerce.dynacache.commands.StringHolder3
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.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.