merge dubbo master

dubbo-cluster/readme.md

@@ -0,0 +1,28 @@
+ ## dubbo-cluster 
+ > 集群模块：将多个服务提供方伪装为一个提供方，包括：负载均衡, 集群容错，路由，分组聚合等。集群的地址列表可以是静态配置的，也可以是由注册中心下发。
+
+注册中心下发，由 dubbo-registry 提供特性。
+
+### 容错
+> com.alibaba.dubbo.rpc.cluster.Cluster 接口 + com.alibaba.dubbo.rpc.cluster.support 包。
+Cluster 将 Directory 中的多个 Invoker 伪装成一个 Invoker，对上层透明，伪装过程包含了容错逻辑，调用失败后，重试另一个。
+拓展参见 《Dubbo 用户指南 —— 集群容错》 和 《Dubbo 开发指南 —— 集群扩展》 文档。
+
+### 目录
+> com.alibaba.dubbo.rpc.cluster.Directory 接口 + com.alibaba.dubbo.rpc.cluster.directory 包。
+Directory 代表了多个 Invoker ，可以把它看成 List ，但与 List 不同的是，它的值可能是动态变化的，比如注册中心推送变更。
+
+### 路由
+> com.alibaba.dubbo.rpc.cluster.Router 接口 + com.alibaba.dubbo.rpc.cluster.router  包。
+负责从多个 Invoker 中按路由规则选出子集，比如读写分离，应用隔离等。
+
+### 配置
+> 接口 + com.alibaba.dubbo.rpc.cluster.configurator 包。
+
+### 负载均衡
+> com.alibaba.dubbo.rpc.cluster.LoadBalance 接口 + com.alibaba.dubbo.rpc.cluster.loadbalance 包。
+LoadBalance 负责从多个 Invoker 中选出具体的一个用于本次调用，选的过程包含了负载均衡算法，调用失败后，需要重选。
+
+### 整体流程如下
+
+![](流程图.jpg)

dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/Cluster.java

@@ -33,6 +33,11 @@
 public interface Cluster {
 
     /**
+     *
+     * <pre>
+     * com.alibaba.dubbo.rpc.cluster.Cluster 接口 + com.alibaba.dubbo.rpc.cluster.support 包。
+     * Cluster 将 Directory 中的多个 Invoker 伪装成一个 Invoker，对上层透明，伪装过程包含了容错逻辑，调用失败后，重试另一个。
+     * </pre>
      * Merge the directory invokers to a virtual invoker.
      *
      * @param <T>

dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/Configurator.java

@@ -19,6 +19,8 @@
 import org.apache.dubbo.common.URL;
 
 /**
+ *
+ * 配置 com.alibaba.dubbo.rpc.cluster.configurator 包
  * Configurator. (SPI, Prototype, ThreadSafe)
  *
  */

dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/Directory.java

@@ -33,6 +33,11 @@
 public interface Directory<T> extends Node {
 
     /**
+     *
+     * <pre>
+     *     com.alibaba.dubbo.rpc.cluster.Directory 接口 + com.alibaba.dubbo.rpc.cluster.directory 包。
+     * Directory 代表了多个 Invoker ，可以把它看成 List ，但与 List 不同的是，它的值可能是动态变化的，比如注册中心推送变更。
+     * </pre>
      * get service type.
      *
      * @return service type.

dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/LoadBalance.java

@@ -27,6 +27,10 @@
 import java.util.List;
 
 /**
+ * <pre>
+ *     com.alibaba.dubbo.rpc.cluster.LoadBalance 接口 + com.alibaba.dubbo.rpc.cluster.loadbalance 包。
+ * LoadBalance 负责从多个 Invoker 中选出具体的一个用于本次调用，选的过程包含了负载均衡算法，调用失败后，需要重选。
+ * </pre>
  * LoadBalance. (SPI, Singleton, ThreadSafe)
  * <p>
  * <a href="http://en.wikipedia.org/wiki/Load_balancing_(computing)">Load-Balancing</a>

dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/Merger.java

@@ -18,6 +18,12 @@
 
 import org.apache.dubbo.common.extension.SPI;
 
+/**
+ * 合并结果
+ * com.alibaba.dubbo.rpc.cluster.Merger 接口 + com.alibaba.dubbo.rpc.cluster.merger 包。
+ * 合并返回结果，用于分组聚合。
+ * @param <T>
+ */
 @SPI
 public interface Merger<T> {
 

dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/Router.java

@@ -24,6 +24,11 @@
 import java.util.List;
 
 /**
+ * <pre>
+ * com.alibaba.dubbo.rpc.cluster.Router 接口 + com.alibaba.dubbo.rpc.cluster.router  包。
+ * 负责从多个 Invoker 中按路由规则选出子集，比如读写分离，应用隔离等。
+ * </pre>
+ * <p>
  * Router. (SPI, Prototype, ThreadSafe)
  * <p>
  * <a href="http://en.wikipedia.org/wiki/Routing">Routing</a>

dubbo-common/readme.md

@@ -0,0 +1,3 @@
+## dubbo-common
+
+> 公共逻辑模块：提供工具类和通用模型

dubbo-common/src/main/java/org/apache/dubbo/common/URL.java

@@ -38,6 +38,12 @@
 
 /**
  * URL - Uniform Resource Locator (Immutable, ThreadSafe)
+ *
+ * <pre>
+ * 格式为 protocol://username:password@host:port/path?key=value&key=value ，通过 URL#buildString(...) 方法生成。
+ * parameters 属性，参数集合。从上面的 Service URL 例子我们可以看到，里面的 key=value ，实际上就是 Service 对应的配置项。
+ * 该属性，通过 AbstractConfig#appendParameters(parameters, config, prefix) 方法生成。
+ * </pre>
  * <p>
  * url example:
  * <ul>
@@ -72,20 +78,40 @@
 
     private static final long serialVersionUID = -1985165475234910535L;
 
+    /**
+     * 协议名称
+     */
     private final String protocol;
 
+    /**
+     * 用户名
+     */
     private final String username;
 
+    /**
+     * 密码
+     */
     private final String password;
 
-    // by default, host to registry
+    /**
+     * by default, host to registry
+     * 地址
+     */
     private final String host;
-
-    // by default, port to registry
+    /**
+     * by default, port to registry
+     * 端口
+     */
     private final int port;
 
+    /**
+     * 路径 服务名
+     */
     private final String path;
 
+    /**
+     * 参数集合
+     */
     private final Map<String, String> parameters;
 
     // ==== cache ====