From b3d44a6e63543f443d0ae26620a384f4e28f5c6d Mon Sep 17 00:00:00 2001
From: Imteyaz Ahmed Khan <30792765+khanimteyaz@users.noreply.github.com>
Date: Mon, 17 Dec 2018 13:26:28 +0530
Subject: [PATCH] Documentation/2935#dubbo rpc api (#2967)

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

* wrong @see java.io.File was added, removed this version of checkins

* Close all ports after tests finish (#2906)

* fix testCustomExecutor (#2904)

* Graceful shutdown enhancement in Spring (#2901)

* Simplify the code logic of the method AbstractClusterInvoker#reselect. (#2826)

* Simplify the code logic of the method AbstractClusterInvoker#reselect.

* Minor modification for code style.

* create AbstractRouter (#2909)

* create AbstractRouter

* router default method

* router default method

* router default method

* mockinvoker

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

* Enhance unit test (#2920)

* Change Readme dubbo-sample hyperlink (#2927)

* Simply TagRouter (#2924)

* make telnet config work again (#2925)

* Remove the log to putRandomPort when one protocol use random port (#2931)

* optimize findConfigedPorts method of ServiceConfig to log only one time when userandom port

* move the log to method putRandomPort

* Fix DubboShutdownHook Memory Leak (#2922)

* Improve UT grammar and remove unnecessary braces. (#2930)

* Improve UT grammer, fix compiler warnings.

* Remove unnecessary braces.

* re-enable testCustomExecutor  (#2917)

* fix testCustomExecutor

* fix ci

* Fixing test-order dependency for FstObjectInputTest (#2815)

* re-enable testCustomExecutor (#2913)

* Resetting ExtensionLoader to remove test order dependencies in StickyTest (#2807)

* optimize the RondRobinLoadBalance and MockClusterInvoker (#2932)

delete unused logic and take the logger out.

* [Dubbo-2864] Fix build failed with -Prelease (#2923)

fixes #2864

* Fix telnet can not find method with enum type (#2803)

* [dubbo-2766] fix the bug of isMatch method of InvokeTelnetHandler (#2787)

* enhance org.apache.dubbo.rpc.protocol.dubbo.telnet.InvokeTelnetHandler#isMatch (#2941)

* enhance isMatch

* remove useless imports

* [Dubbo-2766]Fix 2766 and enhance the invoke command (#2801)

* add getter and setter for ServiceConfig's interfaceName property#2353

* add interfaceName to ignoreAttributeNames and change the unit test

* delete the demo source code and update the unit test

* unchange ServiceConfig

* update unit test

* update unit test

* fix https://github.com/apache/incubator-dubbo/issues/2798 and enhance invoke command

* Delete useless assignments (#2939)

* Replace anonymous class with method reference (#2929)

* Replace anonymous class with method reference

* Revert changes as per @beiwei30 code review

* Optimize retry for FailbackRegistry. (#2763)

* Abstract retry task

* Task for retry.

* Fix sth.

* Finish Optimize. fix ci failed.

* Optimize retry for FailbackRegistry.
The retry operation splits into specific operations, such as subscriptions and registrations. This approach allows for very precise retry control.

* Optimize retry for FailbackRegistry.
The retry operation splits into specific operations, such as subscriptions and registrations. This approach allows for very precise retry control.

* Optimize logger warn's msg.

* Optimize FailedNotifiedTask's run method.
Optimize addXXXTask, directly return if we already have a retry task.

* Optimize notify logic, just notify when the urls is not empty.

* Optimize notify logic, just notify when the urls is not empty.

* Optimize timer that use daemon thread.

* standardize semantics of all mergers,enhance mergeFactory and testcase (#2936)

* Modified to lower camel case (#2945)

* Improve several map iteration (#2938)

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

* wrong @see java.io.File was added, removed this version of checkins
---
 .../java/org/apache/dubbo/rpc/Filter.java     | 19 +++++++++++++++++++
 .../dubbo/rpc/filter/ActiveLimitFilter.java   | 11 ++++++++++-
 .../dubbo/rpc/filter/ClassLoaderFilter.java   |  2 +-
 .../dubbo/rpc/filter/CompatibleFilter.java    | 15 ++++++++++++++-
 .../rpc/filter/ConsumerContextFilter.java     |  7 ++++++-
 .../dubbo/rpc/filter/ContextFilter.java       |  6 +++++-
 .../dubbo/rpc/filter/DeprecatedFilter.java    |  5 ++++-
 .../apache/dubbo/rpc/filter/EchoFilter.java   |  2 +-
 .../dubbo/rpc/filter/ExecuteLimitFilter.java  |  5 ++++-
 .../apache/dubbo/rpc/filter/TokenFilter.java  |  5 ++++-
 .../dubbo/rpc/filter/TpsLimitFilter.java      |  8 ++++++--
 .../rpc/filter/tps/DefaultTPSLimiter.java     |  6 ++++++
 .../apache/dubbo/rpc/filter/tps/StatItem.java |  4 ++++
 .../dubbo/rpc/filter/tps/TPSLimiter.java      |  8 ++++++++
 14 files changed, 92 insertions(+), 11 deletions(-)

diff --git a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/Filter.java b/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/Filter.java
index 3483a607056..9d3b7c4d506 100644
--- a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/Filter.java
+++ b/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 {
diff --git a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/ActiveLimitFilter.java b/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/ActiveLimitFilter.java
index 66213393d4f..7250633a794 100644
--- a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/ActiveLimitFilter.java
+++ b/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/ActiveLimitFilter.java
@@ -30,7 +30,16 @@
 import java.util.concurrent.TimeUnit;
 
 /**
- * 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 {
diff --git a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/ClassLoaderFilter.java b/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/ClassLoaderFilter.java
index 17a6ca01f68..17d265ef6bb 100644
--- a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/ClassLoaderFilter.java
+++ b/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 {
diff --git a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/CompatibleFilter.java b/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/CompatibleFilter.java
index aef65aa36be..ace832ca33c 100644
--- a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/CompatibleFilter.java
+++ b/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);
diff --git a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/ConsumerContextFilter.java b/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/ConsumerContextFilter.java
index f852d7b9e96..ba5e77b2740 100644
--- a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/ConsumerContextFilter.java
+++ b/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 {
diff --git a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/ContextFilter.java b/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/ContextFilter.java
index 2e7d0c5ae90..344419d1504 100644
--- a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/ContextFilter.java
+++ b/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/ContextFilter.java
@@ -30,7 +30,11 @@
 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 RpcContext
+ * @see org.apache.dubbo.rpc.PostProcessFilter
  */
 @Activate(group = Constants.PROVIDER, order = -10000)
 public class ContextFilter extends AbstractPostProcessFilter {
diff --git a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/DeprecatedFilter.java b/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/DeprecatedFilter.java
index 14732ddbd22..95803cbd1a7 100644
--- a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/DeprecatedFilter.java
+++ b/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 {
diff --git a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/EchoFilter.java b/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/EchoFilter.java
index 5dfa8f0813e..cba9e7f4f46 100644
--- a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/EchoFilter.java
+++ b/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 {
diff --git a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/ExecuteLimitFilter.java b/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/ExecuteLimitFilter.java
index 17e05f785f2..1ca1fdfe20e 100644
--- a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/ExecuteLimitFilter.java
+++ b/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 {
diff --git a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/TokenFilter.java b/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/TokenFilter.java
index 3b9695fb16f..35ef2aca526 100644
--- a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/TokenFilter.java
+++ b/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 {
diff --git a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/TpsLimitFilter.java b/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/TpsLimitFilter.java
index ad4137a0505..5ce78d141ee 100644
--- a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/TpsLimitFilter.java
+++ b/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 {
 
diff --git a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/tps/DefaultTPSLimiter.java b/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/tps/DefaultTPSLimiter.java
index 431a31f7ae2..71b579bc75d 100644
--- a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/tps/DefaultTPSLimiter.java
+++ b/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
diff --git a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/tps/StatItem.java b/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/tps/StatItem.java
index 6ef9ab524bd..2fcdaef82a8 100644
--- a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/tps/StatItem.java
+++ b/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;
diff --git a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/tps/TPSLimiter.java b/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/tps/TPSLimiter.java
index 7145a96cdf9..f104eb12c3a 100644
--- a/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/filter/tps/TPSLimiter.java
+++ b/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 {
 
     /**