Disk cache enhancements
 Release notes
 
Abstract
The dynamic cache service enables you to persist objects to disk, which is specified by a file system location, so that the application server does not have to regenerate objects that are removed from the memory cache. Disk caching technology is designed to be an overflow or spill-over cache; however, you might use the disk cache as the primary cache and the memory cache as a buffer. As a result, the following issues might occur:

  • Increased latency of responses exists when cached items are retrieved from the disk.

  • Disk cache grows without a limit.

  • High CPU and I/O utilization occurs when a large disk cache is used.

  • The server freezes occasionally while it retrieves items from the disk cache.
 
 
Content
Include the disk cache enhancements as follows:
  1. Upgrade to the latest service pack:
    • For IBM® WebSphere® Application Server V5.0.2, update to the WebSphere Application Server V5.0.2.18 service pack
    • For WebSphere Application Server V5.1, update to the WebSphere Application Server V5.1.12 service pack
    • For WebSphere Application Server V6.02, update to the WebSphere Application Server V6.0.2.17 service pack
    • WebSphere Application Server V6.1 provides these enhancements
  2. Delete all of the old disk cache files. The disk enhancement supports the old format of disk cache files; however, if the old format is detected, the first two features in the bulleted list below are disabled. It is highly recommended that you use the new format by deleting all old disk cache files before restarting the server. The new format provides the following benefits:
    • Size of each entry in the disk entry header to support the "Limit disk cache size in GB" feature.
    • Disk cache garbage collector using the eviction algorithm feature. This is required for the new format.
    • Reduction in deletion time for entries on disk cache by reorganizing the disk layout to separate metadata (dependencies) that group objects together for invalidation from the actual serialized data. This will improve the overall disk cache performance.
  3. Start the server.
  4. Re-install the cache monitor application if it is already installed in the previous release.
  5. Configure the disk cache properties as follows:
    • Configure the custom properties on the server Java™ virtual machine (JVM) globally across all configured cache instances:
      1. In the administrative console, click Servers > Application servers > server_name > Java and process management > Process definition > Java virtual machine > Custom properties > New.
      2. Type the name of custom properties. Include the full property path.
      3. Type a valid value for the property in the Value field.
      4. Save the property and restart WebSphere Application Server.
    • For WebSphere Application Server V6.0.2, configure the custom properties on the single object cache instance or the servlet cache instance as follows:
      1. In the administrative console, click one of the following paths:
        • Servlet instance: click Resources > Cache instances > Servlet cache instances > servlet_instance_name > Custom properties > New
        • Object instance: click Resources > Cache instances > Object cache instances > object_instance_name > Custom properties > New
      2. Type the name of custom properties. Do not use full property path. For example, com.ibm.ws.cache.CacheConfig.
      3. Type a valid value for the property in the Value field.
      4. Save the property and restart WebSphere Application Server.
    • For WebSphere Application Server V6.1, the administrative console displays the custom properties option when selecting "Enable disk offload". You can also configure the default base cache, object cache instance, or servlet cache instance as follows:
      1. Default base cache: click Servers > Application servers > server_name > Container services > Dynamic cache service.
      2. Servlet instance: click Resources > Cache instances > Servlet cache instances > New
      3. Object instance: click Resources > Cache instances > Object cache instances > New

The following information contains the names of the custom properties for all of the disk cache enhancements with a brief description of their possible values and their meaning:

Disk cache performance level
com.ibm.ws.cache.CacheConfig.diskCachePerformanceLevel
This property indicates the performance level to tune the performance of the disk cache:
Valid values: 0, 1, 2, or 3
  • 0: Low performance and low memory usage
    • A limited amount of metadata is kept in memory.
      set htodCleanupFrequency in minutes (1 to 1440); a value of 0 indicates that cleanup runs only at midnight.
  • 1: Balanced performance and balanced memory usage
    • Some metadata is kept in memory. Use the default.
    • Settings to provide an optimal balance of performance and memory usage for most users.
      set htodCleanupFrequency in minutes (1 to 1440); a value 0 indicates that cleanup runs only at midnight.
  • 2: Custom performance and custom memory usage
    • Explicitly configures the memory that is consumed by the disk cache
      set htodDelayOflloadEntriesLimit (<=100)
      set htodDelayOffloadDepIdBuckets (>= 100)
      set htodDelayOffloadTemplateBuckets (>= 10)
      set htodCleanupFrequency in minutes (1 to 1440); a value of 0 indicates that cleanup runs only at midnight.
  • 3: High performance and high memory usage
    • All of the metadata, including dependency IDs and templates, are kept in memory.
    • No need to perform a disk scan for expiration, for example, no cleanup frequency

