Fulcrum Cache – Cache Component

Overview

This Service functions as a Global Cache. A global cache is a good place to store items that you may need to access often but don't necessarily need (or want) to fetch from the database everytime. A good example would be a look up table of States that you store in a database and use throughout your application. Since information about States doesn't change very often, you could store this information in the Global Cache and decrease the overhead of hitting the database everytime you need State information.

There are three cache implementations

GlobalCacheService,
EHCacheService (built on the EHCache project from ehcache.sourceforge.net, N.B. The implementation is still based on last release 2.10.9.2 of net.sf.ehcache.EHcache) and
JCSCacheService (built on the Java Caching System, which was originally a part of Turbine)

It is written for use in Turbine but it can be used in any container compatible with Avalon's ECM container.

GlobalCacheService

Role Configuration

    <role
        name="org.apache.fulcrum.cache.GlobalCacheService"
        shorthand="cache"
        default-class="org.apache.fulcrum.cache.impl.DefaultGlobalCacheService"/>

Component Configuration

Item	Datatype	Cardinality	Description
@cacheInitialSize	int	[0\|1]	The initial size of the cache. The default is 20.
@cacheCheckFrequency	int	[0\|1]	The cache uses a background thread to check for expired objects. This defines the time between two checks in milliseconds. The default is 5000.

Component Configuration Example

    <cache cacheInitialSize="20" cacheCheckFrequency="5000"/>

EHCacheService

Role Configuration

    <role
        name="org.apache.fulcrum.cache.GlobalCacheService"
        shorthand="ehcache"
        default-class="org.apache.fulcrum.cache.impl.EHCacheService"/>

Component Configuration

Item	Datatype	Cardinality	Description
cacheCheckFrequency	int	[0\|1]	The cache uses a background thread to check for expired objects. This defines the time between two checks in milliseconds. The default is 5000.
cacheName	String	[0\|1]	The EHcache cache name to use for the cache. The default is `fulcrum`.
configurationFile	String	[0\|1]	The the location of the EHcache configuration file. The default is to create a default cache withut settings.

z See the JCS site for more information about configuring JCS.

Component Configuration Example

    <ehcache>
        <cacheCheckFrequency>5000</cacheCheckFrequency>
        <cacheName>fulcrum</cacheName>
        <configurationFile>ehcache.xml</configurationFile>
    </ehcache>

JCSCacheService

The JCS cache service implements the interface GlobalCacheService and thus can serve as a drop-in replacement for DefaultGlobalCacheService. However it is possible to configure the cache behavior in much more detail to provide disk caches or lateral TCP caches for example.

Role Configuration

    <role
        name="org.apache.fulcrum.cache.GlobalCacheService"
        shorthand="jcscache"
        default-class="org.apache.fulcrum.cache.impl.JCSCacheService"/>

Component Configuration

Item	Datatype	Cardinality	Description
cacheCheckFrequency	int	[0\|1]	The cache uses a background thread to check for expired objects. This defines the time between two checks in milliseconds. The default is 5000.
region	String	[0\|1]	The JCS cache region name to use for the cache. The default is `fulcrum`. JCS will store the objects in a group named `default_group` in the given region.
configurationFile	String	[0\|1]	The the location of the JCS configuration file. Please note that JCS uses a class loader to read this file, so make sure this path is part of your classpath. The default is `/cache.ccf`.

See the JCS site for more information about configuring JCS.

Component Configuration Example

    <jcscache>
    	<cacheCheckFrequency>5000</cacheCheckFrequency>
    	<region>fulcrum</region>
    	<configurationFile>/cache.ccf</configurationFile>
    </jcscache>

Usage

    GlobalCacheService gs = null;
    try
    {
        /*
         * Look for the item in the cache.
         * If it doesn't exist or the item is stale,
         * the cache will throw an exception.
         */
        gs = (GlobalCacheService)avalonComponentService.lookup(GlobalCacheService.ROLE)

        CachedObject obj = gs.getObject("cached_object");

        data.setMessage( data.getScreen() + " Got " +
            obj.getContents().toString() + " from global cache!" );
    }
    catch(ObjectExpiredException gone)
    {
        /*
         * Add the item to the cache.
         */
        gs.addObject("cached_object",
            new CachedObject("in_the_cache",5000));

        data.setMessage( data.getScreen() +
            " Refreshed/or added new item to" +
            " the cache! Expires in 5 seconds" );
    }

You can also place an expiration time on your objects so the Service will automatically remove them when they expire. If you don't specify an expiration time, the DefaultGlobalCacheService uses 5 seconds. For JCS this value depends on values set in the cache configuration file. To see an example, look at the test case CacheTest

The cache also supports RefreshableCachedObjects. These objects must implement a refresh()-method which will be called every time the cache detects that the object is expired. This way, you can keep objects in the cache that "auto-refresh" asynchronously.