dubbo 配置的中文注释

YunaiV · Feb 23, 2018 · bbdeff8 · bbdeff8
1 parent 98d27a4
commit bbdeff8
Show file tree

Hide file tree

Showing 18 changed files with 187 additions and 62 deletions.
diff --git a/dubbo-config/dubbo-config-api/src/main/java/com/alibaba/dubbo/config/AbstractConfig.java b/dubbo-config/dubbo-config-api/src/main/java/com/alibaba/dubbo/config/AbstractConfig.java
@@ -43,7 +43,11 @@
 public abstract class AbstractConfig implements Serializable {
 
     protected static final Logger logger = LoggerFactory.getLogger(AbstractConfig.class);
+
     private static final long serialVersionUID = 4267533505537413570L;
+
+    // ========== 属性值的格式校验，参见本类的 `#checkXXX` 方法 BEGIN ==========
+
     private static final int MAX_LENGTH = 200;
 
     private static final int MAX_PATH_LENGTH = 200;
@@ -59,7 +63,23 @@ public abstract class AbstractConfig implements Serializable {
     private static final Pattern PATTERN_NAME_HAS_SYMBOL = Pattern.compile("[:*,/\\-._0-9a-zA-Z]+");
 
     private static final Pattern PATTERN_KEY = Pattern.compile("[*,\\-._0-9a-zA-Z]+");
+
+    // ========== 属性值的格式校验，参见本类的 `#checkXXX` 方法 END ==========
+
+    /**
+     * 新老版本的 properties 的 key 映射
+     *
+     * key：新版本的配置 映射
+     * value：旧版本的配置 映射
+     *
+     * 来自 2012/3/8 下午 5：51 cb1f705 提交
+     * DUBBO-251 增加API覆盖dubbo.properties的测试，以及旧版本配置项测试。
+     */
     private static final Map<String, String> legacyProperties = new HashMap<String, String>();
+    /**
+     * 配置类名的后缀
+     * 例如，ServiceConfig 后缀为 Config；ServiceBean 后缀为 Bean。
+     */
     private static final String[] SUFFIXES = new String[]{"Config", "Bean"};
 
     static {
@@ -73,7 +93,7 @@ public abstract class AbstractConfig implements Serializable {
         legacyProperties.put("dubbo.service.url", "dubbo.service.address");
     }
 
-    static {
+    static { // TODO 芋艿，注意
         Runtime.getRuntime().addShutdownHook(new Thread(new Runnable() {
             public void run() {
                 if (logger.isInfoEnabled()) {
@@ -84,8 +104,20 @@ public void run() {
         }, "DubboShutdownHook"));
     }
 
+    /**
+     * 配置对象的编号
+     */
     protected String id;
 
+    /**
+     * 将键对应的值转换成目标的值。
+     *
+     * 因为，新老配置可能有一些差异，通过该方法进行转换。
+     *
+     * @param key 键
+     * @param value 值
+     * @return 转换后的值
+     */
     private static String convertLegacyValue(String key, String value) {
         if (value != null && value.length() > 0) {
             if ("dubbo.service.max.retry.providers".equals(key)) {
@@ -97,6 +129,13 @@ private static String convertLegacyValue(String key, String value) {
         return value;
     }
 
+    /**
+     * 读取环境变量和 properties 配置到配置对象
+     *
+     * 参见：<a href="https://dubbo.gitbooks.io/dubbo-user-book/configuration/properties.html">属性配置</a>
+     *
+     * @param config 配置对象
+     */
     protected static void appendProperties(AbstractConfig config) {
         if (config == null) {
             return;
@@ -106,26 +145,30 @@ protected static void appendProperties(AbstractConfig config) {
         for (Method method : methods) {
             try {
                 String name = method.getName();
-                if (name.length() > 3 && name.startsWith("set") && Modifier.isPublic(method.getModifiers())
-                        && method.getParameterTypes().length == 1 && isPrimitive(method.getParameterTypes()[0])) {
+                if (name.length() > 3 && name.startsWith("set") && Modifier.isPublic(method.getModifiers()) // 方法是 public 的 setting 方法。
+                        && method.getParameterTypes().length == 1 && isPrimitive(method.getParameterTypes()[0])) { // 方法的唯一参数是基本数据类型
+                    // 获得属性名，例如 `ApplicationConfig#setName(...)` 方法，对应的属性名为 name 。
                     String property = StringUtils.camelToSplitName(name.substring(3, 4).toLowerCase() + name.substring(4), ".");
 
+                    // 【环境变量】优先从带有 `Config#id` 的配置中获取，例如：`dubbo.application.demo-provider.name` 。
                     String value = null;
                     if (config.getId() != null && config.getId().length() > 0) {
-                        String pn = prefix + config.getId() + "." + property;
+                        String pn = prefix + config.getId() + "." + property; // 带有 `Config#id`
                         value = System.getProperty(pn);
                         if (!StringUtils.isBlank(value)) {
                             logger.info("Use System Property " + pn + " to config dubbo");
                         }
                     }
+                    // 【环境变量】获取不到，其次不带 `Config#id` 的配置中获取，例如：`dubbo.application.name` 。
                     if (value == null || value.length() == 0) {
-                        String pn = prefix + property;
+                        String pn = prefix + property; // // 不带 `Config#id`
                         value = System.getProperty(pn);
                         if (!StringUtils.isBlank(value)) {
                             logger.info("Use System Property " + pn + " to config dubbo");
                         }
                     }
                     if (value == null || value.length() == 0) {
+                        // 覆盖优先级为：环境变量 > XML 配置 > properties 配置，因此需要使用 getter 判断 XML 是否已经设置
                         Method getter;
                         try {
                             getter = config.getClass().getMethod("get" + name.substring(3), new Class<?>[0]);
@@ -137,13 +180,16 @@ protected static void appendProperties(AbstractConfig config) {
                             }
                         }
                         if (getter != null) {
-                            if (getter.invoke(config, new Object[0]) == null) {
+                            if (getter.invoke(config, new Object[0]) == null) { // 使用 getter 判断 XML 是否已经设置
+                                // 【properties 配置】优先从带有 `Config#id` 的配置中获取，例如：`dubbo.application.demo-provider.name` 。
                                 if (config.getId() != null && config.getId().length() > 0) {
                                     value = ConfigUtils.getProperty(prefix + config.getId() + "." + property);
                                 }
+                                // 【properties 配置】获取不到，其次不带 `Config#id` 的配置中获取，例如：`dubbo.application.name` 。
                                 if (value == null || value.length() == 0) {
                                     value = ConfigUtils.getProperty(prefix + property);
                                 }
+                                // 【properties 配置】老版本兼容，获取不到，最后不带 `Config#id` 的配置中获取，例如：`dubbo.protocol.name` 。
                                 if (value == null || value.length() == 0) {
                                     String legacyKey = legacyProperties.get(prefix + property);
                                     if (legacyKey != null && legacyKey.length() > 0) {
@@ -154,6 +200,7 @@ protected static void appendProperties(AbstractConfig config) {
                             }
                         }
                     }
+                    // 获取到值，进行反射设置。
                     if (value != null && value.length() > 0) {
                         method.invoke(config, new Object[]{convertPrimitive(method.getParameterTypes()[0], value)});
                     }
@@ -164,6 +211,12 @@ protected static void appendProperties(AbstractConfig config) {
         }
     }
 
+    /**
+     * 获取类名对应的属性标签，例如，ServiceConfig 对应为 service 。
+     *
+     * @param cls 类名
+     * @return 标签
+     */
     private static String getTagName(Class<?> cls) {
         String tag = cls.getSimpleName();
         for (String suffix : SUFFIXES) {
@@ -288,6 +341,12 @@ && isPrimitive(method.getReturnType())) {
         }
     }
 
+    /**
+     * 类型是否为基本数据类型。
+     *
+     * @param type 类型
+     * @return 是否
+     */
     private static boolean isPrimitive(Class<?> type) {
         return type.isPrimitive()
                 || type == String.class
@@ -302,6 +361,13 @@ private static boolean isPrimitive(Class<?> type) {
                 || type == Object.class;
     }
 
+    /**
+     * 将字符串转换成目标的基本数据类型的值
+     *
+     * @param type 目标的基本数据类型
+     * @param value 字符串
+     * @return 值
+     */
     private static Object convertPrimitive(Class<?> type, String value) {
         if (type == char.class || type == Character.class) {
             return value.length() > 0 ? value.charAt(0) : '\0';
@@ -453,6 +519,11 @@ protected void appendAnnotation(Class<?> annotationClass, Object annotation) {
         }
     }
 
+    /**
+     * 拼接成 XML 配置对象的字符串
+     *
+     * @return XML
+     */
     @Override
     public String toString() {
         try {

diff --git a/...nfig/dubbo-config-api/src/main/java/com/alibaba/dubbo/config/AbstractInterfaceConfig.java b/...nfig/dubbo-config-api/src/main/java/com/alibaba/dubbo/config/AbstractInterfaceConfig.java
@@ -44,23 +44,25 @@
 /**
  * AbstractDefaultConfig
  *
+ *
+ *
  * @export
  */
 public abstract class AbstractInterfaceConfig extends AbstractMethodConfig {
 
     private static final long serialVersionUID = -1559314110797223229L;
 
     // local impl class name for the service interface
-    protected String local;
+    protected String local; // TODO 芋艿
 
     // local stub class name for the service interface
-    protected String stub;
+    protected String stub; // TODO 芋艿
 
     // service monitor
     protected MonitorConfig monitor;
 
     // proxy type
-    protected String proxy;
+    protected String proxy; // TODO 芋艿
 
     // cluster type
     protected String cluster;
@@ -79,7 +81,7 @@ public abstract class AbstractInterfaceConfig extends AbstractMethodConfig {
     protected Integer connections;
 
     // layer
-    protected String layer;
+    protected String layer; // TODO 芋艿
 
     // application info
     protected ApplicationConfig application;
@@ -91,10 +93,10 @@ public abstract class AbstractInterfaceConfig extends AbstractMethodConfig {
     protected List<RegistryConfig> registries;
 
     // connection events
-    protected String onconnect;
+    protected String onconnect; // TODO 芋艿
 
     // disconnection events
-    protected String ondisconnect;
+    protected String ondisconnect; // TODO 芋艿
 
     // callback limits
     private Integer callbacks;

diff --git a/...-config/dubbo-config-api/src/main/java/com/alibaba/dubbo/config/AbstractMethodConfig.java b/...-config/dubbo-config-api/src/main/java/com/alibaba/dubbo/config/AbstractMethodConfig.java
@@ -24,6 +24,10 @@
 
 /**
  * AbstractMethodConfig
+ * TODO 需要改下
+ * 方法级配置的抽象类。
+ * 属性参见：http://dubbo.io/books/dubbo-user-book/references/xml/dubbo-method.html 。
+ *  ps：更多属性，在实现类里。
  *
  * @export
  */

diff --git a/...nfig/dubbo-config-api/src/main/java/com/alibaba/dubbo/config/AbstractReferenceConfig.java b/...nfig/dubbo-config-api/src/main/java/com/alibaba/dubbo/config/AbstractReferenceConfig.java
@@ -40,20 +40,20 @@ public abstract class AbstractReferenceConfig extends AbstractInterfaceConfig {
     protected Boolean init;
 
     // whether to use generic interface
-    protected String generic;
+    protected String generic; // TODO 芋艿
 
     // whether to find reference's instance from the current JVM
-    protected Boolean injvm;
+    protected Boolean injvm; // TODO 芋艿
 
     // lazy create connection
     protected Boolean lazy;
 
-    protected String reconnect;
+    protected String reconnect; // TODO 芋艿
 
     protected Boolean sticky;
 
     // whether to support event in stub. //TODO solve merge problem
-    protected Boolean stubevent;//= Constants.DEFAULT_STUB_EVENT;
+    protected Boolean stubevent;//= Constants.DEFAULT_STUB_EVENT; // TODO 芋艿
 
     // version
     protected String version;

diff --git a/...config/dubbo-config-api/src/main/java/com/alibaba/dubbo/config/AbstractServiceConfig.java b/...config/dubbo-config-api/src/main/java/com/alibaba/dubbo/config/AbstractServiceConfig.java
@@ -48,7 +48,7 @@ public abstract class AbstractServiceConfig extends AbstractInterfaceConfig {
     protected Boolean export;
 
     // weight
-    protected Integer weight;
+    protected Integer weight; // TODO 芋艿
 
     // document center
     protected String document;
@@ -57,21 +57,21 @@ public abstract class AbstractServiceConfig extends AbstractInterfaceConfig {
     protected Boolean dynamic;
 
     // whether to use token
-    protected String token;
+    protected String token; // TODO 芋艿
 
     // access log
-    protected String accesslog;
-    protected List<ProtocolConfig> protocols;
+    protected String accesslog; // TODO 芋艿
+    protected List<ProtocolConfig> protocols; // TODO 芋艿
     // max allowed execute times
-    private Integer executes;
+    private Integer executes; // TODO 芋艿
     // whether to register
     private Boolean register;
 
     // warm up period
-    private Integer warmup;
+    private Integer warmup; // TODO 芋艿
 
     // serialization
-    private String serialization;
+    private String serialization; // TODO 芋艿
 
     public String getVersion() {
         return version;

diff --git a/dubbo-config/dubbo-config-api/src/main/java/com/alibaba/dubbo/config/ApplicationConfig.java b/dubbo-config/dubbo-config-api/src/main/java/com/alibaba/dubbo/config/ApplicationConfig.java
@@ -29,6 +29,9 @@
 /**
  * ApplicationConfig
  *
+ * 应用配置
+ * 属性参见 http://dubbo.io/books/dubbo-user-book/references/xml/dubbo-application.html
+ *
  * @export
  */
 public class ApplicationConfig extends AbstractConfig {
@@ -68,7 +71,11 @@ public class ApplicationConfig extends AbstractConfig {
     // is default or not
     private Boolean isDefault;
 
-    // directory for saving thread dump
+    /**
+     * directory for saving thread dump
+     *
+     * @see <a href="http://dubbo.io/books/dubbo-user-book/demos/dump.html">线程栈自动 dump</a>
+     */
     private String dumpDirectory;
 
     private Boolean qosEnable;

diff --git a/dubbo-config/dubbo-config-api/src/main/java/com/alibaba/dubbo/config/ArgumentConfig.java b/dubbo-config/dubbo-config-api/src/main/java/com/alibaba/dubbo/config/ArgumentConfig.java
@@ -21,6 +21,11 @@
 import java.io.Serializable;
 
 /**
+ * ArgumentConfig
+ *
+ * 方法参数配置。
+ * 属性参见：http://dubbo.io/books/dubbo-user-book/references/xml/dubbo-argument.html 。
+ *
  * @export
  */
 public class ArgumentConfig implements Serializable {

diff --git a/dubbo-config/dubbo-config-api/src/main/java/com/alibaba/dubbo/config/ConsumerConfig.java b/dubbo-config/dubbo-config-api/src/main/java/com/alibaba/dubbo/config/ConsumerConfig.java
@@ -19,6 +19,9 @@
 /**
  * ConsumerConfig
  *
+ * 服务消费者缺省值配置。
+ * 参数详见：http://dubbo.io/books/dubbo-user-book/references/xml/dubbo-consumer.html
+ *
  * @export
  */
 public class ConsumerConfig extends AbstractReferenceConfig {
@@ -29,7 +32,7 @@ public class ConsumerConfig extends AbstractReferenceConfig {
     private Boolean isDefault;
 
     // networking framework client uses: netty, mina, etc.
-    private String client;
+    private String client; // TODO 芋艿
 
     @Override
     public void setTimeout(Integer timeout) {