{{{Redirect pageName='CacheBox')}}} [[Dashboard | << Back to Dashboard ]] {|align="right" | __TOC__ |} = ColdBox Cache Guide = == Introduction == The ColdBox Cache is an in-memory cache that lives in '''Application Scope''' designed for handlers, plugins, events, views and any other objects or data you so desire. It has various tuning parameters such as default object timeout, default last access timeout, maximum objects to have in cache, a JVM memory threshold, a reaping frequency, eviction policies, an event model and so much more. The cache is based on java soft references (explained further below), several concurrency classes (if using JDK 5 and above) and is multi-threaded, which makes it an incredibly stable and fast caching engine. The cache is also tied to an event broadcast model, implemented via ColdBox interceptors, that can announce when objects are cached, removed or expired. In this guide we will explore the concepts, configurations and how to use the ColdBox Cache. '''Useful Resources''' * http://ecet.ecs.ru.acad.bg/cst05/Docs/cp/SII/II.20.pdf * http://www.ibm.com/developerworks/java/library/j-jtp01246.html * http://java.sun.com/j2se/1.5.0/docs/api/java/lang/ref/SoftReference.html * http://jdj.sys-con.com/read/36434_p.htm == ColdBox Cache Features == * Fast and Simple ** Fast ColdFusion and Java hybrid cache ** Simple API and basic configuration parameters ** Small Footprint ** No need to create it, configure it or manage it if used within a ColdBox Application * Solid Core ** Multi-Threaded ** Based on Java Concurrency Classes ** Multiple Eviction Policies: LRU,LFU and FIFO ** Memory Management & Memory Sensitive caching based on Java Soft References ** Production Tested ** Fully Documented * Extensible & Flexible ** Cache Listeners for broadcasting when objects are: *** inserted *** removed *** expired ** Create your own custom eviction policies ** Extensive and granular purging mechanisms (regular expressions and key snippets) ** Cache Statistics API for creating custom cache reports * Highly Configurable ** JVM Threshold Checks ** Object Limits ** Ability to time expire objects ** Eternal (singletons) and time-lived objects ** Object purging based on object usage (Access Timeouts) ** Fully configurable at runtime via dynamic configurations and hot-updates * Visually Appealing and Useful ** Fully featured caching monitor and commands panel ** Complete cache performance reports
"In the past, developers didn't have much control over garbage collection or memory management. Java2 has changed that by introducing the java.lang.ref package. The abstract base class Reference is inherited by classes SoftReference, WeakReference and PhantomReference. SoftReferences are well suited for use in applications needing to perform caching."Why is this? Well, a soft reference is nothing but a wrapper class that wraps an object in memory. Whenever the JVM requires memory and runs its reference rules, it can detect these soft references and decide to purge them if it meets the garbage collector rules. If it purges them, the wrapped object inside of the soft reference is marked for collection, but the java soft reference itself still exists. Therefore, the programmer can determine if the object inside the reference exists or not. If it does not exist, it means the object was garbage collected and I have no more object. I won't go into the implementation semantics of the cache, just theory. Please visit the references to understand more of how the ColdBox cache was built. In summary, soft references are what determine if an object is still available or not. The ColdBox cache can then run maintenance on itself and clean out all of its references for you. == Configuring the cache == The ColdBox cache can be configured framework wide by tweaking the framework's settings xml file or via the ColdBox Dashboard. However, you can override all the values in your application via its configuration file (coldbox.xml.cfm). I will list below a table of the main settings and the framework defaults. {|cellpadding="5", class="tablelisting" ! '''Setting''' !! '''Type''' !! '''Default Value''' !! '''Description''' |- || '''ObjectDefaultTimeout''' || numeric || 60 || the default lifespan of an object in minutes |- || '''ObjectDefaultLastAccessTimeout''' || numeric || 30 || the default last access timeout in minutes |- || '''UseLastAccessTimeouts''' || Boolean || true || whether to use last access expirations |- || '''ReapFrequency''' || numeric || 1 || The delay in minutes to produce a cache reap (Not guaranteed) |- || '''MaxObject''' || numeric || 100 || The maximum number of objects in the cache |- || '''FreeMemoryPercentageThreshold''' || numeric || 0 || The numerical percentage threshold of free JVM memory to have. If the jvm free memory falls below this setting, the cache will no longer cache objects but evict them. (0=Unlimited) |- || '''EvictionPolicy''' || string || LRU || The eviction policy algorithm class to use. ColdBox ships with LFU, LRU and FIFO |} Sample application configuration xml for your application's configuration file:
index.cfm?debugpanel=cache== Techniques == There are various ways that you can use the ColdBox cache and it all depends on the data you want to store and how to retrieve it. One method that I have used for storing queries in the cache is to use the on application start method to place the queries on the cache indefinitely.