Here is a list of some of the most common methods you can use to interact with CacheBox. For full details, please view the online API Docs

• addCache(any<ICacheProvider> cache)

Register a new instantiated cache with this cache factory

• addDefaultCache(string name)

Add a default named cache to our registry, create it, config it, register it and return it of type: cachebox

• clearAll()

Clears all the elements in all the registered caches without de-registrations

• configure(CacheBoxConfig config)

Configure the cache factory for operation, called by the init()

• expireAll()

Expires all the elements in all the registered caches without de-registrations

• getCache(string name)

Get a reference to a registered cache in this factory

• getDefaultCache()

Get the default cache provider of type cachebox

• reapAll()

A nice way to call reap on all registered caches

• removeCache(string name)

Try to remove a named cache from this factory

• replaceCache(any<ICacheProvider> cache, any<ICacheProvider> decoratedCache)

Replace a registered named cache with a new decorated cache of the same name

• shutdown()

Recursively sends shutdown commands to all registered caches and cleans up in preparation for shutdown

Common Operation Examples

// Add another default cache type but with the name FunkyCache
funkyCache = cachebox.addDefaultCache("FunkyCache");
// Add some elements to funky Cache
funkyCache.set("Myentry",now(),"20");

// Get a reference to a named cache
cfCache = cacheBox.getCache("CFCache");

// Get a reference to the default named cache
cache = cacheBox.getDefaultCache();

// Remove our funky cache no longer needed
cacheBox.removeCache("FunkyCache");

// Create a new cache a replace a cache, the MyFunkyFunkyCache implements ICacheProvider
newCache = new MyFunkyFunkyCache({maxObjects=200,timeout=30});
// replace the CFCache with this one
cacheBox.replaceCache( "CFCache", newCache );

// Add a new cache to cachebox programmatically
newCache = new MyFunkyFunkyCache("FunkynessCache", {maxObjects=200,timeout=30});
cacheBox.addCache( newCache );

// Send a shutdown command to cachebox
cachebox.shutdown();

Info Remember that some of the CacheBox methods announce events. So please see our event model section to see what kind of events you can listen to when working with CacheBox.

CacheBox is the core framework you need to instantiate in order to work with caching in your application. You can instantiate it with a CacheBoxConfig object that will hold all of your caching configurations. To configure the library you can either do it programmatically or via a struct/data DSL, the choice is yours. After the library is instantiated and configured you can ask from it a named cache provider, or interact with the caches. By default, CacheBox can be started with no configuration and it will configure itself with the default configuration that is shipped with CacheBox that can be found in the following location:

/cachebox/system/cache/config/DefaultConfiguration.cfc

The default configuration is the following:

function configure(){
    // The CacheBox configuration structure DSL
    cacheBox = {
        // LogBox Configuration file
        logBoxConfig = "cachebox.system.cache.config.LogBox",

        // Scope registration, automatically register the cachebox factory instance on any CF scope
        // By default it registers itself on application scope
        scopeRegistration = {
            enabled = true,
            scope   = "application", // valid CF scope
            key     = "cacheBox"
        },

        // 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,
            // Our default store is the concurrent soft reference
            objectStore = "ConcurrentSoftReferenceStore",
            // This switches the internal provider from normal cacheBox to coldbox enabled cachebox
            coldboxEnabled = false
        },

        // Register all the custom named caches you like here
        caches = {},
        // Register all event listeners here, they are created in the specified order
        listeners = []
    };
}

If you are using CacheBox within a ColdBox application you do not need to worry about creating or even configuring the framework, as ColdBox ships already with a default configuration for ColdBox applications. However, you also have full control of configuring CacheBox at your application level (Please see the ColdBox application configuration section). The default configuration for a ColdBox application can be found in the following location:

/coldbox/system/web/config/CacheBox.cfc

Modes of Operation

In summary, CacheBox has two modes of operation:

• Standalone Framework

• ColdBox Application

If you have downloaded CacheBox as a standalone framework, then please make sure you use the correct namespace path (cachebox.system). Also, once you create CacheBox make sure that you persist it somewhere, either in Application scope or any other scope or a dependency injection context (WireBox). ColdBox application users already have an instance of CacheBox created for you in every application and it is stored in the main application controller and can be retrieved via the following function:

// Get a reference to CacheBox
controller.getCacheBox();

// Get a reference to the default cache provider
controller.getCache() or getCache()

// Get a reference to a named cache provider
controller.getCache("template") or getCache("template")

Info Note: Most of the examples shown in this documentation refer the default framework namespace of coldbox.system. However, if you are using CacheBox as a standalone framework, then the namespace to use is cachebox.system. Happy Coding!

Creating CacheBox Examples

Let's start with the simplest example of them all which is just creating CacheBox with the default configuration. The rest of the samples show different configuration options:

import cachebox.system.cache.*;

// create cachebox
cachebox = new CacheFactory();
// get the default cache
cache = cachebox.getDefaultCache();
// set a value in cache, with 60 minute timeout and 20 minute idle timeout.
cache.set("MyValue", {name="Luis Majano", awesome=true, cacheWeirdo=true}, 60,20);

Here are some more configuration samples:

// Create CacheBox with default configuration
cacheBox = new cachebox.system.cache.CacheFactory( );


// Create CacheBox instance
cacheBox = new cachebox.system.cache.CacheFactory( config );

// Create the config object as a CacheBox DSL Simple CFC
dataCFC = new MyCacheBoxConfig();
config = new cachebox.system.cache.config.CacheBoxConfig( CFCConfig=dataCFC );
// Create CacheBox instance
cacheBox = new cachebox.system.cache.CacheFactory( config );


// Create the config object as a CacheBox DSL Simple CFC path only
config = new cachebox.system.cache.config.CacheBoxConfig( CFCConfigPath="MyCacheBoxConfig" );
// Create CacheBox instance
cacheBox = new cachebox.system.cache.CacheFactory( config );

// Create CacheBoxConfig, call configuration methods on it and then create the factory
config = new cachebox.system.cache.config.CacheBoxConfig();
// Configure programmatically: You can chain methods, woot!
config.scopeRegistration( true, "application" )
    .defaultCache( objectStore="DiskStore", maxObject=200 );
// Create CacheBox instance
cacheBox = new cachebox.system.cache.CacheFactory( config );

If you are using CacheBox within a ColdBox application, ColdBox is in charge of emitting reaping or cleanup requests to the CacheBox factory. However, if you are using the standalone version of the cache, then you will need to emit this command yourself in the desired execution point. We would suggest to do this on every request. This does not mean that the request executes every time, it means that the trigger is made and if the reaping time has been elapsed, then the caches clean themselves (CacheBox Providers Only!):

cachebox.reapAll();

That's it! Just call on the reapAll() method and this will make sure that your caches clean themselves according to the reaping frequency selected in your configuration file.

Info: Reaping frequency and cleanup only applies to the CacheBox Provider.