1 files changed, 78 insertions, 20 deletions

diff --git a/java/src/IceUtil/Cache.java b/java/src/IceUtil/Cache.java
index 00e98e27051..2fc00d10816 100644
--- a/java/src/IceUtil/Cache.java
+++ b/java/src/IceUtil/Cache.java
@@ -9,18 +9,37 @@
 
 package IceUtil;
 
-//
-// An abstraction to efficiently populate a Cache, without holding
-// a lock while loading from a potentially slow store.
-//
+/**
+ * An abstraction to efficiently maintain a cache, without holding
+ * a lock on the entire cache while objects are being loaded from
+ * their backing store. This class is useful mainly to implement
+ * evictors, such as used by Freeze.
+ *
+ * @see Store
+ * @see Freeze.Evictor
+ **/
 
 public class Cache
 {
+    /**
+     * Initialize a cache using the specified backing store.
+     **/
     public Cache(Store store)
     {
         _store = store;
     }
 
+    /**
+     * Return the value stored for the given key from the cache.
+     *
+     * @param key The key for the object to look up in the cache.
+     *
+     * @return If the cache contains an entry for the key, the return value
+     * is the object corresponding to the key; otherwise, the return value
+     * is null. <code>getIfPinned</code> does not call load.
+     *
+     * @see Store.load
+     **/
     public Object
     getIfPinned(Object key)
     {
@@ -31,6 +50,15 @@ public class Cache
         }
     }
 
+    /**
+     * Removes the entry for the given key from the cache.
+     *
+     * @param key The key for the entry to remove.
+     *
+     * @return If the cache contains an entry for the key, the
+     * return value is the corresponding object; otherwise, the
+     * return value is <code>null</code>.
+     **/
     public Object
     unpin(Object key)
     {
@@ -41,6 +69,9 @@ public class Cache
         }
     }
 
+    /**
+     * Removes all entries from the cache.
+     **/
     public void
     clear()
     {
@@ -50,6 +81,11 @@ public class Cache
         }
     }
 
+    /**
+     * Returns the number of entries in the cache.
+     *
+     * @return The number of entries.
+     **/
     public int
     size()
     {
@@ -59,12 +95,18 @@ public class Cache
         }
     }
 
-    //
-    // Add an object to the cache without checking store
-    // If there is already an object associated with this
-    // key, the existing value remains in the map and is
-    // returned.
-    //
+    /**
+     * Adds a key-value pair to the cache.
+     * This version of <code>pin</code> does not call <code>Store.load</code> to retrieve
+     * an entry from backing store if an entry for the given key is not yet in the cache. This
+     * is useful to add a newly-created object to the cache.
+     *
+     * @param key The key for the entry.
+     * @param o The value for the entry.
+     * @return If the cache already contains an entry with the given key, the entry is
+     * unchanged and <code>pin(Object, Object)</code> returns the original value for the entry; otherwise,
+     * the entry is added and <code>pin(Object, Object)</code> returns <code>null</code>.
+     **/
     public Object
     pin(Object key, Object o)
     {
@@ -83,22 +125,38 @@ public class Cache
         }
     }
 
-    //
-    // Return an object from the cache, loading it from the
-    // store if necessary.
-    //
+    /**
+     * Returns an object from the cache.
+     * If no entry with the given key is in the cache, <code>pin</code> calls
+     * <code>load</code> to retrieve the corresponding value (if any) from the
+     * backing store.
+     *
+     * @param key The key for the entry to retrieve.
+     * @return Returns the value for the corresponding key if the cache
+     * contains an entry for the key. Otherwise, <code>pin(Object)</code> calls
+     * <code>Store.load</code> and the return value is whatever is returned by
+     * <code>load</code>; if <code>load</code> throws an exception, that exception
+     * is thrown by <code>pin(Object)</code>.
+     **/
     public Object
     pin(Object key)
     {
         return pinImpl(key, null);
     }
 
-    //
-    // Puts this key/value pair in the cache.
-    // If this key is already in the cache or store, the given
-    // key/value pair is not inserted and the existing value
-    // is returned.
-    //
+    /**
+     * Adds a key-value pair to the cache.
+     * @param key The key for the entry.
+     * @param newObj The value for the entry.
+     * @return If the cache already contains an entry for the given key,
+     * <code>putIfAbsent</code> returns the original value for that key.
+     * If no entry is for the given key is in the cache, <code>putIfAbsent</code>
+     * calls <code>load</code> to retrieve the corresponding entry (if any) from
+     * the backings store and returns the value returned by <code>load</code>.
+     * If the cache does not contain an entry for the given key and <code>load</code>
+     * does not return a value for the key, <code>putIfAbsent</code> adds the new entry
+     * and returns <code>null</code>.
+     **/
     public Object
     putIfAbsent(Object key, Object newObj)
     {