org.apache.commons.jcs3.utils.access

Class JCSWorker<K,V>

java.lang.Object

org.apache.commons.jcs3.utils.access.JCSWorker<K,V>

public class JCSWorker<K,V>
extends Object

Utility class to encapsulate doing a piece of work, and caching the results in JCS. Simply construct this class with the region name for the Cache and keep a static reference to it instead of the JCS itself. Then make a new org.apache.commons.jcs3.utils.access.AbstractJCSWorkerHelper and implement Object doWork() and do the work in there, returning the object to be cached. Then call .getResult() with the key and the AbstractJCSWorkerHelper to get the result of the work. If the object isn't already in the Cache, AbstractJCSWorkerHelper.doWork() will get called, and the result will be put into the cache. If the object is already in cache, the cached result will be returned instead.

As an added bonus, multiple JCSWorkers with the same region, and key won't do the work multiple times: The first JCSWorker to get started will do the work, and all subsequent workers with the same region, group, and key will wait on the first one and use his resulting work instead of doing the work themselves.

This is ideal when the work being done is a query to the database where the results may take time to be retrieved.

For example:

      public static JCSWorker cachingWorker = new JCSWorker("example region");
                public Object getSomething(Serializable aKey){
        JCSWorkerHelper helper = new AbstractJCSWorkerHelper(){
          public Object doWork(){
            // Do some (DB?) work here which results in a list
            // This only happens if the cache doesn't have a item in this region for aKey
            // Note this is especially useful with Hibernate, which will cache individual
            // Objects, but not entire query result sets.
            List results = query.list();
            // Whatever we return here get's cached with aKey, and future calls to
            // getResult() on a CachedWorker with the same region and key will return that instead.
            return results;
        };
        List result = worker.getResult(aKey, helper);
      }
 

This is essentially the same as doing:

 JCS jcs = JCS.getInstance( "exampleregion" );
 List results = (List) jcs.get( aKey );
 if ( results != null )
 {
     //do the work here
     results = query.list();
     jcs.put( aKey, results );
 }
 

But has the added benefit of the work-load sharing; under normal circumstances if multiple threads all tried to do the same query at the same time, the same query would happen multiple times on the database, and the resulting object would get put into JCS multiple times.

Constructor Summary

Constructors

Constructor and Description
JCSWorker(String aRegion) Constructor which takes a region for the JCS cache.

Method Summary

Modifier and Type	Method and Description
String	getRegion() Getter for the region of the JCS Cache.
V	getResult(K aKey, JCSWorkerHelper<V> aWorker) Gets the cached result for this region/key OR does the work and caches the result, returning the result.
V	getResult(K aKey, String aGroup, JCSWorkerHelper<V> aWorker) Gets the cached result for this region/key OR does the work and caches the result, returning the result.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JCSWorker

public JCSWorker(String aRegion)

Constructor which takes a region for the JCS cache.

Parameters:

aRegion - The Region to use for the JCS cache.

Method Detail

getRegion

public String getRegion()

Getter for the region of the JCS Cache.

Returns:

The JCS region in which the result will be cached.

getResult

public V getResult(K aKey,
                   JCSWorkerHelper<V> aWorker)
            throws Exception

Gets the cached result for this region/key OR does the work and caches the result, returning the result. If the result has not been cached yet, this calls doWork() on the JCSWorkerHelper to do the work and cache the result. This is also an opportunity to do any post processing of the result in your CachedWorker implementation.

Parameters:

aKey - The key to get/put with on the Cache.

aWorker - The JCSWorkerHelper implementing Object doWork(). This gets called if the cache get misses, and the result is put into cache.

Returns:

The result of doing the work, or the cached result.

Throws:

Exception - Throws an exception if anything goes wrong while doing the work.

getResult

public V getResult(K aKey,
                   String aGroup,
                   JCSWorkerHelper<V> aWorker)
            throws Exception

Gets the cached result for this region/key OR does the work and caches the result, returning the result. If the result has not been cached yet, this calls doWork() on the JCSWorkerHelper to do the work and cache the result. This is also an opportunity to do any post processing of the result in your CachedWorker implementation.

Parameters:

aKey - The key to get/put with on the Cache.

aGroup - The cache group to put the result in.

aWorker - The JCSWorkerHelper implementing Object doWork(). This gets called if the cache get misses, and the result is put into cache.

Returns:

The result of doing the work, or the cached result.

Throws:

Exception - Throws an exception if anything goes wrong while doing the work.