natas_hw
/
dubbo
0
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

This commit is contained in:
Imteyaz Ahmed Khan 2018-12-08 19:07:59 +05:30 committed by Huxing Zhang
parent e16e78ff18
commit f3e8be7e95
18 changed files with 314 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/Cache.java vendored
View File

@ -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);
}

12
dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/CacheFactory.java vendored
View File

@ -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);

50
dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/filter/CacheFilter.java vendored
View File

@ -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)&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 class CacheFilter implements Filter {
}
return invoker.invoke(invocation);
}
/**
* Cache value wrapper.
*/
static class ValueWrapper implements Serializable{
private static final long serialVersionUID = -1777337318019193256L;

24
dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/AbstractCacheFactory.java vendored
View File

@ -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);
}

27
dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/expiring/ExpiringCache.java vendored
View File

@ -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) &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 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);

16
dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/expiring/ExpiringCacheFactory.java vendored
View File

@ -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);

9
dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/jcache/JCache.java vendored
View File

@ -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 {

17
dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/jcache/JCacheFactory.java vendored
View File

@ -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);

35
dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/lru/LruCache.java vendored
View File

@ -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) &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);

12
dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/lru/LruCacheFactory.java vendored
View File

@ -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);

33
dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/threadlocal/ThreadLocalCache.java vendored
View File

@ -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. &lt;dubbo:service cache="threadlocal" /&gt;
* </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);

12
dubbo-filter/dubbo-filter-cache/src/main/java/org/apache/dubbo/cache/support/threadlocal/ThreadLocalCacheFactory.java vendored
View File

@ -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);

7
dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/Validation.java
View File

@ -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);

3
dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/Validator.java
View File

@ -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 {

37
dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/filter/ValidationFilter.java
View File

@ -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. &lt;dubbo:method name="save" validation="jvalidation" /&gt;
* 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. &lt;dubbo:method name="save" validation="special" /&gt;
* 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("$")

7
dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/support/AbstractValidation.java
View File

@ -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 {

9
dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/support/jvalidation/JValidation.java
View File

@ -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);

5
dubbo-filter/dubbo-filter-validation/src/main/java/org/apache/dubbo/validation/support/jvalidation/JValidator.java
View File

@ -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. &lt;dubbo:method name="save" validation="jvalidation" /&gt;
* </pre>
*/
public class JValidator implements Validator {