CacheBox has a nifty little feature that enables itself to leech onto a specific scope in memory. It basically can auto-register itself in your environment with no further need for persistence or just to expand its location. By default CacheBox registers itself in application scope with a key of cacheBox, but you have complete control on how the scope registration should work.

Customizable Keys:

Example:

// The CacheBox configuration structure DSL
cacheBox = {
    scopeRegistration = {
        enabled = true,
        scope   = "application",
        key     = "cacheBox"
    },
};

The LogBoxConfig element is used only in standalone mode of operation and tells CacheBox what configuration file to load into LogBox. LogBox is an enterprise ColdFusion (CFML) logging library. This way, you have granular control of how CacheBox and its registered caches will be producing logging and debugging data. If you do not specify a location for a custom LogBox configuration file, then CacheBox will instantiate LogBox with its own default configuration file located at:

cachebox.system.cache.config.LogBox.cfc

Example

// The CacheBox configuration structure DSL
cacheBox = {
    logBoxConfig = "myapp.config.MyLogBoxConfig",
};

Let's delve deeper into the rabbit hole and explore how to configure this bad boy. Our preference is the programmatic approach via a simple data CFC that can encapsulate the CacheBox configuration in one single component. However, at the end of the day all configuration approaches will use the CacheBoxConfig object's methods in some manner.

This is the CFC that you will use to configure CacheBox and its constructor can be called with the following optional arguments which determines your configuration approach:

• none - Means you will be using the CFCs methods for configuration

• CFCConfig - The object reference to the simple data CFC that contains the CacheBox DSL

• CFCConfigPath - The instantiation path of the simple data CFC that contains the CacheBox DSL

No matter what configuration you decide to use, you will always have to instantiate CacheBox with a CacheBoxConfig object of type: cachebox.system.cache.config.CacheBoxConfig. However, you have the option of either working with this CFC directly or creating a more portable configuration.

This portable configuration we denote as a simple data CFC that contains the CacheBox configuration data that represents our CacheBox DSL (Domain Specific Language). This DSL is exactly the same if you are using CacheBox standalone or in any ColdBox application, so it definitely has its benefits.

Tip: Please note that you have full access to the running CacheBox's configuration object or even a specific cache's configuration structure. Therefore, you can easily change the configuration settings for a cache or CacheBox dynamically at runtime.

The previous CacheBox DSL is a great way to configure CacheBox as it is very portable. However, you can also configure CacheBox by calling methods on the CacheBoxConfig object, which is exactly what we do when we read the CacheBox DSL.

Below are the main methods used for configuring CacheBox which match exactly to the DSL items, so please refer to the DSL items for definitions and settings. Also, for all the methods in this object, check out the API Docs

• init([any CFCConfig], [string CFCConfigPath])

The constructor

• cache(string name, [string provider=], [struct properties={}])

Add a new cache configuration

• defaultCache([numeric objectDefaultTimeout=], [numeric objectDefaultLastAccessTimeout=], [numeric reapFrequency=], [numeric maxObjects=], [numeric freeMemoryPercentageThreshold=], [boolean useLastAccessTimeouts=], [string evictionPolicy=], [numeric evictCount=], [string objectStore=], [boolean coldboxEnabled=])

Add a default cache configuration

• listener(string class, [struct properties={}], [string name=])

Add a new listener configuration

• logBoxConfig(string config)

Set the logBox Configuration path to use

• reset()

Reset the entire configuration

• scopeRegistration([boolean enabled='false'], [string scope='application'], [string key='cachebox'])

Use to define cachebox factory scope registration

Code Examples:

config = new cacheBox.system.cache.config.CacheBoxConfig();

// logbox config & scope chained, yes you can chain any method
config.logBoxConfig( "LogBox" )
    .scopeRegistration( true, "application", "cacheBox" );

// default cache
config.default( maxObjects=500, evictCount=5, objectDefaultTimeout=30 );

// Caches
config.cache( "ehCache", "caches.ehCacheProvider", {configFile="ehCache.xml"} ).
    cache( "template", "cachebox.system.cache.providers.CacheBoxProvider" );

// Listeners
config.listener( "myapp.model.MyListener", "FunkyListener", {} );

The defaultCache element is in itself a structure of configuration data for the default cache provider of type cachebox.system.cache.providers.CacheBoxProvider. This is a reserved cache name and it is MANDATORY to declare and its name or 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. So let's see the configuration keys for our default cache.

Default Cache Properties:

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:

// The CacheBox configuration structure DSL
cacheBox = {
    // Please note that each object store could have more configuration properties
    defaultCache = {
        objectDefaultTimeout = 60,
        objectDefaultLastAccessTimeout = 30,
        useLastAccessTimeouts = true,
        reapFrequency = 2,
        freeMemoryPercentageThreshold = 0,
        evictionPolicy = "LRU",
        evictCount = 1,
        maxObjects = 200,
        // Our default store is the concurrent soft reference
        objectStore = "ConcurrentSoftReferenceStore",
        // This switches the internal provider from normal cacheBox to coldbox enabled cachebox
        coldboxEnabled = false,
        resetTimeoutOnAccess = false
    },
};

The caches element is in itself a structure of configuration data for aggregating named cache providers of ANY type. The key is the unique name of the cache to aggregate under this CacheBox instance. The value should be a structure with the following keys:

Example:

// 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"
    }
},

This is an array of structures that you will use to define cache listeners. This is exactly the same as if you would be declaring ColdBox Interceptors, so order is very important. The order of declaration is the order that they are registered into their specific listening events and also the order in which they fire. The keys to declare for each structure are:

In order to create a simple data CFC, just create a new CFC with one required method on it called configure(). This is where you will define the caching configuration data structure in a structure called cacheBox in the variables scope:

**
* A CacheBox configuration data object
*/
component{

    function configure(){
        cacheBox = {

        };
    }
}

The cacheBox structure can be configured with the following keys:

Default Configuration

The default configuration file for CacheBox within ColdBox applications can be found here

This configuration file configures CacheBox with two caches:

• default

• template

The default cache can be used for any type of data caching or object persistence. The template cache is used for event caching and view fragment caching. It is also important to note that the template cache uses the ConcurrentSoftReferenceStore for its objects and the default cache uses the ConcurrentStore for its objects.

This means that event/view caching is subject to available memory via the JVM, a memory sensitive cache. This is essential as you could have lots of events being cached and you want to be considerate with memory concerns. It is also limited to 300 objects.

Now, this is all nice and dandy, but what if I want to configure CacheBox "MY WAY!!"? Well, don't shout, we are just getting there. There are several ways you can configure CacheBox from within your applications, so chose wisely.

Custom Configuration

ColdBox allows for a programmatic approach via the ColdBox configuration object: Coldbox.cfc. So let's look at how the framework loader looks at your configuration for CacheBox configuration details:

• Is there a cachebox DSL variable defined in the configuration structure?

• False:

  • Does a CacheBox.cfc exist in the application's config folder?

    • True : Use that for configuration

    • False: Configure CacheBox with default framework settings found in /coldbox/system/web/config/CacheBox.cfc

• True:

  • Have you defined a configFile key in the cacheBox DSL structure?

    • True: Then use that value to pass into the configuration object so it can load CacheBox using that configuration CFC

    • False: The configuration data (CacheBox DSL) is going to be defined inline here so use that structure for configuration

Info The configuration DSL is exactly the same as you have seen in before with the only distinction that you can add a configFile key that can point to an external configuration CFC.

That's it folks! You can either write inline CacheBox DSL configuration, use by convention a CacheBox.cfc data CFC or use a configFile approach for external file loading. Pick your poison!