CacheBox also sports a very nice event model that can announce several cache life cycle events and factory life cycle events. You can listen to these events and interact with caches at runtime very easily, whether you are in standalone mode or within a ColdBox application.
Of course, if you are within a ColdBox application, you get the benefit of all the potential of ColdBox Interceptors and if you are in standalone mode, well, you just get the listener and that's it.
Each event execution also comes with a structure of name-value pairs called interceptData that can contain objects, variables and all kinds of data that can be useful for listeners to use. This data is sent by the event caller and each event caller decides what this data sent is.
We have already seen in our previous section all the events that are announced by CacheBox and its providers, but how do we listen?
There are two ways to build CacheBox listeners because there are two modes of operations, but the core is the same. Listeners are simple CFCs that must create methods that match the name of the event they want to listen in. If you are running CacheBox within a ColdBox application, listeners are Interceptors and you declare them and register them exactly the same way that you do with normal interceptors.
Also, these methods can take up to three parameters depending on your mode of operation (standalone or ColdBox). The one main difference between pure CacheBox listeners and ColdBox interceptors are that the configure method for the standalone CacheBox is different. Please see samples in this section.
So let's say that we want to listen on the beforeCacheFactoryShutdown and on the afterCacheElementRemoved event in our listener.
Coldbox Mode Listener
Standalone Mode Listener
Please note the configure() method in the standalone listener. This is necessary when you are using CacheBox listeners outside of a ColdBox application. The configure() method receives two parameters:
cacheBox : An instance reference to the CacheBox factory where this listener will be registered with.
properties : A structure of properties that passes through from the configuration file.
As you can see from the examples above, each Listener component can listen to multiple events. Now you might be asking yourself, in what order are these listeners executed in? Well, they are executed in the order they are declared in either the ColdBox configuration file as interceptors or the CacheBox configuration file as listeners.
Caution Order is EXTREMELY important for interceptors/listeners. So please make sure you order them in the declaration file in the order you want them to fire.
CacheBox's aggregation functionality offers a wide gamut of life cycle events that are announced at certain points in execution time. Below are the current events announced by the CacheBox CacheFactory. Remember, this is the CacheFactory and not a CacheBox Cache Provider.
Each cache provider has the potential of announcing life cycle events as it implements it. If you are a cache provider author, then you can use the aggregated EventManager to register, process and announce events a-la-carte. So let's investigate each provider's life cycle events:
Event
Data
Description
afterCacheRegistration
cache: the registered reference
beforeCacheRemoval
cache: the cahce reference to remove
Called before a removeCache() operation is called on CacheBox
afterCacheRemoval
cache: the cache name
Called after the cache has been removed from CacheBox. You receive only the name of the cache removed.
beforeCacheReplacement
oldCache: the cache reference to replace newCache: the new cache reference to replace with
Called right before a cache is replaced with another cache in CacheBox.
afterCacheFactoryConfiguration
cacheFactory: A reference to the CacheBox factory created
Called after a CacheBox instance has been created, configured and started up. This is a great interception point for creating cache loaders or on startup scripts.
beforeCacheFactoryShutdown
cacheFactory: A reference to the CacheBox factory created
Called right before the CacheBox instance is shutdown gracefully
afterCacheFactoryShutdown
cacheFactory: A reference to the CacheBox factory created
Called right after the CacheBox instance has been shutdown gracefully
beforeCacheShutdown
cache: A reference to the cache shutdown
Called right before a specific cache provider is shutdown by CacheBox Factory
afterCacheShutdown
cache: A reference to the cache that was shutdown
Called right after a specific cache provider has been shut down by CacheBox Factory and before its removed
Event | Data | Description |
afterCacheElementUpdated | cache: the cache provider cacheNewObject: the new object to cache cacheOldObject: the object replaced | Called via a |
afterCacheElementInsert | cache: the cache provider cacheObject: the new object to cache cacheObjectKey: the key used to store the object cacheObjectTimeout: the timeout used cacheObjectLastAccessTimeout:the last access timeout used | Called after a new cache element has been inserted into the cache |
afterCacheElementRemoved | cache: the cache provdier cacheObjectKey: the key of the removed object | Called after a cache element has been removed from the cache |
afterCacheClearAll | cache: the cache provider | Called after a |
afterCacheElementExpired | cache: the cache provider cacheObjectKey: the key of the expired object | Called after a cache element has been expired from the cache |
Event | Data | Description |
afterCacheElementInsert | cache: the cache provider cacheObject: the new object to cache cacheObjectKey: the key used to store the object cacheObjectTimeout: the timeout used cacheObjectLastAccessTimeout: the last access timeout used | Called after a new cache element has been inserted into the cache |
afterCacheElementRemoved | cache: the cache provider cacheObjectKey: the key of the removed object | Called after a cache element has been removed from the cache |
afterCacheClearAll | cache: the cache provider | Called after a |