Introduction

Cache Management allows to manage caches by using a common API for:

• Implementation and usage of caches (Actors: Developers)
• (Selective) clearing of caches (Actors: Developers and Administrators)
• Monitoring of caches (Actors: Administrators)
• Configuration of caches (Actors: Administrators)

The API is provided by the CacheEngine which supports the following processes:

• Implementation and registration of caches which are assigned to cache layers at development time
• (Selective) clearing of caches at runtime, when objects have changed and caches have to be refreshed
• Monitoring and configuration of caches at runtime

The Cache Management API was implemented by using the following paradigms:

• The order, number and types of caches are transparent to developers who have to implement logic to clear caches
• UDP multicast network traffic must be reduced to a minimum
• Caches must be monitorable and configurable at runtime via JMX clients

References

• Concept - ORM Layer
• Concept Search Services (since 6.7)
• Concept - Page Cache
• Cookbook - Cache Management
• Guide - Cache Engine Administration

Concept: Caches, CacheGroups, Cache Clear Order

Caches are located at different layers of the product. Within one layer different groups of caches can exist.
Caches must be assigned to cache groups. Note that not all caches are caches in a narrow sense, there are pseudo-caches which just behave like classical caches in some aspects; e.g., search indexes are based on data, and when this data changes, the search indexes must be updated.

ORMCacheGroup

The ORMCacheGroup is located at the platfrom layer and contains one cache instance which represents the ORMCache used to cache persistent objects in the JVM memory of an application server.
Please check Concept - ORM Layer for more details regarding the ORMCache.

ObjectCacheGroup

The ObjectCacheGroup is located at the business layer and contains an arbitrary number of cache instances which are global per JVM, used to cache Java objects in the JVM memory of an application server.

SearchIndexRebuildableCacheGroup

The SearchIndexRebuildableCacheGroup is located at the application layer and contains one pseudo-cache instance which is used to rebuild/update and reload search indexes. Search indexes are stored in the shared file system.
Please check CO Search Services (until 6.6.x) and Concept Search Services (since 6.7) for more details regarding the Search Framework.

SearchIndexReloadableCacheGroup

The SearchIndexReloadableCacheGroup is located at the application layer and contains one pseudo-cache instance which is used to reload search indexes without rebuild/update. Search indexes are stored in the shared file system.
Note that this group is relevant in the mass data replication scenario only. Search index data is assumed to be in a consistent and updated state on EDIT and it is just replicated to the LIVE system, followed by a search index reload action.

PageCacheGroup

The PageCacheGroup is located at the presentation layer and contains one pseudo-cache instance which is used to invalidate the webadapter page cache which is stored in the webadapter's page cache file system.
The CacheEngine supports keyword-based invalidation. Please check Concept - Page Cache for more details regarding the PageCache.

Cache Clear Order

One entity could be cached in different cache groups at the same time, e.g. a product is cached in the ORMCache, it is contained in a search index and its storefront page is contained in the page cache. The CacheEngine - i.e., a certain CacheClearProcessor - clears the caches in a consistent way by clearing the caches in the order of cache groups.
The following order is used: ORMCacheGroup, ObjectCacheGroup, SearchIndexRebuildableCacheGroup / SearchIndexReloadableCacheGroup, PageCacheGroup.

Concept: CacheClearKeys and CacheClearKeyProviders

There are two ways of clearing a cache:

• Full cache clear which removes all objects from a cache, or all objects belonging to a certain class, or all objects belonging to a certain domain
• Partial (selective) cache clear which removes only cached objects which have be changed or deleted.

A concept is necessary to be able to identify which objects must be removed from a cache. The CacheEngine uses so-called "CacheClearKeys" for that. A CacheClearKey identifies an object, a class of objects or the domain of objects to be removed from caches.

The following types of CacheClearKeys are available:

• CacheClearKey: Identifies one single object
• ClassCacheClearKey: Identifies all objects which belong to a certain class
• PageCacheClearKey: Identifies one single object by its page cache keywords and the sites which contain pages to display the object

For each kind of object the appropriate CacheClearKeys must be provided. This is done by CacheClearKeyProviders which are registered at the CacheEngine and used by CacheClearProcessors.

Concept: CacheClearProcessors

There are different times when caches have to and can be cleared. Cache clear can be done instantly when objects have been changed or it can be done later by batching the cache clear. Depending on the type of processor and performance aspects, not all CacheGroups are necessarily assigned to a processor. A processor collects the CacheClearKeys with the help of the CacheClearKeyProviders assigned to the CacheEngine. Processors may also differ in the way cache clear messaging is done in a clustered environment with more than one appserver.