com.ibm.ws.cache.CacheConfig.htodCleanupFrequency
Valid value: A positive value in minutes.
The default value is zero (0), which means that cleanup is scheduled to run at midnight. This property specifies the frequency at which the disk cache cleanup daemon removes expired entries from the disk cache.

com.ibm.ws.cache.CacheConfig.htodDelayOffloadEntriesLimit
Valid value: A positive value.
The default value is 1000. This property provides a way to limit the buffering of dependency and template information. This limit occurs by specifying an upper bound on the number of cache entries any specific dependency can contain for buffering in memory. If there are more entries per dependency than this limit, the dependency and template information is written to the disk.

com.ibm.ws.cache.CacheConfig.htodDelayOffloadDepIdBuckets
Valid value: A positive value.
The default value is 1000. This property provides a way to limit the buffering of dependency ID information. This limit occurs by specifying an upper bound on the number of dependencies that are buffered in memory. If the count of dependencies exceeds this limit, the excess is written to disk.

com.ibm.ws.cache.CacheConfig.htodDelayOffloadTemplateBuckets
Valid value: A positive value.
The default value is 100. This property provides a way to limit template information buffering by specifying an upper bound on the number of templates that are buffered in memory. If the count of templates exceeds this limit, the excess is written to disk.


Disk cache size control
com.ibm.ws.cache.CacheConfig.diskCacheSize
Valid values: An integer.
A value of zero (0) means that a limit does not exist. The property specifies the maximum disk cache size in terms of number of entries.

com.ibm.ws.cache.CacheConfig.diskCacheSizeInGB
Valid values: An integer.
A value of zero (0) means that a limit does not exist. The property specifies the maximum disk cache size in terms of the amount of space that is occupied in gigabytes (GB).
Note: The limiting disk size in GB feature is required to use the new disk cache format. If you use the old disk cache format, a DYNA0066W warning message displays and this feature is disabled. To use the new format, delete all of the disk cache files.

com.ibm.ws.cache.CacheConfig.diskCacheEntrySizeInMB
Valid values: An integer.
A value of zero (0) means that a limit does not exist. This property specifies the maximum size of an individual disk cache entry in megabytes.

Disk cache garbage collection
com.ibm.ws.cache.CacheConfig.diskCacheHighThreshold
Valid values: 0 to 100
The default value is 80 and the units are in percent.
This property starts removing objects out of disk cache when the high threshold is reached

com.ibm.ws.cache.CacheConfig.diskCacheLowThreshold
Valid values: 0 to 100.
The default value is 70 and the units are in percent.
This property sets a lower limit on the number of entries that are removed from the disk cache.
Calculate the number and size of the removed entries as follows:
Number of removed entries = diskCacheSize * (diskCacheHighThreshold - diskCacheLowThreshold)
Size of the removed entries = diskCacheSizeInGB * (diskCacheHighThreshold - diskCacheLowThreshold)

com.ibm.ws.cache.CacheConfig.diskCacheEvictionPolicy
Valid values: 0, 1, and 2
The disk cache garbage collector removes objects from the disk cache based upon a specified removal policy. The policy is defined by this property.

The garbage collector keeps a certain amount of space available on the disk available. The configuration attribute limits the amount of disk space that is used for caching objects. Enable this policy by enabling the Limit disk cache size in GB, limit the disk cache size in the entries features, or both. The disk cache garbage collector removal algorithm follows:
  • None (0): The removal algorithm is disabled.
  • Random (1): The expired objects are removed first. If the disk size still has not reached the low threshold limit, objects are picked from the disk cache in random order and removed until the disk size reaches a low threshold limit.
  • Size (2): The expired objects are removed first. If the disk size still has not reached the low threshold limit, then largest-sized objects are removed until the disk size reaches a low threshold limit.

The disk cache size limit and the high threshold percentage determines when to trigger the removal process and when the disk cache is considered nearly full. The removal process is computed as a function of the user-specified limit. If the specified limit is 10 GB (3 GB is the minimum value), the cache subsystem initially creates three files that can grow to 1 GB in size for cache data, dependency ID information, and template information. Each time more space is needed to contain cache data, dependency ID information, or template information, a new file is created. Each of these files grow in 1 GB increments until the total number of files that are created is equal to the disk size in gigabytes. In this case, the value is 10 GB. Although the initial size of the new file might be smaller than 1 GB, dynamic cache service always rounds the number up to the next GB.

