Added javadoc for dubbo-filter module dubbo github issue 2884 (apache#2921)

Author: khanimteyaz

dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/Cache.java

@@ -17,12 +17,27 @@
 package org.apache.dubbo.cache;
 
 /**
- * Cache
+ * Cache interface to support storing and retrieval of value against a lookup key. It has two operation <b>get</b> and <b>put</b>.
+ * <li><b>put</b>-Storing value against a key.</li>
+ * <li><b>get</b>-Retrival of object.</li>
+ * @see org.apache.dubbo.cache.support.lru.LruCache
+ * @see org.apache.dubbo.cache.support.jcache.JCache
+ * @see org.apache.dubbo.cache.support.expiring.ExpiringCache
+ * @see org.apache.dubbo.cache.support.threadlocal.ThreadLocalCache
  */
 public interface Cache {
-
+    /**
+     * API to store value against a key
+     * @param key  Unique identifier for the object being store.
+     * @param value Value getting store
+     */
     void put(Object key, Object value);
 
+    /**
+     * API to return stored value using a key.
+     * @param key Unique identifier for cache lookup
+     * @return Return stored object against key
+     */
     Object get(Object key);
 
 }

dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/CacheFactory.java

@@ -22,11 +22,21 @@
 import org.apache.dubbo.rpc.Invocation;
 
 /**
- * CacheFactory
+ * Interface needs to be implemented by all the cache store provider.Along with implementing <b>CacheFactory</b> interface
+ * entry needs to be added in org.apache.dubbo.cache.CacheFactory file in a classpath META-INF sub directories.
+ *
+ * @see Cache
  */
 @SPI("lru")
 public interface CacheFactory {
 
+    /**
+     * CacheFactory implementation class needs to implement this return underlying cache instance for method against
+     * url and invocation.
+     * @param url
+     * @param invocation
+     * @return Instance of Cache containing cached value against method url and invocation.
+     */
     @Adaptive("cache")
     Cache getCache(URL url, Invocation invocation);
 

dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/filter/CacheFilter.java

@@ -32,17 +32,60 @@
 import java.io.Serializable;
 
 /**
- * CacheFilter
+ * CacheFilter is a core component of dubbo.Enabling <b>cache</b> key of service,method,consumer or provider dubbo will cache method return value.
+ * Along with cache key we need to configure cache type. Dubbo default implemented cache types are
+ * <li>lur</li>
+ * <li>threadlocal</li>
+ * <li>jcache</li>
+ * <li>expiring</li>
+ *
+ * <pre>
+ *   e.g. 1)&lt;dubbo:service cache="lru" /&gt;
+ *        2)&lt;dubbo:service /&gt; &lt;dubbo:method name="method2" cache="threadlocal" /&gt; &lt;dubbo:service/&gt;
+ *        3)&lt;dubbo:provider cache="expiring" /&gt;
+ *        4)&lt;dubbo:consumer cache="jcache" /&gt;
+ *
+ *If cache type is defined in method level then method level type will get precedence. According to above provided
+ *example, if service has two method, method1 and method2, method2 will have cache type as <b>threadlocal</b> where others will
+ *be backed by <b>lru</b>
+ *</pre>
+ *
+ * @see org.apache.dubbo.rpc.Filter
+ * @see org.apache.dubbo.cache.support.lru.LruCacheFactory
+ * @see org.apache.dubbo.cache.support.lru.LruCache
+ * @see org.apache.dubbo.cache.support.jcache.JCacheFactory
+ * @see org.apache.dubbo.cache.support.jcache.JCache
+ * @see org.apache.dubbo.cache.support.threadlocal.ThreadLocalCacheFactory
+ * @see org.apache.dubbo.cache.support.threadlocal.ThreadLocalCache
+ * @see org.apache.dubbo.cache.support.expiring.ExpiringCacheFactory
+ * @see org.apache.dubbo.cache.support.expiring.ExpiringCache
+ *
  */
 @Activate(group = {Constants.CONSUMER, Constants.PROVIDER}, value = Constants.CACHE_KEY)
 public class CacheFilter implements Filter {
 
     private CacheFactory cacheFactory;
 
+    /**
+     * Dubbo will populate and set the cache factory instance based on service/method/consumer/provider configured
+     * cache attribute value. Dubbo will search for the class name implementing configured <b>cache</b> in file org.apache.dubbo.cache.CacheFactory
+     * under META-INF sub folders.
+     *
+     * @param cacheFactory instance of CacheFactory based on <b>cache</b> type
+     */
     public void setCacheFactory(CacheFactory cacheFactory) {
         this.cacheFactory = cacheFactory;
     }
 
+    /**
+     * If cache is configured, dubbo will invoke method on each method call. If cache value is returned by cache store
+     * then it will return otherwise call the remote method and return value. If remote method's return valeu has error
+     * then it will not cache the value.
+     * @param invoker    service
+     * @param invocation invocation.
+     * @return Cache returned value if found by the underlying cache store. If cache miss it will call target method.
+     * @throws RpcException
+     */
     @Override
     public Result invoke(Invoker<?> invoker, Invocation invocation) throws RpcException {
         if (cacheFactory != null && ConfigUtils.isNotEmpty(invoker.getUrl().getMethodParameter(invocation.getMethodName(), Constants.CACHE_KEY))) {
@@ -66,7 +109,10 @@ public Result invoke(Invoker<?> invoker, Invocation invocation) throws RpcExcept
         }
         return invoker.invoke(invocation);
     }
-    
+
+    /**
+     * Cache value wrapper.
+     */
     static class ValueWrapper implements Serializable{
 
         private static final long serialVersionUID = -1777337318019193256L;

dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/AbstractCacheFactory.java

@@ -26,12 +26,29 @@
 import java.util.concurrent.ConcurrentMap;
 
 /**
- * AbstractCacheFactory
+ * AbstractCacheFactory is a default implementation of {@link CacheFactory}. It abstract out the key formation from URL along with
+ * invocation method. It initially check if the value for key already present in own local in-memory store then it won't check underlying storage cache {@link Cache}.
+ * Internally it used {@link ConcurrentHashMap} to store do level-1 caching.
+ *
+ * @see CacheFactory
+ * @see org.apache.dubbo.cache.support.jcache.JCacheFactory
+ * @see org.apache.dubbo.cache.support.lru.LruCacheFactory
+ * @see org.apache.dubbo.cache.support.threadlocal.ThreadLocalCacheFactory
+ * @see org.apache.dubbo.cache.support.expiring.ExpiringCacheFactory
  */
 public abstract class AbstractCacheFactory implements CacheFactory {
 
+    /**
+     * This is used to store factory level-1 cached data.
+     */
     private final ConcurrentMap<String, Cache> caches = new ConcurrentHashMap<String, Cache>();
 
+    /**
+     *  Takes URL and invocation instance and return cache instance for a given url.
+     * @param url url of the method
+     * @param invocation invocation context.
+     * @return Instance of cache store used as storage for caching return values.
+     */
     @Override
     public Cache getCache(URL url, Invocation invocation) {
         url = url.addParameter(Constants.METHOD_KEY, invocation.getMethodName());
@@ -44,6 +61,11 @@ public Cache getCache(URL url, Invocation invocation) {
         return cache;
     }
 
+    /**
+     * Takes url as an method argument and return new instance of cache store implemented by AbstractCacheFactory subclass.
+     * @param url url of the method
+     * @return Create and return new instance of cache store used as storage for caching return values.
+     */
     protected abstract Cache createCache(URL url);
 
 }

dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/expiring/ExpiringCache.java

@@ -24,6 +24,22 @@
 /**
  * ExpiringCache - With the characteristic of expiration time.
  */
+
+/**
+ * This class store the cache value with the characteristic of expiration time. If a service,method,consumer or provided is configured with key <b>cache</b>
+ * with value <b>expiring</b>, dubbo initialize the instance of this class using {@link ExpiringCacheFactory} to store method's returns value
+ * to server from store without making method call.
+ * <pre>
+ *     e.g. 1) &lt;dubbo:service cache="expiring" cache.seconds="60" cache.interval="10"/&gt;
+ *          2) &lt;dubbo:consumer cache="expiring" /&gt;
+ * </pre>
+ * <li>It used constructor argument url instance <b>cache.seconds</b> value to decide time to live of cached object.Default value of it is 180 second.</li>
+ * <li>It used constructor argument url instance <b>cache.interval</b> value for cache value expiration interval.Default value of this is 4 second</li>
+ * @see Cache
+ * @see ExpiringCacheFactory
+ * @see org.apache.dubbo.cache.support.AbstractCacheFactory
+ * @see org.apache.dubbo.cache.filter.CacheFilter
+ */
 public class ExpiringCache implements Cache {
     private final Map<Object, Object> store;
 
@@ -37,11 +53,22 @@ public ExpiringCache(URL url) {
         this.store = expiringMap;
     }
 
+    /**
+     * API to store value against a key in the calling thread scope.
+     * @param key  Unique identifier for the object being store.
+     * @param value Value getting store
+     */
     @Override
     public void put(Object key, Object value) {
         store.put(key, value);
     }
 
+    /**
+     * API to return stored value using a key against the calling thread specific store.
+     * @param key Unique identifier for cache lookup
+     * @return Return stored object against key
+     */
+
     @Override
     public Object get(Object key) {
         return store.get(key);

dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/expiring/ExpiringCacheFactory.java

@@ -20,11 +20,23 @@
 import org.apache.dubbo.cache.support.AbstractCacheFactory;
 import org.apache.dubbo.common.URL;
 
+
 /**
- * ExpiringCacheFactory
+ * Implement {@link org.apache.dubbo.cache.CacheFactory} by extending {@link AbstractCacheFactory} and provide
+ * instance of new {@link ExpiringCache}.
+ *
+ * @see AbstractCacheFactory
+ * @see ExpiringCache
+ * @see Cache
  */
+
 public class ExpiringCacheFactory extends AbstractCacheFactory {
-    
+
+    /**
+     * Takes url as an method argument and return new instance of cache store implemented by JCache.
+     * @param url url of the method
+     * @return ExpiringCache instance of cache
+     */
     @Override
     protected Cache createCache(URL url) {
         return new ExpiringCache(url);

dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/jcache/JCache.java

@@ -30,7 +30,14 @@
 import java.util.concurrent.TimeUnit;
 
 /**
- * JCache
+ * This class store the cache value per thread. If a service,method,consumer or provided is configured with key <b>cache</b>
+ * with value <b>jcache</b>, dubbo initialize the instance of this class using {@link JCacheFactory} to store method's returns value
+ * to server from store without making method call.
+ *
+ * @see Cache
+ * @see JCacheFactory
+ * @see org.apache.dubbo.cache.support.AbstractCacheFactory
+ * @see org.apache.dubbo.cache.filter.CacheFilter
  */
 public class JCache implements org.apache.dubbo.cache.Cache {
 

dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/jcache/JCacheFactory.java

@@ -20,11 +20,26 @@
 import org.apache.dubbo.cache.support.AbstractCacheFactory;
 import org.apache.dubbo.common.URL;
 
+import javax.cache.spi.CachingProvider;
+
 /**
- * JCacheFactory
+ * JCacheFactory is factory class to provide instance of javax spi cache.Implement {@link org.apache.dubbo.cache.CacheFactory} by
+ * extending {@link AbstractCacheFactory} and provide
+ * @see AbstractCacheFactory
+ * @see JCache
+ * @see org.apache.dubbo.cache.filter.CacheFilter
+ * @see Cache
+ * @see CachingProvider
+ * @see javax.cache.Cache
+ * @see javax.cache.CacheManager
  */
 public class JCacheFactory extends AbstractCacheFactory {
 
+    /**
+     * Takes url as an method argument and return new instance of cache store implemented by JCache.
+     * @param url url of the method
+     * @return JCache instance of cache
+     */
     @Override
     protected Cache createCache(URL url) {
         return new JCache(url);

dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/lru/LruCache.java

@@ -23,22 +23,55 @@
 import java.util.Map;
 
 /**
- * LruCache
+ * This class store the cache value per thread. If a service,method,consumer or provided is configured with key <b>cache</b>
+ * with value <b>lru</b>, dubbo initialize the instance of this class using {@link LruCacheFactory} to store method's returns value
+ * to server from store without making method call.
+ * <pre>
+ *     e.g. 1) &lt;dubbo:service cache="lru" cache.size="5000"/&gt;
+ *          2) &lt;dubbo:consumer cache="lru" /&gt;
+ * </pre>
+ * <pre>
+ * LruCache uses url's <b>cache.size</b> value for its max store size, if nothing is provided then
+ * default value will be 1000
+ * </pre>
+ *
+ * @see Cache
+ * @see LruCacheFactory
+ * @see org.apache.dubbo.cache.support.AbstractCacheFactory
+ * @see org.apache.dubbo.cache.filter.CacheFilter
  */
 public class LruCache implements Cache {
 
+    /**
+     * This is used to store cache records
+     */
     private final Map<Object, Object> store;
 
+    /**
+     * Initialize LruCache, it uses constructor argument <b>cache.size</b> value as its storage max size.
+     *  If nothing is provided then it will use 1000 as default value.
+     * @param url A valid URL instance
+     */
     public LruCache(URL url) {
         final int max = url.getParameter("cache.size", 1000);
         this.store = new LRUCache<Object, Object>(max);
     }
 
+    /**
+     * API to store value against a key in the calling thread scope.
+     * @param key  Unique identifier for the object being store.
+     * @param value Value getting store
+     */
     @Override
     public void put(Object key, Object value) {
         store.put(key, value);
     }
 
+    /**
+     * API to return stored value using a key against the calling thread specific store.
+     * @param key Unique identifier for cache lookup
+     * @return Return stored object against key
+     */
     @Override
     public Object get(Object key) {
         return store.get(key);

dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/lru/LruCacheFactory.java

@@ -21,10 +21,20 @@
 import org.apache.dubbo.common.URL;
 
 /**
- * LruCacheFactory
+ * Implement {@link org.apache.dubbo.cache.CacheFactory} by extending {@link AbstractCacheFactory} and provide
+ * instance of new {@link LruCache}.
+ *
+ * @see AbstractCacheFactory
+ * @see LruCache
+ * @see Cache
  */
 public class LruCacheFactory extends AbstractCacheFactory {
 
+    /**
+     * Takes url as an method argument and return new instance of cache store implemented by LruCache.
+     * @param url url of the method
+     * @return ThreadLocalCache instance of cache
+     */
     @Override
     protected Cache createCache(URL url) {
         return new LruCache(url);