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

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 seconds. The default is 5.

Component Configuration Example

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

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.

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.