This is an automated email from the ASF dual-hosted git repository.
huxing pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-dubbo.git
The following commit(s) were added to refs/heads/master by this push:
new f3e8be7 Added javadoc for dubbo-filter module dubbo github issue 2884
(#2921)
f3e8be7 is described below
commit f3e8be7e95576c4d835caab02ded331d2b6d2c5f
Author: Imteyaz Ahmed Khan <[email protected]>
AuthorDate: Sat Dec 8 19:07:59 2018 +0530
Added javadoc for dubbo-filter module dubbo github issue 2884 (#2921)
---
.../main/java/org/apache/dubbo/cache/Cache.java | 19 +++++++-
.../java/org/apache/dubbo/cache/CacheFactory.java | 12 +++++-
.../org/apache/dubbo/cache/filter/CacheFilter.java | 50 +++++++++++++++++++++-
.../dubbo/cache/support/AbstractCacheFactory.java | 24 ++++++++++-
.../cache/support/expiring/ExpiringCache.java | 27 ++++++++++++
.../support/expiring/ExpiringCacheFactory.java | 16 ++++++-
.../apache/dubbo/cache/support/jcache/JCache.java | 9 +++-
.../dubbo/cache/support/jcache/JCacheFactory.java | 17 +++++++-
.../apache/dubbo/cache/support/lru/LruCache.java | 35 ++++++++++++++-
.../dubbo/cache/support/lru/LruCacheFactory.java | 12 +++++-
.../support/threadlocal/ThreadLocalCache.java | 33 +++++++++++++-
.../threadlocal/ThreadLocalCacheFactory.java | 12 +++++-
.../org/apache/dubbo/validation/Validation.java | 7 ++-
.../org/apache/dubbo/validation/Validator.java | 3 +-
.../dubbo/validation/filter/ValidationFilter.java | 37 +++++++++++++++-
.../validation/support/AbstractValidation.java | 7 ++-
.../support/jvalidation/JValidation.java | 9 +++-
.../validation/support/jvalidation/JValidator.java | 5 ++-
18 files changed, 314 insertions(+), 20 deletions(-)
diff --git
a/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/Cache.java
b/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/Cache.java
index 4ba84eb..fb2a329 100644
---
a/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/Cache.java
+++
b/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);
}
diff --git
a/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/CacheFactory.java
b/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/CacheFactory.java
index 2fabd94..77256bb 100644
---
a/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/CacheFactory.java
+++
b/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/CacheFactory.java
@@ -22,11 +22,21 @@ import org.apache.dubbo.common.extension.SPI;
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);
diff --git
a/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/filter/CacheFilter.java
b/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/filter/CacheFilter.java
index ee62826..4de9f5a 100644
---
a/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/filter/CacheFilter.java
+++
b/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/filter/CacheFilter.java
@@ -32,17 +32,60 @@ import org.apache.dubbo.rpc.RpcResult;
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)<dubbo:service cache="lru" />
+ * 2)<dubbo:service /> <dubbo:method name="method2"
cache="threadlocal" /> <dubbo:service/>
+ * 3)<dubbo:provider cache="expiring" />
+ * 4)<dubbo:consumer cache="jcache" />
+ *
+ *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 class CacheFilter implements Filter {
}
return invoker.invoke(invocation);
}
-
+
+ /**
+ * Cache value wrapper.
+ */
static class ValueWrapper implements Serializable{
private static final long serialVersionUID = -1777337318019193256L;
diff --git
a/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/AbstractCacheFactory.java
b/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/AbstractCacheFactory.java
index ad95e77..2522ce7 100644
---
a/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/AbstractCacheFactory.java
+++
b/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/AbstractCacheFactory.java
@@ -26,12 +26,29 @@ import java.util.concurrent.ConcurrentHashMap;
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 abstract class AbstractCacheFactory implements
CacheFactory {
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);
}
diff --git
a/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/expiring/ExpiringCache.java
b/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/expiring/ExpiringCache.java
index 9fd61f5..9295718 100644
---
a/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/expiring/ExpiringCache.java
+++
b/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/expiring/ExpiringCache.java
@@ -24,6 +24,22 @@ import java.util.Map;
/**
* 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) <dubbo:service cache="expiring" cache.seconds="60"
cache.interval="10"/>
+ * 2) <dubbo:consumer cache="expiring" />
+ * </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 class ExpiringCache implements Cache {
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);
diff --git
a/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/expiring/ExpiringCacheFactory.java
b/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/expiring/ExpiringCacheFactory.java
index 381a04e..5259d74 100644
---
a/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/expiring/ExpiringCacheFactory.java
+++
b/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.Cache;
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);
diff --git
a/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/jcache/JCache.java
b/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/jcache/JCache.java
index 2a28204..92e1642 100644
---
a/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/jcache/JCache.java
+++
b/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/jcache/JCache.java
@@ -30,7 +30,14 @@ import javax.cache.spi.CachingProvider;
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 {
diff --git
a/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/jcache/JCacheFactory.java
b/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/jcache/JCacheFactory.java
index bd1e9d5..c4d713f 100644
---
a/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/jcache/JCacheFactory.java
+++
b/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.Cache;
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);
diff --git
a/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/lru/LruCache.java
b/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/lru/LruCache.java
index 11a00ac..1d74580 100644
---
a/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/lru/LruCache.java
+++
b/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/lru/LruCache.java
@@ -23,22 +23,55 @@ import org.apache.dubbo.common.utils.LRUCache;
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) <dubbo:service cache="lru" cache.size="5000"/>
+ * 2) <dubbo:consumer cache="lru" />
+ * </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);
diff --git
a/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/lru/LruCacheFactory.java
b/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/lru/LruCacheFactory.java
index 775cdd0..cda2129 100644
---
a/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/lru/LruCacheFactory.java
+++
b/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/lru/LruCacheFactory.java
@@ -21,10 +21,20 @@ import org.apache.dubbo.cache.support.AbstractCacheFactory;
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);
diff --git
a/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/threadlocal/ThreadLocalCache.java
b/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/threadlocal/ThreadLocalCache.java
index 4b557be..0f35ed3 100644
---
a/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/threadlocal/ThreadLocalCache.java
+++
b/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/threadlocal/ThreadLocalCache.java
@@ -23,12 +23,33 @@ import java.util.HashMap;
import java.util.Map;
/**
- * ThreadLocalCache
+ * 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>threadlocal</b>, dubbo initialize the instance of this class
using {@link ThreadLocalCacheFactory} to store method's returns value
+ * to server from store without making method call.
+ * <pre>
+ * e.g. <dubbo:service cache="threadlocal" />
+ * </pre>
+ * <pre>
+ * As this ThreadLocalCache stores key-value in memory without any expiry or
delete support per thread wise, if number threads and number of key-value are
high then jvm should be
+ * configured with appropriate memory.
+ * </pre>
+ *
+ * @see org.apache.dubbo.cache.support.AbstractCacheFactory
+ * @see org.apache.dubbo.cache.filter.CacheFilter
+ * @see Cache
*/
public class ThreadLocalCache implements Cache {
+ /**
+ * Thread local variable to store cached data.
+ */
private final ThreadLocal<Map<Object, Object>> store;
+ /**
+ * Taken URL as an argument to create an instance of ThreadLocalCache. In
this version of implementation constructor
+ * argument is not getting used in the scope of this class.
+ * @param url
+ */
public ThreadLocalCache(URL url) {
this.store = new ThreadLocal<Map<Object, Object>>() {
@Override
@@ -38,11 +59,21 @@ public class ThreadLocalCache implements Cache {
};
}
+ /**
+ * 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.get().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().get(key);
diff --git
a/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/threadlocal/ThreadLocalCacheFactory.java
b/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/threadlocal/ThreadLocalCacheFactory.java
index e456f26..bde16f6 100644
---
a/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/threadlocal/ThreadLocalCacheFactory.java
+++
b/dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/threadlocal/ThreadLocalCacheFactory.java
@@ -21,10 +21,20 @@ import org.apache.dubbo.cache.support.AbstractCacheFactory;
import org.apache.dubbo.common.URL;
/**
- * ThreadLocalCacheFactory
+ * Implement {@link org.apache.dubbo.cache.CacheFactory} by extending {@link
AbstractCacheFactory} and provide
+ * instance of new {@link ThreadLocalCache}. Note about this class is, each
thread does not have a local copy of factory.
+ *
+ * @see AbstractCacheFactory
+ * @see ThreadLocalCache
+ * @see Cache
*/
public class ThreadLocalCacheFactory extends AbstractCacheFactory {
+ /**
+ * Takes url as an method argument and return new instance of cache store
implemented by ThreadLocalCache.
+ * @param url url of the method
+ * @return ThreadLocalCache instance of cache
+ */
@Override
protected Cache createCache(URL url) {
return new ThreadLocalCache(url);
diff --git
a/dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/Validation.java
b/dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/Validation.java
index 1cf1022..d6775f0 100644
---
a/dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/Validation.java
+++
b/dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/Validation.java
@@ -22,11 +22,16 @@ import org.apache.dubbo.common.extension.Adaptive;
import org.apache.dubbo.common.extension.SPI;
/**
- * Validation
+ * Instance of Validation interface provide instance of {@link Validator}
based on the value of <b>validation</b> attribute.
*/
@SPI("jvalidation")
public interface Validation {
+ /**
+ * Return the instance of {@link Validator} for a given url.
+ * @param url Invocation url
+ * @return Instance of {@link Validator}
+ */
@Adaptive(Constants.VALIDATION_KEY)
Validator getValidator(URL url);
diff --git
a/dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/Validator.java
b/dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/Validator.java
index cea93d8..b1565ba 100644
---
a/dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/Validator.java
+++
b/dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/Validator.java
@@ -17,7 +17,8 @@
package org.apache.dubbo.validation;
/**
- * Validator
+ * Instance of validator class is an extension to perform validation on method
input parameter before the actual method invocation.
+ *
*/
public interface Validator {
diff --git
a/dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/filter/ValidationFilter.java
b/dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/filter/ValidationFilter.java
index e229080..2af761a 100644
---
a/dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/filter/ValidationFilter.java
+++
b/dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/filter/ValidationFilter.java
@@ -29,17 +29,52 @@ import org.apache.dubbo.validation.Validation;
import org.apache.dubbo.validation.Validator;
/**
- * ValidationFilter
+ * ValidationFilter invoke the validation by finding the right {@link
Validator} instance based on the
+ * configured <b>validation</b> attribute value of invoker url before the
actual method invocation.
+ *
+ * <pre>
+ * e.g. <dubbo:method name="save" validation="jvalidation" />
+ * In the above configuration a validation has been configured of type
jvalidation. On invocation of method <b>save</b>
+ * dubbo will invoke {@link
org.apache.dubbo.validation.support.jvalidation.JValidator}
+ * </pre>
+ *
+ * To add a new type of validation
+ * <pre>
+ * e.g. <dubbo:method name="save" validation="special" />
+ * where "special" is representing a validator for special character.
+ * </pre>
+ *
+ * developer needs to do
+ * <br/>
+ * 1)Implement a SpecialValidation.java class (package name xxx.yyy.zzz)
either by implementing {@link Validation} or extending {@link
org.apache.dubbo.validation.support.AbstractValidation} <br/>
+ * 2)Implement a SpecialValidator.java class (package name xxx.yyy.zzz) <br/>
+ * 3)Add an entry <b>special</b>=<b>xxx.yyy.zzz.SpecialValidation</b> under
<b>META-INF folders org.apache.dubbo.validation.Validation file</b>.
+ *
+ * @see Validation
+ * @see Validator
+ * @see Filter
+ * @see org.apache.dubbo.validation.support.AbstractValidation
*/
@Activate(group = {Constants.CONSUMER, Constants.PROVIDER}, value =
Constants.VALIDATION_KEY, order = 10000)
public class ValidationFilter implements Filter {
private Validation validation;
+ /**
+ * Sets the validation instance for ValidationFilter
+ * @param validation Validation instance injected by dubbo framework based
on "validation" attribute value.
+ */
public void setValidation(Validation validation) {
this.validation = validation;
}
+ /**
+ * Perform the validation of before invoking the actual method based on
<b>validation</b> attribute value.
+ * @param invoker service
+ * @param invocation invocation.
+ * @return Method invocation result
+ * @throws RpcException Throws RpcException if validation failed or any
other runtime exception occurred.
+ */
@Override
public Result invoke(Invoker<?> invoker, Invocation invocation) throws
RpcException {
if (validation != null && !invocation.getMethodName().startsWith("$")
diff --git
a/dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/support/AbstractValidation.java
b/dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/support/AbstractValidation.java
index 0f1f629..17f6646 100644
---
a/dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/support/AbstractValidation.java
+++
b/dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/support/AbstractValidation.java
@@ -24,7 +24,12 @@ import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ConcurrentMap;
/**
- * AbstractValidation
+ * AbstractValidation is abstract class for Validation interface. It helps low
level Validation implementation classes
+ * by performing common task e.g. key formation, storing instance of
validation class to avoid creation of unnecessary
+ * copy of validation instance and faster execution.
+ *
+ * @see Validation
+ * @see Validator
*/
public abstract class AbstractValidation implements Validation {
diff --git
a/dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/support/jvalidation/JValidation.java
b/dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/support/jvalidation/JValidation.java
index 8e04ba5..e085989 100644
---
a/dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/support/jvalidation/JValidation.java
+++
b/dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/support/jvalidation/JValidation.java
@@ -21,10 +21,17 @@ import org.apache.dubbo.validation.Validator;
import org.apache.dubbo.validation.support.AbstractValidation;
/**
- * JValidation
+ * Creates a new instance of {@link Validator} using input argument url.
+ * @see AbstractValidation
+ * @see Validator
*/
public class JValidation extends AbstractValidation {
+ /**
+ * Return new instance of {@link JValidator}
+ * @param url Valid URL instance
+ * @return Instance of JValidator
+ */
@Override
protected Validator createValidator(URL url) {
return new JValidator(url);
diff --git
a/dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/support/jvalidation/JValidator.java
b/dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/support/jvalidation/JValidator.java
index a7c8afe..9feccb2 100644
---
a/dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/support/jvalidation/JValidator.java
+++
b/dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/support/jvalidation/JValidator.java
@@ -68,7 +68,10 @@ import java.util.Set;
import java.util.concurrent.ConcurrentHashMap;
/**
- * JValidator
+ * Implementation of JValidation. JValidation is invoked if configuration
validation attribute value is 'jvalidation'.
+ * <pre>
+ * e.g. <dubbo:method name="save" validation="jvalidation" />
+ * </pre>
*/
public class JValidator implements Validator {