InstantCacheClearProcessor

An InstantCacheClearProcessor clears caches of all CacheGroups assigned to it immediately.

BatchCacheClearProcessor

A BatchCacheClearProcessor uses a two-phase mechanism to clear caches: On each batchCacheClear request the CacheClearKeys are stored in the database for a context. This context is described by a virtual UUID used to identify the process the processor is used for, e.g. an import process. Once all CacheClearKeys are stored, cache clear can be requested and caches of all CacheGroups assigned to the processor are cleared immediately for the CacheClearKeys previously batched for the virtual UUID.

A second mechanism is supported by this type of processor: Cache clear can be batched for a desired cache clear date. A scheduled job named "ProcessBatchCacheClear" exists which runs at intervals and clears caches for all CacheClearKeys previously batched for a desired cache clear date < current date.

CacheClearProcessor Implementations and Usage Areas

ORMCacheSyncCacheClearProcessor

This processor clears the ORMCacheGroup and ObjectCacheGroup only. It does not use a dedicated messaging channel to inform other appservers about the cache clear. Instead, the messaging mechanism provided by the ORMEngine's SynchronizationManager is used. The SynchronizationManager does UDP multicast for the intershop.cacheSync channel - configurable in <eserver>/share/system/config/cluster/orm.properties-per default. Note that this channel is usually disabled after installation. It has to be enabled and configured properly when more than one appserver is used.

1. A transaction is committed for an ORMObject.
2. The SynchronizationManager of the ORMEngine requests a cache clear by using the ORMCacheSyncCacheClearProcessor.
3. The ORMCacheSyncCacheClearProcessor clears the ORMCache of the ORMCacheGroup for the ORMObject which has been modified.
4. The ORMCacheSyncCacheClearProcessor clears all ObjectCaches of the ObjectCacheGroup for the ORMObject which has been modified.
5. The SynchronizationManager sends a message - using the intershop.cacheSync channel - to all other appservers.
6. The SynchronizationManager receives the message and requests a cache clear by using the ORMCacheSyncCacheClearProcessor.
7. The ORMCacheSyncCacheClearProcessor on the receiving appserver clears the ORMCache of the ORMCacheGroup for the ORMObject which has been modified.
8. The ORMCacheSyncCacheClearProcessor on the receiving appserver clears all ObjectCaches of the ObjectCacheGroup for the ORMObject which has been modified.

ImportBatchCacheClearProcessor / SyncMessenger

This processor clears the SearchIndexRebuildableCacheGroup and PageCacheGroup only. Since the cache location of a SearchIndex is the file system, search indexes are always updated by the appserver which issued the cache clear request only. Afterwards, the search indexes are simply reloaded on other appservers by sending a search index reload message. For the PageCacheGroup no messaging is necessary at all, the page cache is invalidated using the keyword-based approach and it is up to the WebAdapterAgent to perform the concrete invalidation.

Messaging for search index reload is done by the SearchIndexRebuildableCache instance; it uses a dedicated messaging channel and a special SyncMessenger implementation to inform other appservers about the cache clear. The SyncMessenger provides a mechanism to send a message to other appservers and wait for message responses from those appservers. For sending another messenger - per default a UDP multicast messenger - is wrapped and used. The SyncMessenger waits for responses by checking a special table in the DB where every receiving appserver is supposed to commit a row when the message has been received and successfully handled. The SyncMessenger does not wait forever; therefore, a timeout has to be configured - it defaults to 10s. If an appserver did not respond within this timeout, the message and the complete cache clear process is considered as failed. The SyncMessenger has to be configured in <eserver>/share/system/config/cluster/cache.properties.
Note that the ORMCacheGroup and ObjectCacheGroup are still cleared during import processes because the ORMCacheSyncCacheClearProcessor is used during import automatically if an ORM-based import approach is used.

