Merged HEAD-QA to HEAD (4.2) - final one

r54310-54386


git-svn-id: https://svn.alfresco.com/repos/alfresco-enterprise/alfresco/HEAD/root@54387 c4b6b30b-aa2e-2d43-bbcb-ca4b014f7261

source/java/org/alfresco/repo/cache/CacheFactory.java

@@ -29,8 +29,34 @@ import java.io.Serializable;
  */
 public interface CacheFactory<K extends Serializable, V>
 {
+    /**
+     * Creates a fully distributed cache (when clustering is enabled and active).
+     * 
+     * @param cacheName
+     * @return SimpleCache
+     */
     SimpleCache<K, V> createCache(String cacheName);
+    
+    /**
+     * Creates a "local" cache, i.e. one that exists only on the JVM that created it. It does not
+     * attempt to replicate any data, send invalidation messages etc. and is intended for use
+     * only where the data does not need to be shared and where remote operations should be avoided for
+     * performance reasons.
+     *  
+     * @param cacheName
+     * @return SimpleCache
+     */
     SimpleCache<K, V> createLocalCache(String cacheName);
-    SimpleCache<K, V> createInvalidatingCache(String cacheName);
+    
+    /**
+     * <p>Creates a local (as opposed to fully-distributed) cache that broadcasts invalidation messages
+     * to its peers on other cluster members upon cache item removal. Its peers then remove the
+     * corresponding cache item.</p>
+     * 
+     * <p>This cache does <strong>not</strong> replicate put(k,v) invocations.</p> 
+     * 
+     * @param cacheName
+     * @return SimpleCache
+     */
     SimpleCache<K, V> createInvalidateRemovalCache(String cacheName);
 }