svn commit: r1753494 - in /jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/cache: CacheLIRS.java CacheStats.java

[th...@apache.org]

Author: thomasm
Date: Wed Jul 20 12:25:56 2016
New Revision: 1753494

URL: http://svn.apache.org/viewvc?rev=1753494&view=rev
Log:
OAK-4578 Clarify weight related methods/parameters/arguments of the LIRS cache

Modified:
    jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/cache/CacheLIRS.java
    jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/cache/CacheStats.java

Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/cache/CacheLIRS.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/cache/CacheLIRS.java?rev=1753494&r1=1753493&r2=1753494&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/cache/CacheLIRS.java (original)
+++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/cache/CacheLIRS.java Wed Jul 20 12:25:56 2016
@@ -251,10 +251,11 @@ public class CacheLIRS<K, V> implements
     }
 
     /**
-     * Add an entry to the cache. The entry may or may not exist in the
-     * cache yet. This method will usually mark unknown entries as cold and
-     * known entries as hot.
-     *
+     * Add an entry to the cache. This method is an explicit memory size
+     * (weight), and not using the weigher even if configured. The entry may or
+     * may not exist in the cache yet. This method will usually mark unknown
+     * entries as cold and known entries as hot.
+     * 
      * @param key the key (may not be null)
      * @param value the value (may not be null)
      * @param memory the memory used for the given entry
@@ -266,8 +267,9 @@ public class CacheLIRS<K, V> implements
     }
 
     /**
-     * Add an entry to the cache using the average memory size.
-     *
+     * Add an entry to the cache. If a weigher is specified, it is used,
+     * otherwise the average memory size is used.
+     * 
      * @param key the key (may not be null)
      * @param value the value (may not be null)
      */
@@ -1519,21 +1521,55 @@ public class CacheLIRS<K, V> implements
             return this;
         }
 
+        /**
+         * Set the weigher which is used if memory usage of an entry is not
+         * explicitly set (when adding entries).
+         * 
+         * @param weigher the weigher
+         * @return this
+         */
         public Builder<K, V> weigher(Weigher<K, V> weigher) {
             this.weigher = weigher;
             return this;
         }
 
+        /**
+         * Set the total maximum weight. If the cache is heavier, then entries
+         * are evicted.
+         * 
+         * @param maxWeight the maximum weight
+         * @return this
+         */
         public Builder<K, V> maximumWeight(long maxWeight) {
             this.maxWeight = maxWeight;
             return this;
         }
 
+        /**
+         * Set the average weight of an entry. This is used, together with the
+         * maximum weight, to calculate the length of the internal array of the
+         * cache.
+         * 
+         * For higher performance, the weight should be set relatively low, at
+         * the cost of some space. To save space, the average weight should be
+         * set high, at the cost of some performance.
+         * 
+         * @param averageWeight the average weight
+         * @return this
+         */
         public Builder<K, V> averageWeight(int averageWeight) {
             this.averageWeight = averageWeight;
             return this;
         }
 
+        /**
+         * Set the maximum size (in number of entries). This is the same as
+         * setting the average weight of an entry to 1, and the maximum weight
+         * to the maximum size.
+         * 
+         * @param maxSize the maximum size
+         * @return this
+         */
         public Builder<K, V> maximumSize(long maxSize) {
             this.maxWeight = maxSize;
             this.averageWeight = 1;

Modified: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/cache/CacheStats.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/cache/CacheStats.java?rev=1753494&r1=1753493&r2=1753494&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/cache/CacheStats.java (original)
+++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/cache/CacheStats.java Wed Jul 20 12:25:56 2016
@@ -41,6 +41,14 @@ public class CacheStats extends Annotate
             new com.google.common.cache.CacheStats(
             0, 0, 0, 0, 0, 0);
 
+    /**
+     * Construct the cache stats object.
+     * 
+     * @param cache the cache
+     * @param name the name of the cache
+     * @param weigher the weigher used to estimate the current weight
+     * @param maxWeight the maximum weight
+     */
     @SuppressWarnings("unchecked")
     public CacheStats(Cache<?, ?> cache, String name, 
             Weigher<?, ?> weigher, long maxWeight) {
@@ -162,6 +170,7 @@ public class CacheStats extends Annotate
                 .toString();
     }
 
+    @Override
     public String getName() {
         return name;
     }