added dubbo-rpc-api filter documentation for issue no apache#2935

dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/Filter.java

@@ -19,7 +19,26 @@
 import org.apache.dubbo.common.extension.SPI;
 
 /**
+ * Extension for intercepting the invocation for both service provider and consumer, furthermore, most of
+ * functions in dubbo are implemented base on the same mechanism. Since every time when remote method is
+ * invoked, the filter extensions will be executed too, the corresponding penalty should be considered before
+ * more filters are added.
+ * <pre>
+ *  They way filter work from sequence point of view is
+ *    <b>
+ *    ...code before filter ...
+ *          invoker.invoke(invocation) //filter work in a filter implementation class
+ *          ...code after filter ...
+ *    </b>
+ *    Caching is implemented in dubbo using filter approach. If cache is configured for invocation then before
+ *    remote call configured caching type's (e.g. Thread Local, JCache etc) implementation invoke method gets called.
+ * </pre>
  * Filter. (SPI, Singleton, ThreadSafe)
+ *
+ * @see org.apache.dubbo.rpc.filter.GenericFilter
+ * @see org.apache.dubbo.rpc.filter.EchoFilter
+ * @see org.apache.dubbo.rpc.filter.TokenFilter
+ * @see org.apache.dubbo.rpc.filter.TpsLimitFilter
  */
 @SPI
 public interface Filter {

dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/ActiveLimitFilter.java

@@ -27,7 +27,16 @@
 import org.apache.dubbo.rpc.RpcStatus;
 
 /**
- * LimitInvokerFilter
+ * ActiveLimitFilter restrict the concurrent client invocation for a service or service's method from client side.
+ * To use active limit filter, configured url with <b>actives</b> and provide valid >0 integer value.
+ * <pre>
+ *     e.g. <dubbo:reference id="demoService" check="false" interface="org.apache.dubbo.demo.DemoService" "actives"="2"/>
+ *      In the above example maximum 2 concurrent invocation is allowed.
+ *      If there are more than configured (in this example 2) is trying to invoke remote method, then rest of invocation
+ *      will wait for configured timeout(default is 0 second) before invocation gets kill by dubbo.
+ * </pre>
+ *
+ * @see Filter
  */
 @Activate(group = Constants.CONSUMER, value = Constants.ACTIVES_KEY)
 public class ActiveLimitFilter implements Filter {

dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/ClassLoaderFilter.java

@@ -25,7 +25,7 @@
 import org.apache.dubbo.rpc.RpcException;
 
 /**
- * ClassLoaderInvokerFilter
+ * Set the current execution thread class loader to service interface's class loader.
  */
 @Activate(group = Constants.PROVIDER, order = -30000)
 public class ClassLoaderFilter implements Filter {

dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/CompatibleFilter.java

@@ -32,7 +32,18 @@
 import java.lang.reflect.Type;
 
 /**
- * CompatibleFilter
+ * CompatibleFilter make the remote method's return value compatible to invoker's version of object.
+ * To make return object compatible it does
+ * <pre>
+ *    1)If the url contain serialization key of type <b>json</b> or <b>fastjson</b> then transform
+ *    the return value to instance of {@link java.util.Map}
+ *    2)If the return value is not a instance of invoked method's return type available at
+ *    local jvm then POJO conversion.
+ *    3)If return value is other than above return value as it is.
+ * </pre>
+ *
+ * @see Filter
+ *
  */
 public class CompatibleFilter implements Filter {
 
@@ -51,9 +62,11 @@ public Result invoke(Invoker<?> invoker, Invocation invocation) throws RpcExcept
                     String serialization = invoker.getUrl().getParameter(Constants.SERIALIZATION_KEY);
                     if ("json".equals(serialization)
                             || "fastjson".equals(serialization)) {
+                        // If the serialization key is json or fastjson
                         Type gtype = method.getGenericReturnType();
                         newValue = PojoUtils.realize(value, type, gtype);
                     } else if (!type.isInstance(value)) {
+                        //if local service interface's method's return type is not instance of return value
                         newValue = PojoUtils.isPojo(type)
                                 ? PojoUtils.realize(value, type)
                                 : CompatibleTypeUtils.compatibleTypeConvert(value, type);

dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/ConsumerContextFilter.java

@@ -28,7 +28,12 @@
 import org.apache.dubbo.rpc.RpcInvocation;
 
 /**
- * ConsumerContextInvokerFilter
+ * ConsumerContextFilter set current RpcContext with invoker,invocation, local host, remote host and port
+ * for consumer invoker.It does it to make the requires info available to execution thread's RpcContext.
+ *
+ * @see org.apache.dubbo.rpc.Filter
+ * @see org.apache.dubbo.rpc.PostProcessFilter
+ * @see RpcContext
  */
 @Activate(group = Constants.CONSUMER, order = -10000)
 public class ConsumerContextFilter extends AbstractPostProcessFilter {

dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/ContextFilter.java

@@ -30,7 +30,12 @@
 import java.util.Map;
 
 /**
- * ContextInvokerFilter
+ * ContextFilter set the provider RpcContext with invoker, invocation, local port it is using and host for
+ * current execution thread.
+ *
+ * @see java.io.File
+ * @see RpcContext
+ * @see org.apache.dubbo.rpc.PostProcessFilter
  */
 @Activate(group = Constants.PROVIDER, order = -10000)
 public class ContextFilter extends AbstractPostProcessFilter {

dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/DeprecatedFilter.java

@@ -30,7 +30,10 @@
 import java.util.Set;
 
 /**
- * DeprecatedInvokerFilter
+ * DeprecatedFilter logs error message if a invoked method has been marked as deprecated. To check whether a method
+ * is deprecated or not it looks for <b>deprecated</b> attribute value and consider it is deprecated it value is <b>true</b>
+ *
+ * @see Filter
  */
 @Activate(group = Constants.CONSUMER, value = Constants.DEPRECATED_KEY)
 public class DeprecatedFilter implements Filter {

dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/EchoFilter.java

@@ -26,7 +26,7 @@
 import org.apache.dubbo.rpc.RpcResult;
 
 /**
- * EchoInvokerFilter
+ * Dubbo provided default Echo echo service, which is available for all dubbo provider service interface.
  */
 @Activate(group = Constants.PROVIDER, order = -110000)
 public class EchoFilter implements Filter {

dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/ExecuteLimitFilter.java

@@ -29,7 +29,10 @@
 import java.util.concurrent.Semaphore;
 
 /**
- * ThreadLimitInvokerFilter
+ * The maximum parallel execution request count per method per service for the provider.If the max configured
+ * <b>executes</b> is set to 10 and if invoke request where it is already 10 then it will throws exception. It
+ * continue the same behaviour un till it is <10.
+ *
  */
 @Activate(group = Constants.PROVIDER, value = Constants.EXECUTES_KEY)
 public class ExecuteLimitFilter implements Filter {

dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/TokenFilter.java

@@ -29,7 +29,10 @@
 import java.util.Map;
 
 /**
- * TokenInvokerFilter
+ * Perform check whether given provider token is matching with remote token or not. If it does not match
+ * it will not allow to invoke remote method.
+ *
+ * @see Filter
  */
 @Activate(group = Constants.PROVIDER, value = Constants.TOKEN_KEY)
 public class TokenFilter implements Filter {

dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/TpsLimitFilter.java

@@ -28,8 +28,12 @@
 import org.apache.dubbo.rpc.filter.tps.TPSLimiter;
 
 /**
- * Limit TPS for either service or service's particular method
- */
+ * TpsLimitFilter limit the TPS (transaction per second) for all method of a service or a particular method.
+ * Service or method url can define <b>tps</b> or <b>tps.interval</b> to control this control.It use {@link DefaultTPSLimiter}
+ * as it limit checker. If a provider service method is configured with <b>tps</b>(optionally with <b>tps.interval</b>),then
+ * if invocation count exceed the configured <b>tps</b> value (default is -1 which means unlimited) then invocation will get
+ * RpcException.
+ * */
 @Activate(group = Constants.PROVIDER, value = Constants.TPS_LIMIT_RATE_KEY)
 public class TpsLimitFilter implements Filter {
 

dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/tps/DefaultTPSLimiter.java

@@ -23,6 +23,12 @@
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.ConcurrentMap;
 
+/**
+ * DefaultTPSLimiter is a default implementation for tps filter. It is an in memory based implementation for stroring
+ * tps information. It internally use
+ *
+ * @see org.apache.dubbo.rpc.filter.TpsLimitFilter
+ */
 public class DefaultTPSLimiter implements TPSLimiter {
 
     private final ConcurrentMap<String, StatItem> stats

dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/tps/StatItem.java

@@ -18,6 +18,10 @@
 
 import java.util.concurrent.atomic.AtomicInteger;
 
+/**
+ * Judge whether a particular invocation of service provider method should be allowed within a configured time interval.
+ * As a state it contain name of key ( e.g. method), last invocation time, interval and rate count.
+ */
 class StatItem {
 
     private String name;

dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/tps/TPSLimiter.java

@@ -19,6 +19,14 @@
 import org.apache.dubbo.common.URL;
 import org.apache.dubbo.rpc.Invocation;
 
+/**
+ * Provide boolean information whether a invocation of a provider service's methods or a particular method
+ * is allowed within a last invocation and current invocation.
+ * <pre>
+ *     e.g. if tps for a method m1 is 5 for a minute then if 6th call is made within the span of 1 minute then 6th
+ *     should not be allowed <b>isAllowable</b> will return false.
+ * </pre>
+ */
 public interface TPSLimiter {
 
     /**