Author: julien_viet Date: 2011-01-26 04:52:23 -0500 (Wed, 26 Jan 2011) New Revision: 5818 Modified: portal/trunk/component/common/src/main/java/org/exoplatform/commons/cache/future/FutureCache.java Log: clarify FutureCache usage with javadoc Modified: portal/trunk/component/common/src/main/java/org/exoplatform/commons/cache/future/FutureCache.java =================================================================== --- portal/trunk/component/common/src/main/java/org/exoplatform/commons/cache/future/FutureCache.java 2011-01-25 17:12:23 UTC (rev 5817) +++ portal/trunk/component/common/src/main/java/org/exoplatform/commons/cache/future/FutureCache.java 2011-01-26 09:52:23 UTC (rev 5818) @@ -25,9 +25,20 @@ import java.util.concurrent.*; /** - * A future cache that prevents the loading of the same resource twice. This should be used when the resource - * to load is very expensive or cannot be concurrently retrieved (like a classloading). + * <p>A future cache that prevents the loading of the same resource twice. This should be used when the resource + * to load is very expensive or cannot be concurrently retrieved (like a classloading).</p> * + * <p>The future cache should be used with the {@link #get(Object, Object)} method, that retrieves an object + * from the cache. When the object is not found, then the {@link Loader#retrieve(Object, Object)} method is + * used to retrieve the data and then this data is inserted in the cache.</p> + * + * <p>The class is abstract and does not implement a cache technology by itself, the cache implementation is delegated + * to the contractual methods {@link #get(Object)} and {@link #put(Object, Object)}. Those methods are intended + * to be used by the future cache only.</p> + * + * <p>The {@link Loader} interface provides a source to retrieve objects to put in the cache. The goal to maintain + * this interface is to decouple the cache from the object source.</p> + * * @author <a href="mailto:julien.viet@exoplatform.com">Julien Viet</a> * @version $Revision$ * @param <K> the key type parameter @@ -52,8 +63,21 @@ this.futureEntries = new ConcurrentHashMap<K, FutureTask<V>>(); } + /** + * Retrieves the cached value corresponding to the specified key from the cache, it must returns null when the + * key does not exist. This method is intended for internal use by the future cache only. + * + * @param key the key + * @return the cache value + */ protected abstract V get(K key); + /** + * Updates the cache with a new key/value pair. This method is intended for internal use by the future cache only. + * + * @param key the key + * @param value the cache value + */ protected abstract void put(K key, V value); /**