The removal process is triggered when the cache data size reaches the high threshold and continues until the cache data size reaches the low threshold. The calculation of the cache data size is dynamic.

Note: The disk cache garbage collector feature is required to use the new disk cache format. If the old format for the disk cache is used, a DYNA0067W warning message displays and this feature is disabled. To use the new format, delete all of the disk cache files.


PMI counters and MBean statistics for disk cache monitoring
This table describes the Performance Monitoring Infrastructure (PMI) counters for the disk cache. To access the PMI counters, look at the sample PMI clients that are provided in the product documentation. For more information, see "Dynamic cache counters" in the information center documentation.

PMI counters Description
DependencyIDBasedInvalidationFromDisk (cumulative count) The number of dependency ID-based invalidations that have been performed since the server started.
DependencyIDsBufferForDisk The number of dependency IDs that are buffered in memory for the disk.
DependencyIDsOffloadedToDisk (cumulative count) The number of dependency IDs that have been offloaded to disk since the server started.
DependencyIDsOnDisk The number of dependency IDs that are currently on the disk.
ExplicitInvalidationsFromDisk (cumulative count) The number of explicit invalidations that result in an entry being removed from the disk.
GarbageCollectorInvalidationsFromDisk (cumulative count) The number of garbage collector invalidations that result in the removal of non-expired entries from the disk cache due to a high threshold being reached since the server started.
HitsOnDisk (cumulative count) The number of requests for cached objects that are served from the disk.
ObjectsOnDisk The number of cache entries that are currently on the disk.
OverflowInvalidationsFromDisk (cumulative count) The number of invalidations that result in the removal of entries from the disk because the disk cache size limit or disk cache size in GB limit is exceeded since the server started.
PendingRemovalFromDisk The number of pending entries to remove from the disk.
TemplateBasedInvalidationFromDisk (cumulative count) The number of template-based invalidations that have been performed since the server started.
TemplatesBufferedForDisk The number of templates that are buffered in memory for the disk.
TemplatesOffloadedToDisk (cumulative count) The number of dependency IDs that are offloaded to disk since the server started.
TemplatesOnDisk The number of templates that are on the disk.
TimeoutInvalidationFromDisk (cumulative count) The number of expired entries from the disk.

Dynamic cache MBean statistics
This table describes the statistics that are used for adequate performance monitoring and tuning capabilities of the dynamic cache service.

