Merged DEV/DEREK_2.1 to HEAD

- Removed Node.parentAssocs mapping
 - Added parentAssocs transactional cache to NodeDAO
 - Added concurrency detection to TransactionalCache
 - Fixed cluster sample config


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

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

@@ -34,19 +34,48 @@ import java.util.Collection;
  * <tt>Serializable</tt> for both keys and values ensures that the underlying
  * cache implementations can support both clustered caches as well as persistent
  * caches.
+ * <p>
+ * All implementations must support <tt>null</tt> values.  It therefore follows
+ * that
+ * <pre>
+ *    (simpleCache.contains(key) == true) does not imply (simpleCache.get(key) != null)
+ * </pre>
+ * but
+ * <pre>
+ *    (simpleCache.contains(key) == false) implies (simpleCache.get(key) == null)
+ * <pre>
  * 
  * @author Derek Hulley
  */
 public interface SimpleCache<K extends Serializable, V extends Object>
 {
+    /**
+     * @param key       the cache key to check up on
+     * @return          Returns <tt>true</tt> if there is a cache entry,
+     *                  regardless of whether the value itself is <tt>null</tt>
+     */
     public boolean contains(K key);
     
     public Collection<K> getKeys();
     
+    /**
+     * @param key
+     * @return          Returns the value associated with the key.  It will be <tt>null</tt>
+     *                  if the value is <tt>null</tt> or if the cache doesn't have an entry.
+     */
     public V get(K key);
     
+    /**
+     * @param key       the key against which to store the value
+     * @param value     the value to store.  <tt>null</tt> is allowed.
+     */
     public void put(K key, V value);
     
+    /**
+     * Removes the cache entry whether or not the value stored against it is <tt>null</tt>.
+     * 
+     * @param key       the key value to remove
+     */
     public void remove(K key);
     
     public void clear();