CacheBox DSL

As we have seen, the CacheBox DSL can be used in different contexts:

  • Portable CFC with a configure() method in a cachebox variable

  • ColdBox config inside the configure() method in a cachebox variable

  • A struct literal is sent into the constructor of CacheBox

No matter how you dice it, it's the same CacheBox Config DSL:

* A CacheBox configuration data object

    function configure(){
        cacheBox = {
            logBoxConfig : "",
            scopeRegistration : {},
            defaultCache : {},
            caches : {}
            listeners : {}


Base Config

The cacheBox structure can be configured with the following keys:






The instantiation or location of a LogBox configuration file. This is only for standalone operations.



A structure that enables scope registration of the CacheBox factory in either server, cluster, application, or session scope.



The configuration of the default cache which will have an implicit name of default which is a reserved cache name. It also has a default provider of CacheBox which cannot be changed.



A structure where you can create more named caches for usage in your CacheBox factory.



An array that will hold all the listeners you want to configure at startup time for your CacheBox instance. If you are running CacheBox within a ColdBox application, this item is not necessary as you can register them via the main ColdBox interceptors section.


// LogBox config path
logBoxConfig : "myapp.config.MyLogBoxConfig",

The LogBoxConfig element is used only in a standalone mode of operation and tells CacheBox what configuration file to load into LogBox.

LogBox is an enterprise ColdFusion (CFML) logging library

By default, CacheBox will instantiate LogBox with its default configuration file located at: cachebox.system.cache.config.LogBox.cfc which logs to the console.

Scope Registration

scopeRegistration = {
    enabled = true,
    scope   = "application",
    key     = "cacheBox"

This configuration allows CacheBox to be placed automatically upon construction in your specified scope. By default, CacheBox registers itself in application scope with a key of cachebox










Enable scope registration





The ColdFusion scope to persist on





The name of the key in the ColdFusion scope to persist on


// The defaultCache has an implicit name of "default" which is a reserved cache name
// It also has a default provider of cachebox which cannot be changed.
// All timeouts are in minutes
// Please note that each object store could have more configuration properties
defaultCache : {
	objectDefaultTimeout           : 120,
	objectDefaultLastAccessTimeout : 30,
	useLastAccessTimeouts          : true,
	reapFrequency                  : 2,
	freeMemoryPercentageThreshold  : 0,
	evictionPolicy                 : "LRU",
	evictCount                     : 1,
	maxObjects                     : 300,
	objectStore                    : "ConcurrentSoftReferenceStore",
	// This switches the internal provider from normal cacheBox to coldbox enabled cachebox
	coldboxEnabled                 : false

Every CacheBox instance has a default cache that can be configured as you like. Above you can see the default configuration for the cache.

This is a reserved cache name, and it is MANDATORY to declare, and its name or provider type cannot be changed.

However, if you are using CacheBox within a ColdBox application, the provider will switch itself to cachebox.system.cache.providers.CacheBoxColdBoxProvider by using the coldboxEnabled key.

objectDefaultTimeout : numeric

The default lifespan of an object is in minutes. This is how long an object lives within the cache. If this value is 0 then all objects will be eternal, meaning they will live forever.

objectDefaultLastAccessTimeout : numeric

The default last access or idle timeout in minutes. If an object has not been accessed within this time limit since the last access, then it will be marked for purging.

useLastAccessTimeouts : boolean

By default, the last access timeout is enabled. You can disable this purging feature if you desire.

resetTimeoutOnAccess : boolean

If true, then when cached objects are retrieved their timeout will be reset to its original value thus elongating the survival strategy of the items. Much how session storages work on JEE. The default is false, meaning the timeout will NOT be reset on each access.

reapFrequency : numeric

Every CacheBox provider has its own executor service with a reaping task executing under this frequency. This is how often the cache is inspected to purge old/invalid keys.

freeMemoryPercentageThreshold : numeric

The numerical percentage threshold of free JVM memory to be available before caching. If the JVM free memory falls below this setting, the cache will run the eviction policies to cache new objects. If you set this value to be 0 , there will be no free memory checks.

evictionPolicy : string

The eviction policy algorithm to use. The available algorithms are:

  • LFU

  • LRU - Default

  • LIFO

  • FIFO

  • Custom

evictCount : numeric

The number of objects to evict once an execution of the policy is requested. You can increase this to make your evictions more aggressive. By default, one object is purged from the cache. However, you can increase it to purge more than one as needed.

maxObjects : numeric

The maximum number of objects the cache can have, give or take, expired objects. Once a limit is reached, the cache will start purging objects using the eviction policy and counts. The default is 300.

coldboxEnabled : boolean

A flag that switches on/off the usage of either a plain vanilla CacheBox provider or a ColdBox enhanced provider. This must be true when used within a ColdBox application and applies to the default cache ONLY. For standalone mode, ignore this or always set it to false.

objectStore : string

Each CacheBox provider can have a strategy of where to store the objects. These are called object stores. The value here is the name of the store. By default, we use the ConcurrentSoftReferenceStore.


Used for mocking. Objects go nowhere!

Objects are kept in a concurrent hashmap but wrapped in a Java SoftReference object, which can sense the JVM's memory. Meaning it can auto-reap if the JVM desires it.

Objects are kept in a concurrent hashmap.

Objects are stored on disk in a directory of choice

Objects are stored in a database table of choice

You can build your own storage

Eviction Policies

  • ,LFU (Least Frequently Used)

  • LRU (Least Recently Used)

  • FIFO (First In First Out)

  • Custom: You can also build your own and pass the instantiation path in this setting

Object Stores

  • ConcurrentStore - Uses concurrent hashmaps for increased performance

  • ConcurrentSoftReferenceStore - Concurrent hashmaps plus java soft references for JVM memory sensitivity

  • DiskStore - Uses a physical disk location for caching (Uses java serialization for complex objects)

  • JDBCStore - Uses a JDBC datasource for caching (Uses java serialization for complex objects)

  • Custom : You can also build your own and pass the instantiation path in this setting.

Caution : Please note that each object store could have more configuration properties that you will need to add to the configuration structure. To find out about these extra configuration properties, please see the Object Store's section.



// Register all the custom-named caches you like here
caches = {
    sampleCache1 = {
        properties = {
    sampleCache2 = {
        provider = "cachebox.system.cache.providers.CFColdboxProvider"

The caches element is a configuration data structure for aggregating named cache providers of ANY type. The key is the unique name of the cache to aggregate under this CacheBox instance. Each provider has unique configuration properties, so explore them as well.






The path of the cache that must implement our ICacheProvider interface.



A structure of name-value pairs of configuration data for the cache to declare.


    // The path to the listener
    // A unique name for the listener
    // A structure of name-value pairs for configuring this interceptor
    properties = {}
{ class="Timer", name="CoolTimer" }

CacheBox has an event-driven model where you can listen to cache operations and cache factory operations. You do so with listener CFCs that you register in your config, mostly for standalone operation. In ColdBox, all interceptors have access to all events.

Caution: Please note that the order of declaration is the same as the order of execution, so it matters, just like ColdBox Interceptors. Using CacheBox within a ColdBox application, you can also register listeners as interceptors in your ColdBox configuration file.






The instantiation path of the listener object to register



The unique name is used for this listener for registration purposes. If no name is provided, we will use the last part of the instantiation path, usually the filename.



A structure of name-value pairs of configuration data for the listener declared.

Last updated