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
*/
component{

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

        };
    }
}

Base Config

The cacheBox structure can be configured with the following keys:

Key	Required	Description
logBoxConfig	false	The instantiation or location of a LogBox configuration file. This is only for standalone operations.
scopeRegistration	false	A structure that enables scope registration of the CacheBox factory in either server, cluster, application, or session scope.
defaultCache	true	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.
caches	true	A structure where you can create more named caches for usage in your CacheBox factory.
listeners	false	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.

LogBoxConfig

// 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

Key	Type	Required	Default	Description
enabled	boolean	false	true	Enable scope registration
scope	string	false	application	The ColdFusion scope to persist on
key	string	false	cachebox	The name of the key in the ColdFusion scope to persist on

DefaultCache

// 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.

Store	Description
BlackHoleStore	Used for mocking. Objects go nowhere!
ConcurrentSoftReferenceStore	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.
ConcurrentStore	Objects are kept in a concurrent hashmap.
DiskStore	Objects are stored on disk in a directory of choice
JDBCStore	Objects are stored in a database table of choice
Custom Stores	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.

Example:

Caches

// Register all the custom-named caches you like here
caches = {
    sampleCache1 = {
        provider="cachebox.system.cache.providers.CacheBoxProvider",
        properties = {
            objectDefaultTimeout="20",
            useLastAccessTimeouts="false",
            reapFrequency="1",
            evictionPolicy="LFU",
            evictCount="1",
            maxObjects="100",
            objectStore="ConcurrentSoftReferenceStore"
        }
    },
    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.

Key	Type	Description
provider	string	The path of the cache that must implement our ICacheProvider interface.
properties	struct	A structure of name-value pairs of configuration data for the cache to declare.

Listeners

{
    // The path to the listener
    class="path.to.CFC",
    // A unique name for the listener
    name="UniqueName",
    // 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.

Key	Type	Description
class	path	The instantiation path of the listener object to register
name	string	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.
properties	struct	A structure of name-value pairs of configuration data for the listener declared.