Note: The values for the Cumulative and Resettable are as follows:
  • YES (#) - the counter is cumulative. It continually increments and does not reset to zero by clearing the cache. This counter can only be reset to zero by clicking the Reset Statistics button in the Cache Monitor. An example is CacheHits counter.
  • NO ($) - the counter is not cumulative, but can be increased or decreased, depending on the state of the cache or disk cache. Reset this counter to zero by clearing the cache. An example is ObjectsOnDisk counter (# of entries on disk).
  • NO (%) - the counter is not cumulative, but can be increased or decreased, depending on the state of the cache or disk cache. Reset this counter to any value other than zero by clearing the cache. An example is DiskCacheSizeInMB.

MBean counters Can reset counter characteristics Description
CacheHits YES (#) The number of cache hits.
CacheLruRemoves YES (#) The number of memory-based, least recently used (LRU) removals.
CacheMisses YES (#) The number of cache misses.
CacheRemoves YES (#) The number of cache removals.
DependencyIDBasedInvalidationFromDisk YES (#) The number of dependency ID-based invalidations that have been performed.
DependencyIDsBufferForDisk NO ($) The number of dependency IDs that are currently buffered in memory for the disk.
DependencyIDsOffloadedToDisk YES (#) The number of dependency IDs that are offloaded to the disk.
DependencyIDsOnDisk NO ($) The number of dependency IDs that are currently on the disk.
DiskCacheSizeInMB NO (%) The total size of data objects in megabytes (MB).
ExplicitInvalidationsFromDisk YES (#) The number of explicit invalidations that result in an entry being removed from the disk.
ExplicitInvalidationsFromMemory YES (#) The number of explicit invalidations that result in an entry being removed from memory.
ExplicitInvalidationsLocal YES (#) The number of explicit invalidations that are generated locally.
ExplicitInvalidationsRemote YES (#) The number of explicit invalidations that are generated from a cooperating JVM in the cluster.
GarbageCollectorInvalidationsFromDisk YES (#) The number of garbage collector invalidations that result in the removal of non-expired entries from disk cache because the high threshold has been reached.
MemoryCacheEntries YES (#) The number of cache entries in memory.
ObjectsDeleteFromDisk YES (#) The number of cached objects that are deleted from the disk.
ObjectsDeleteFromDisk4K YES (#) The number of cached objects that are deleted from the disk and are smaller than 4K.
ObjectsDeleteFromDisk40K YES (#) The number of cached objects that are deleted from the disk and are between 4K and 40K.
ObjectsDeleteFromDisk400K YES (#) The number of cached objects that are deleted from the disk and are between 40K and 400K.
ObjectsDeleteFromDisk4000K YES (#) The number of cached objects that are deleted from the disk and are between 400K and 4000K.
ObjectsDeleteFromDiskSize YES (#) The size of cached objects that are deleted from the disk .
ObjectsOnDisk NO ($) The number of cache entries on the disk.
ObjectsReadFromDisk YES (#) The number of cached objects that are read from the disk.
ObjectsReadFromDisk4K YES (#) The number of cached objects that are read from the disk and are smaller than 4K.
ObjectsReadFromDisk40K YES (#) The number of cached objects that are read from the disk and are between 4K and 40K.
ObjectsReadFromDisk400K YES (#) The number of cached objects that are read from the disk and are between 40K and 400K.
ObjectsReadFromDisk4000K YES (#) The number of cached objects that are read from the disk and are between 400K and 4000K.
ObjectsReadFromDiskSize YES (#) The size of cached objects have been read from the disk .
ObjectsWriteToDisk YES (#) The number of cached objects that are written to the disk.
ObjectsWriteToDisk4K YES (#) The number of cached objects that are written to the disk and are smaller than 4K.
ObjectsWriteToDisk40K YES (#) The number of cached objects that are written to the disk and are between 4K and 40K.
ObjectsWriteToDisk400K YES (#) The number of cached objects are written to the disk and are between 40K and 400K.
ObjectsWriteToDisk4000K YES (#) The number of cached objects that are written to the disk and are between 400K and 4000K.
ObjectsWriteToDiskSize YES (#) The size of cached objects that are written to the disk .
OverflowInvalidationsFromDisk YES (#) The number of invalidations that result in the removal of entries from the disk because the disk cache size limit or disk cache size in GB limit is exceeded.
PendingRemovalFromDisk NO ($) The number of pending entries to be removed from disk.
PushPullTableSize NO ($) The number of cache IDs that are buffered in the PushPullTable.
RemoteInvalidationNotifications YES (#) The number of remote invalidation notifications from other servers.
RemoteObjectFetchSize YES (#) The size of requests for cached objects that are served from other JVMs in the cluster. (PushPull mode)
RemoteObjectHits YES (#) The number of requests for cached objects that are served from other JVMs in the cluster. (PushPull mode)
RemoteObjectMisses YES (#) The number of requests for cached objects that are not located on other JVMs in the cluster. (PushPull mode)
RemoteObjectUpdateSize YES (#) The size of cached objects that are received from other JVMs in the cluster. (Push mode)
RemoteObjectUpdate YES (#) The number of cached objects that are received from other JVMs in the cluster. (Push mode)
RemoteUpdateNotifications YES (#) The number of notifications that identify an object has been updated at another JVM in the cluster. (PushPull mode)
TemplateBasedInvalidationFromDisk YES (#) The number of template-based invalidations that are performed.
TemplatesBufferForDisk NO ($) The number of templates that are buffered in memory for the disk.
TemplatesOffloadedToDisk YES (#) The number of templates that are offloaded to the disk.
TemplatesOnDisk NO ($) The number of templates on the disk.
TimeoutInvalidationsFromDisk YES (#) The number of timeout invalidations that result in an entry being removed from the disk.
TimeoutInvalidationsFromMemory YES (#) The number of timeout invalidations that result in an entry being removed from memory.


MBean cache statistics access
You can access different cache statistics with the MBean interface using JACL. Start the wsadmin scripting client from the install_root/bin directory. You can complete the following actions that are related to the MBean cache statistics:
  • To obtain a list of dynamic cache Mbean identifiers, type the following command:
    $AdminControl queryNames type=DynaCache,* 
  • To set your dynamic cache MBean, type the following command:
    set mbean dynamic_cache_mbean 
  • To retrieve the names of the available cache statistics, type the following command:
    $Admincontrol invoke $mbean getCacheStatisticsNames
  • To retrieve the names of the available cache instances, which is available for WebSphere® Application Server Versions 5.1.x and 6.0.2.x only, type the following command:
    $AdminControl invoke $mbean getCacheInstanceNames 
  • To retrieve all of the available cache statistics for the base cache instance, type the following command:
    $AdminControl invoke $mbean getAllCacheStatistics
  • To retrieve all of the available cache statistics for the named cache instance, which is available for WebSphere® Application Server Versions 5.1.x and 6.0.2.x only, type the following command:
    $AdminControl invoke $mbean getAllCacheStatistics "services/cache/servletInstance_4" 
  • To retrieve cache statistics that are specified by the names array for the base cache instance, type the following command:
    $AdminControl invoke $mbean getCacheStatistics {"ObjectsReadFromDisk4000K RemoteObjectMisses"}
  • To retrieve cache statistics that are specified by the names array for the named cache instance, which is available for WebSphere® Application Server Versions 5.1.x and 6.0.2.x only, type the following command:
    $AdminControl invoke $mbean getCacheStatistics {services/cache/servletInstance_4 "CacheHits ObjectsOnDisk"} 


Cache policy enhancements
The “do-not-cache” property, which defines a fragment that is neither cached nor consumed, was added to the cache specification (cachespec.dtd). This property is shown in example 1. Even though DNCParent.jsp file consumes subfragments and includes the DNCChild.jsp file, the DNCChild.jsp file is not cached nor consumed.

Example1: The cachespec.xml file
<cache-entry> 
<class>servlet</class>
<name>/DNCParent.jsp</name>
<property name="consume-subfragments">true</property>
<cache-id>
<timeout>0</timeout>
</cache-id>
</cache-entry> 
  
<cache-entry> 
<class>servlet</class>
<name>/DNCChild.jsp</name>
<property name="do-not-cache">true</property>
<cache-id>
<timeout>0</timeout>
</cache-id>
</cache-entry> 


You can extend the Do-not-cache property to use with an edge component, such as IBM HTTP Server, as shown in example 2. Note the presence of the "edge-cacheable" property. This property must be present to define a fragment that cannot be cached on an edge component.

Example 2: The cachespec.xml file (Edge component)
<cache-entry> 
<class>servlet</class>
<name>/DoNotCache.jsp</name>
<property name="do-not-cache">true</property>
<property name="edge-cacheable">true</property>
<cache-id>
<timeout>0</timeout>
</cache-id>
</cache-entry> 

The “skip-cache” attribute was added to the cache specification (cachespec.dtd).The attribute specifies that the response cannot be retrieved nor stored in the specific cache instance.

Example 1: The cachespec.xml file (Base cache)
<cache> 
<skip-cache-attribute>previewRequest</skip-cache-attribute> 
... 
</cache> 

Example 2: The cachespec.xml file (cacheinstance1)
<cache-instance name="cacheinstance1"> 
<skip-cache-attribute>previewRequest</skip-cache-attribute> 
... 
</cache-instance> 

To invoke the skip-cache functionality, set the request attribute, which is noted in example 3. The SkipCache.jsp file is not retrieved from the cache regardless of its cache policy.

Example 3: Invoking skip-cache from a filter
public void doFilter (ServletRequest request, ServletResponse
response, FilterChain chain){
try {  
String parm = request.getParameter("previewRequest");
       
if (parm == null)
request.setAttribute("previewRequest",null);
else if (parm.equals("true"))
request.setAttribute("previewRequest","true");
else if (parm.equals("false"))
request.setAttribute("previewRequest","false");
chain.doFilter(request, response);
} catch (Throwable t) {}}
 
Related information
Information Centers for Version 6.0.x
Information Centers for Version 5.1.x
Information Centers for Version 5.0.x
 
 
Cross Reference information
Segment Product Component Platform Version Edition
Application Servers WebSphere Application Server for z/OS Dynamic Cache z/OS 6.0.2, 5.1, 5.0
Business Integration WebSphere Business Integration Server Foundation General AIX, HP-UX, Linux, Solaris, Windows 5.1, 5.0
Business Integration WebSphere Business Integration Server Foundation for z/OS Not Applicable z/OS 5.0, 5.1
Application Servers Runtimes for Java Technology Java SDK
 
 


Document Information


Product categories: Software > Application Servers > Distributed Application & Web Servers > WebSphere Application Server > Dynamic Cache
Operating system(s): i5/OS
Software version: 6.0.2
Software edition:
Reference #: 7007969
IBM Group: Software Group
Modified date: Jul 28, 2006