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 4ba84eb31e6..fb2a329fc15 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 get and put. + *
  • put-Storing value against a key.
    • + *
  • get-Retrival of object.
    • + * @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 2fabd94a5f3..77256bb5ee5 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.rpc.Invocation; /** - * CacheFactory + * Interface needs to be implemented by all the cache store provider.Along with implementing CacheFactory 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 ee6282659aa..4de9f5a170c 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 java.io.Serializable; /** - * CacheFilter + * CacheFilter is a core component of dubbo.Enabling cache 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 + *
  • lur
    • + *
  • threadlocal
    • + *
  • jcache
    • + *
  • expiring
    • + * + * 
    + *   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 threadlocal where others will
+ *be backed by lru
+ *
    + * + * @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 cache in file org.apache.dubbo.cache.CacheFactory + * under META-INF sub folders. + * + * @param cacheFactory instance of CacheFactory based on cache 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; 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 ad95e770e0d..2522ce775a8 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.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 caches = new ConcurrentHashMap(); + /** + * 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); } 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 9fd61f59504..9295718dfc7 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 @@ /** * 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 cache + * with value expiring, dubbo initialize the instance of this class using {@link ExpiringCacheFactory} to store method's returns value + * to server from store without making method call. + * 
    + *     e.g. 1) <dubbo:service cache="expiring" cache.seconds="60" cache.interval="10"/>
+ *          2) <dubbo:consumer cache="expiring" />
+ *
    + *
  • It used constructor argument url instance cache.seconds value to decide time to live of cached object.Default value of it is 180 second.
    • + *
  • It used constructor argument url instance cache.interval value for cache value expiration interval.Default value of this is 4 second
    • + * @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 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); 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 381a04ee243..5259d74b6eb 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.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 2a28204573f..92e16423e3d 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 java.util.concurrent.TimeUnit; /** - * JCache + * This class store the cache value per thread. If a service,method,consumer or provided is configured with key cache + * with value jcache, 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 bd1e9d5c612..c4d713f0b17 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.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 11a00ac60c9..1d745804d83 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 java.util.Map; /** - * LruCache + * This class store the cache value per thread. If a service,method,consumer or provided is configured with key cache + * with value lru, dubbo initialize the instance of this class using {@link LruCacheFactory} to store method's returns value + * to server from store without making method call. + * 
    + *     e.g. 1) <dubbo:service cache="lru" cache.size="5000"/>
+ *          2) <dubbo:consumer cache="lru" />
+ *
    + * 
    + * LruCache uses url's cache.size value for its max store size, if nothing is provided then
+ * default value will be 1000
+ *
    + * + * @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 store; + /** + * Initialize LruCache, it uses constructor argument cache.size 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(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 775cdd0237f..cda21292e8f 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.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 4b557bebbbd..0f35ed3315e 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.Map; /** - * ThreadLocalCache + * This class store the cache value per thread. If a service,method,consumer or provided is configured with key cache + * with value threadlocal, dubbo initialize the instance of this class using {@link ThreadLocalCacheFactory} to store method's returns value + * to server from store without making method call. + * 
    + *      e.g. <dubbo:service cache="threadlocal" />
+ *
    + * 
    + * 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.
+ *
    + * + * @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> 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>() { @Override @@ -38,11 +59,21 @@ protected Map initialValue() { }; } + /** + * 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 e456f2696b7..bde16f63bd6 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.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 1cf10225fb0..d6775f0e270 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.SPI; /** - * Validation + * Instance of Validation interface provide instance of {@link Validator} based on the value of validation 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 cea93d85fec..b1565ba4b68 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 e22908067ed..2af761a0958 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.Validator; /** - * ValidationFilter + * ValidationFilter invoke the validation by finding the right {@link Validator} instance based on the + * configured validation attribute value of invoker url before the actual method invocation. + * + * 
    + *     e.g. <dubbo:method name="save" validation="jvalidation" />
+ *     In the above configuration a validation has been configured of type jvalidation. On invocation of method save
+ *     dubbo will invoke {@link org.apache.dubbo.validation.support.jvalidation.JValidator}
+ *
    + * + * To add a new type of validation + * 
    + *     e.g. <dubbo:method name="save" validation="special" />
+ *     where "special" is representing a validator for special character.
+ *
    + * + * developer needs to do + *
    + * 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}
    + * 2)Implement a SpecialValidator.java class (package name xxx.yyy.zzz)
    + * 3)Add an entry special=xxx.yyy.zzz.SpecialValidation under META-INF folders org.apache.dubbo.validation.Validation file. + * + * @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 validation 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 0f1f629512b..17f6646f526 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.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 8e04ba5f225..e0859897f1e 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.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 a7c8afe3f29..9feccb22e72 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.concurrent.ConcurrentHashMap; /** - * JValidator + * Implementation of JValidation. JValidation is invoked if configuration validation attribute value is 'jvalidation'. + * 
    + *     e.g. <dubbo:method name="save" validation="jvalidation" />
+ *
    */ public class JValidator implements Validator {