1. The ImportFramework - i.e., an ElementBulker - batches cache clear keys for each imported element through the ImportBatchCacheClearProcessor.
2. The ImportFramework - i.e., the final part of an import pipeline - issues a cache clear request to the ImportBatchCacheClearProcessor.
3. The ImportBatchCacheClearProcessor starts to clear the SearchIndexRebuildableCacheGroup.
4. The SearchIndexRebuildableCache updates each search index for the batched cache clear keys.
5. The SearchIndexRebuildableCache starts to reload search indexes on other appservers by handing over a sync message to the SyncMessenger.
6. The SyncMessenger sends the search index reload message - via the intershop.cache channel - to other appservers.
7. The SyncMessenger on the sending appserver waits and checks for responses from those appservers.
8. The SyncMessenger on the receiving appserver received the message and uses the SearchIndexRebuildableCache to reload the search indexes.
9. After reload was successful, the SyncMessenger writes a response into the DB.
10. The SyncMessenger on the sending appserver detects that appservers handled the message.
11. The ImportBatchCacheClearProcessor invalidates the PageCache by using the keyword-based approach for the cache clear keys.

Note that the ImportBatchCacheClearProcessor is currently used during product import and catalog import only.

StagingCacheClearProcessor / SyncMessenger

This processor clears the ORMCacheGroup, ObjectCacheGroup and SearchIndexReloadableCacheGroup after mass data replication on the live system only. It uses the same SyncMessenger as the ImportBatchCacheClearProcessor - please check the previous chapter for details. Note that after this processor finished, a complete page cache clear is done by the staging framework on the live system. This is not done via the Cache Management API but by the staging framework itself because the page cache can be rolled back to the previous state when a replication process is undone. This special feature is not yet supported by the Cache Management API.
This page cache clear is different from a keyword-based invalidation because it creates a fresh page cache directory for each site were data was replicated for.

1. The StagingFramework - i.e., a StagingProcessor or StagingDecorator - batches cache clear keys for each PO class or other grouped entity affected by the current staging process through the StagingBatchCacheClearProcessor.
2. The StagingFramework - i.e., the final part of the staging pipeline in the live system - issues a cache clear request to the StagingBatchCacheClearProcessor.
3. The StagingBatchCacheClearProcessor clears the ORMCache for the batched cache clear keys.
4. The StagingBatchCacheClearProcessor clears the ObjectCaches for the batched cache clear keys.
5. The StagingBatchCacheClearProcessor starts to clear ORMCaches and ObjectCaches on other appservers by handing over a sync message to the SyncMessenger.
6. The SyncMessenger sends the cache clear message - via the intershop.cache channel - to other appservers.
7. The SyncMessenger on the sending appserver waits and checks for responses from those appservers.
8. The SyncMessenger on the receiving appserver received the message and forwards the cache clear message to the StagingBatchCacheClearProcessor of this appserver.
9. The StagingBatchCacheClearProcessor clears the ORMCache for the batched cache clear keys.
10. The StagingBatchCacheClearProcessor clears the ObjectCaches for the batched cache clear keys.
11. After cache clear was successful the SyncMessenger writes a response into the DB.
12. The SyncMessenger on the sending appserver detects that appservers handled the cache clear message.
13. The StagingBatchCacheClearProcessor informs the SearchIndexReloadableCache.
14. The SearchIndexReloadableCache hands over a sync message to reload search indexes to the SyncMessenger.
15. The SyncMessenger sends the search index reload message - via the intershop.cache channel - to other appservers.
16. The SyncMessenger on the sending appserver waits and checks for responses from those appservers.
17. The SyncMessenger on the receiving appserver received the message and uses the SearchIndexRebuildableCache to reload the search indexes.
18. After reload was successful, the SyncMessenger writes a response into the DB.
19. The SyncMessenger on the sending appserver detects that appservers handled the message.

Generic InstantCacheClearProcessor / SyncMessenger

This processor clears all available cache groups (ORMCacheGroup, ObjectCacheGroup, SearchIndexRebuildableCacheGroup, PageCacheGroup) immediately. It uses the same SyncMessenger as the ImportBatchCacheClearProcessor - please check the previous chapters for details. This processor is not directly related to a certain framework, it can be used at various places. Please keep in mind that InstantCacheClearProcessors do not store cache clear keys in the DB, instead the keys are transferred as part of the cache clear message issued by the SyncMessenger. When the SyncMessenger uses a MulticastMessenger for sending messages, the size of a message might be limited. It is not recommended to use this processor for a lot of cache clear keys and it is not recommended to use this processor in a mass data scenario. The GenericBatchCacheClearProcessor is available if a lot of cache clear keys must be handled or if mass data is processed.

Generic BatchCacheClearProcessor / SyncMessenger

This processor clears all available cache groups (ORMCacheGroup, ObjectCacheGroup, SearchIndexRebuildableCacheGroup, PageCacheGroup) by batching the cache clear keys first. It uses the same SyncMessenger as the ImportBatchCacheClearProcessor - please check the previous chapters for details.