Event caching is extremely useful and easy to use. ColdBox will act like a cache proxy between your events and the clients requesting the events, much like squid, nginx or HA Proxy. All you need to do is add several metadata arguments to the action methods and the framework will cache the output of the event in the template cache provider in CacheBox. In other words, the event executes and produces output that the framework then caches. Subsequent calls to the same event with the same incoming RC variables will not do any processing, but just output the content back to the user.

For example, you have an event called blog.showEntry. This event executes, gets an entry from the database and sets a view to be rendered. The framework then renders the view and if event caching is turned on for this event, the framework will cache the HTML produced. So the next incoming show entry event will just spit out the cached HTML. The cache key is created by hashing the incoming request collection.

Enabling Event Caching

To enable event caching, you will need to set a setting in your ColdBox.cfc called coldbox.eventcaching to true.

 coldbox.eventCaching = true;

Setting Up Actions For Caching

The way to set up an event for caching is on the function declaration with the following annotations:

// In Script
function showEntry(event,rc,prc) cache="true" cacheTimeout="30" cacheLastAccessTimeout="15"{
    //get Entry
    prc.entry = getEntryService().getEntry(event.getValue('entryID',0));
​
    //set view
    event.setView('blog/showEntry');
}

Storage

All event and view caching are stored in a named cache called template which all ColdBox applications have by default. You can open or create a new CacheBox configuration object and decide where the storage is, timeouts, providers, etc. You have complete control of how event and view caching is stored.

Purging

We also have a great way to purge these events programmatically via our cache provider interface.

templateCache = cachebox.getCache( "template" );

Methods for event purging:

• clearEvent( string eventSnippet, string querystring="" ): Clears all the event permutations from the cache according to snippet and querystring. Be careful when using incomplete event name with query strings as partial event names are not guaranteed to match with query string permutations

• clearEventMulti( eventsnippets,string querystring="" ): Clears all the event permutations from the cache according to the list of snippets and querystrings. Be careful when using incomplete event name with query strings as partial event names are not guaranteed to match with query string permutations

• clearAllEvents( [boolean async=true] ) : Can clear ALL cached events in one shot and can be run asynchronously.

//Trigger to purge all Events
getCache( "template" ).clearAllEvents();
​
//Trigger to purge all events synchronously
getCache( "template" ).clearAllEvents(async=false);
​
//Purge all events from the blog handler
getCache( "template" ).clearEvent('blog');
​
//Purge all permutations of the blog.dspBlog event
getCache( "template" ).clearEvent('blog.dspBlog');
​
//Purge the blog.dspBlog event with entry of 12345
getCache( "template" ).clearEvent('blog.dspBlog','id=12345')

this.event_cache_suffix

You can now leverage the cache suffix property in handlers to be declared as a closure so it can be evaluated at runtime so it can add dynamic suffixes to cache keys. This can allow you to incorporate elements into the cache key at runtime instead of statically. This is a great way to incorporate the user's language locale or session identifier to make unique entries.

this.EVENT_CACHE_SUFFIX = function( eventHandlerBean ){
  return "a localized string, etc";
};

OnRequestCapture - Influence Cache Keys

We have provided an interception point in ColdBox that allows you to add variables into the request collection before a snapshot is made so you can influence the cache key of a cacheable event. What this means is that you can use it to mix in variables into the request collection that can make this event cache unique for a user, a specific language, country, etc. This is a great way to leverage event caching on multi-lingual or session based sites.

component{
​
    onRequestCapture(event,interceptData){
        var rc = event.getCollection();
​
        // Add user's locale to the request collection to influenze event caching
        rc._user_locale = getFWLocale();
    }
​
}

With the simple example above, the user's locale will be addded to all your event caching permutations and thus create entries for different languages.

Life-Cycle Caveats

When using event caching the framework will NOT execute ANY event at all. It will stream the content directly from the selected cache provider. This means that any interceptors or code that executes in the event is also NOT executed. The only interception points that will execute are:

• preProcess

• postProcess

So please make sure you take note of this when planning for event security.

Monitoring

​CacheBox has an intuitive and powerful monitor that can be used via the ColdBox Debugger Module. From the monitor you can purge, expire and view cache elements, etc.

box install cbdebugger