svn commit: r952011 - in /cayenne/main/trunk/framework/cayenne-jdk1.5-unpublished/src/main/java/org/apache/cayenne/cache: OSQueryCache.java QueryCache.java

[aa...@apache.org]

Author: aadamchik
Date: Sun Jun  6 22:11:00 2010
New Revision: 952011

URL: http://svn.apache.org/viewvc?rev=952011&view=rev
Log:
javadocs update to address cache size confusion

Modified:
    cayenne/main/trunk/framework/cayenne-jdk1.5-unpublished/src/main/java/org/apache/cayenne/cache/OSQueryCache.java
    cayenne/main/trunk/framework/cayenne-jdk1.5-unpublished/src/main/java/org/apache/cayenne/cache/QueryCache.java

Modified: cayenne/main/trunk/framework/cayenne-jdk1.5-unpublished/src/main/java/org/apache/cayenne/cache/OSQueryCache.java
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/framework/cayenne-jdk1.5-unpublished/src/main/java/org/apache/cayenne/cache/OSQueryCache.java?rev=952011&r1=952010&r2=952011&view=diff
==============================================================================
--- cayenne/main/trunk/framework/cayenne-jdk1.5-unpublished/src/main/java/org/apache/cayenne/cache/OSQueryCache.java (original)
+++ cayenne/main/trunk/framework/cayenne-jdk1.5-unpublished/src/main/java/org/apache/cayenne/cache/OSQueryCache.java Sun Jun  6 22:11:00 2010
@@ -258,8 +258,8 @@ public class OSQueryCache implements Que
 
     /**
      * Returns a non-null cached value. If it is not present in the cache, it is obtained
-     * by calling {@link QueryCacheEntryFactory#createObject()}. Whether the cache provider
-     * will block on the entry update or not is controlled by "cache.blocking"
+     * by calling {@link QueryCacheEntryFactory#createObject()}. Whether the cache
+     * provider will block on the entry update or not is controlled by "cache.blocking"
      * configuration property and is "false" by default.
      */
     @SuppressWarnings("unchecked")
@@ -309,7 +309,7 @@ public class OSQueryCache implements Que
             }
         }
     }
-    
+
     /**
      * Returns non-null RefreshSpecification for the QueryMetadata.
      */
@@ -384,6 +384,7 @@ public class OSQueryCache implements Que
     }
 
     final static class OSCacheAdministrator extends GeneralCacheAdministrator {
+
         OSCacheAdministrator() {
         }
 

Modified: cayenne/main/trunk/framework/cayenne-jdk1.5-unpublished/src/main/java/org/apache/cayenne/cache/QueryCache.java
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/framework/cayenne-jdk1.5-unpublished/src/main/java/org/apache/cayenne/cache/QueryCache.java?rev=952011&r1=952010&r2=952011&view=diff
==============================================================================
--- cayenne/main/trunk/framework/cayenne-jdk1.5-unpublished/src/main/java/org/apache/cayenne/cache/QueryCache.java (original)
+++ cayenne/main/trunk/framework/cayenne-jdk1.5-unpublished/src/main/java/org/apache/cayenne/cache/QueryCache.java Sun Jun  6 22:11:00 2010
@@ -24,6 +24,11 @@ import org.apache.cayenne.query.QueryMet
 
 /**
  * An interface that defines generic QueryCache.
+ * <p>
+ * Note that depending on implementation, {@link #remove(String)},
+ * {@link #removeGroup(String)} and {@link #clear()} methods may mark the matching
+ * existing entries as expired instead of actually removing them. So it may appear that
+ * the size of the cache, as reported by {@link #size()} method, is unchanged.
  * 
  * @since 3.0
  */
@@ -40,7 +45,8 @@ public interface QueryCache {
      * Returns a cached query result for the given QueryMetadata. If the result is not
      * cached or is expired, cache will use provided factory to rebuild the value and
      * store it in the cache. A corollary is that this method never returns null.
-     * <p/>Compared to {@link #get(QueryMetadata)}, this method allows the cache to do
+     * <p/>
+     * Compared to {@link #get(QueryMetadata)}, this method allows the cache to do
      * appropriate synchronization when refreshing the entry, preventing multiple threads
      * from running the same query when a missing entry is requested by multiple threads
      * simultaneously.
@@ -57,15 +63,22 @@ public interface QueryCache {
     void remove(String key);
 
     /**
-     * Removes a group of entries identified by group key. This may not be supported by
-     * the implementation.
+     * Removes a group of entries identified by group key. Note that depending on
+     * implementation this method may either actively remove the entries belonging to the
+     * group or just mark them as expired, so that they are refreshed on the next access.
+     * In the former case the cache size would shrink, but in the later the cache size
+     * will not change after calling this method.
      */
     void removeGroup(String groupKey);
 
     /**
-     * Clears all entries.
+     * Clears all cache entries.
      */
     void clear();
 
+    /**
+     * Returns the number of entries currently in the cache, including expired but not
+     * removed entries.
+     */
     int size();
 }