增加javadoc注释

2017-03-02 10:02:45 +08:00
parent 11a29b4ed6
commit d948c7af47
22 changed files with 122 additions and 81 deletions
--- a/src/META-INF/application-template.xml
+++ b/src/META-INF/application-template.xml
@@ -42,8 +42,8 @@
            一个组包含多个NODE， 同一Service服务可以由多个进程提供，这些进程称为一个GROUP，且同一GROUP内的进程必须在同一机房或局域网内
            一个group节点对应一个 Transport 对象。
            name: 服务组ID，长度不能超过11个字节. 默认为空字符串。 注意: name不能包含$符号。
-            protocol：值只能是UDP TCP， 默认TCP
-            kind: 与SNCP服务连接时的数据传输类型；可选值有:rest(不区分大小写);值为空或空字符串表示按SNCP协议传输; 为rest表示按REST传输。默认值为空
+            protocol：值范围：UDP TCP， 默认TCP
+            subprotocol: 子协议，预留字段。默认值为空
            注意: 一个node只能所属一个group。只要存在protocol=SNCP的Server节点信息， 就必须有group节点信息。
        -->
        <group name="" protocol="TCP">
--- a/src/org/redkale/boot/ApiDocs.java
+++ b/src/org/redkale/boot/ApiDocs.java
@@ -15,15 +15,17 @@ import org.redkale.source.*;
 import org.redkale.util.*;

 /**
+ * API接口文档生成类，作用：生成Application实例中所有HttpServer的可用HttpServlet的API接口方法   <br>
 * 继承 HttpBaseServlet 是为了获取 WebAction 信息
 *
+ * <p>
 * 详情见: https://redkale.org
 *
 * @author zhangjx
 */
 public class ApiDocs extends HttpBaseServlet {

-    private final Application app;
+    private final Application app; //Application全局对象

    public ApiDocs(Application app) {
        this.app = app;
--- a/src/org/redkale/boot/Application.java
+++ b/src/org/redkale/boot/Application.java
@@ -30,9 +30,17 @@ import org.redkale.watch.WatchFactory;
 import org.w3c.dom.*;

 /**
- * 编译时需要加入: -XDignore.symbol.file=true
+ *
+ * 进程启动类，全局对象。  <br>
+ * <pre>
+ * 程序启动执行步骤:
+ *     1、读取application.xml
+ *     2、进行classpath扫描动态加载Service与Servlet
+ *     3、优先加载所有SNCP协议的服务，再加载其他协议服务
+ *     4、最后进行Service、Servlet与其他资源之间的依赖注入
+ * </pre>
 * <p>
- * 进程启动类，程序启动后读取application.xml,进行classpath扫描动态加载Service与Servlet 优先加载所有SNCP协议的服务， 再加载其他协议服务， 最后进行Service、Servlet与其他资源之间的依赖注入。
+ * 编译时需要加入: -XDignore.symbol.file=true
 * <p>
 * 详情见: https://redkale.org
 *
@@ -333,7 +341,7 @@ public final class Application {
                }
                GroupInfo ginfo = globalGroups.get(group);
                if (ginfo == null) {
-                    ginfo = new GroupInfo(group, protocol, conf.getValue("kind", ""), new LinkedHashSet<>());
+                    ginfo = new GroupInfo(group, protocol, conf.getValue("subprotocol", ""), new LinkedHashSet<>());
                    globalGroups.put(group, ginfo);
                }
                for (AnyValue node : conf.getAnyValues("node")) {
--- a/src/org/redkale/boot/ClassFilter.java
+++ b/src/org/redkale/boot/ClassFilter.java
@@ -28,9 +28,9 @@ import org.redkale.util.AnyValue.DefaultAnyValue;
@SuppressWarnings("unchecked")
 public final class ClassFilter<T> {

-    private static final Logger logger = Logger.getLogger(ClassFilter.class.getName());
+    private static final Logger logger = Logger.getLogger(ClassFilter.class.getName()); //日志对象

-    private static final boolean finer = logger.isLoggable(Level.FINER);
+    private static final boolean finer = logger.isLoggable(Level.FINER); //日志级别

    private final Set<FilterEntry<T>> entrys = new HashSet<>(); //符合条件的结果

--- a/src/org/redkale/boot/GroupInfo.java
+++ b/src/org/redkale/boot/GroupInfo.java
@@ -9,6 +9,7 @@ import java.net.InetSocketAddress;
 import java.util.*;

 /**
+ * 协议地址组合对象, 对应application.xml 中 resources-&#62;group 节点信息
 *
 * <p>
 * 详情见: https://redkale.org
@@ -17,21 +18,21 @@ import java.util.*;
 */
 public class GroupInfo {

-    protected String name;
+    protected String name;  //地址

-    protected String protocol;
+    protected String protocol; //协议 取值范围:  TCP、UDP

-    protected String kind;
+    protected String subprotocol; //子协议，预留使用

-    protected Set<InetSocketAddress> addrs;
+    protected Set<InetSocketAddress> addrs; //地址列表， 对应 resources-&#62;group-&#62;node节点信息

    public GroupInfo() {
    }

-    public GroupInfo(String name, String protocol, String kind, Set<InetSocketAddress> addrs) {
+    public GroupInfo(String name, String protocol, String subprotocol, Set<InetSocketAddress> addrs) {
        this.name = name;
        this.protocol = protocol;
-        this.kind = kind;
+        this.subprotocol = subprotocol;
        this.addrs = addrs;
    }

@@ -51,12 +52,12 @@ public class GroupInfo {
        this.protocol = protocol;
    }

-    public String getKind() {
-        return kind;
+    public String getSubprotocol() {
+        return subprotocol;
    }

-    public void setKind(String kind) {
-        this.kind = kind;
+    public void setSubprotocol(String subprotocol) {
+        this.subprotocol = subprotocol;
    }

    public Set<InetSocketAddress> getAddrs() {
--- a/src/org/redkale/boot/NodeHttpServer.java
+++ b/src/org/redkale/boot/NodeHttpServer.java
@@ -29,7 +29,7 @@ import org.redkale.util.*;
@NodeProtocol({"HTTP"})
 public class NodeHttpServer extends NodeServer {

-    protected final boolean rest;
+    protected final boolean rest; //是否加载REST服务， 为true加载rest节点信息并将所有可REST化的Service生成RestHttpServlet

    protected final HttpServer httpServer;

--- a/src/org/redkale/boot/NodeInterceptor.java
+++ b/src/org/redkale/boot/NodeInterceptor.java
@@ -9,6 +9,7 @@ import java.util.Objects;
 import org.redkale.service.Service;

 /**
+ * NodeServer的拦截类
 *
 * <p>
 * 详情见: https://redkale.org
@@ -17,10 +18,22 @@ import org.redkale.service.Service;
 */
 public class NodeInterceptor {

+    /** *
+     * Server.start之前调用 <br>
+     * NodeServer.start的部署是先执行NodeInterceptor.preStart，再执行 Server.start 方法
+     *
+     * @param server NodeServer
+     */
    public void preStart(NodeServer server) {

    }

+    /**
+     * Server.shutdown之前调用 <br>
+     * NodeServer.shutdown的部署是先执行NodeInterceptor.preShutdown，再执行 Server.sshutdown 方法
+     *
+     * @param server NodeServer
+     */
    public void preShutdown(NodeServer server) {

    }
--- a/src/org/redkale/boot/NodeServer.java
+++ b/src/org/redkale/boot/NodeServer.java
@@ -165,7 +165,7 @@ public abstract class NodeServer {
        initResource(); //给 DataSource、CacheSource 注册依赖注入时的监听回调事件。
        String interceptorClass = this.serverConf.getValue("interceptor", "");
        if (!interceptorClass.isEmpty()) {
-            Class clazz = Class.forName(interceptorClass); 
+            Class clazz = Class.forName(interceptorClass);
            this.interceptor = (NodeInterceptor) clazz.newInstance();
        }

@@ -276,8 +276,8 @@ public abstract class NodeServer {
                if (WebSocketNode.class.isAssignableFrom(type)) continue;
            }
            if (entry.getName().contains("$")) throw new RuntimeException("<name> value cannot contains '$' in " + entry.getProperty());
-            if (resourceFactory.find(entry.getName(), type) != null) { //Server加载Service时需要判断是否已经加载过了。
-                Service oldother = resourceFactory.find(entry.getName(), type);
+            Service oldother = resourceFactory.find(entry.getName(), type);
+            if (oldother != null) { //Server加载Service时需要判断是否已经加载过了。
                interceptorServiceWrappers.add(new NodeInterceptor.InterceptorServiceWrapper(entry.getName(), type, oldother));
                continue;
            }
@@ -403,7 +403,7 @@ public abstract class NodeServer {
        Transport first = transports.get(0);
        GroupInfo ginfo = application.findGroupInfo(first.getName());
        Transport newTransport = new Transport(groupid, ginfo.getProtocol(), application.getWatchFactory(),
-            ginfo.getKind(), application.transportBufferPool, application.transportChannelGroup, this.sncpAddress, addrs);
+            ginfo.getSubprotocol(), application.transportBufferPool, application.transportChannelGroup, this.sncpAddress, addrs);
        synchronized (application.resourceFactory) {
            transport = application.resourceFactory.find(groupid, Transport.class);
            if (transport == null) {
@@ -429,7 +429,7 @@ public abstract class NodeServer {
            Set<InetSocketAddress> addrs = ginfo.copyAddrs();
            if (addrs == null) throw new RuntimeException("Not found <group> = " + group + " on <resources> ");
            transport = new Transport(group, ginfo.getProtocol(), application.getWatchFactory(),
-                ginfo.getKind(), application.transportBufferPool, application.transportChannelGroup, this.sncpAddress, addrs);
+                ginfo.getSubprotocol(), application.transportBufferPool, application.transportChannelGroup, this.sncpAddress, addrs);
            application.resourceFactory.register(group, transport);
        }
        return transport;
--- a/src/org/redkale/convert/ArrayDecoder.java
+++ b/src/org/redkale/convert/ArrayDecoder.java
@@ -9,10 +9,10 @@ import java.lang.reflect.*;
 import java.util.*;

 /**
- * 数组的反序列化操作类
- * 对象数组的反序列化，不包含int[]、long[]这样的primitive class数组。
- * 数组长度不能超过 32767。 在BSON中数组长度设定的是short，对于大于32767长度的数组传输会影响性能，所以没有采用int存储。
- * 支持一定程度的泛型。
+ * 数组的反序列化操作类  <br>
+ * 对象数组的反序列化，不包含int[]、long[]这样的primitive class数组。  <br>
+ * 数组长度不能超过 32767。 在BSON中数组长度设定的是short，对于大于32767长度的数组传输会影响性能，所以没有采用int存储。  <br>
+ * 支持一定程度的泛型。  <br>
 *
 * <p>
 * 详情见: https://redkale.org
--- a/src/org/redkale/convert/ArrayEncoder.java
+++ b/src/org/redkale/convert/ArrayEncoder.java
@@ -8,10 +8,10 @@ package org.redkale.convert;
 import java.lang.reflect.*;

 /**
- * 数组的序列化操作类
- * 对象数组的序列化，不包含int[]、long[]这样的primitive class数组。
- * 数组长度不能超过 32767。 在BSON中数组长度设定的是short，对于大于32767长度的数组传输会影响性能，所以没有必要采用int存储。
- * 支持一定程度的泛型。
+ * 数组的序列化操作类  <br>
+ * 对象数组的序列化，不包含int[]、long[]这样的primitive class数组。  <br>
+ * 数组长度不能超过 32767。 在BSON中数组长度设定的是short，对于大于32767长度的数组传输会影响性能，所以没有必要采用int存储。  <br>
+ * 支持一定程度的泛型。  <br>
 *
 * <p>
 * 详情见: https://redkale.org
--- a/src/org/redkale/convert/CollectionDecoder.java
+++ b/src/org/redkale/convert/CollectionDecoder.java
@@ -11,9 +11,9 @@ import java.lang.reflect.Type;
 import java.util.Collection;

 /**
- * Collection的反序列化操作类
- * 集合大小不能超过 32767。 在BSON中集合大小设定的是short，对于大于32767长度的集合传输会影响性能，所以没有采用int存储。
- * 支持一定程度的泛型。
+ * Collection的反序列化操作类  <br>
+ * 集合大小不能超过 32767。 在BSON中集合大小设定的是short，对于大于32767长度的集合传输会影响性能，所以没有采用int存储。  <br>
+ * 支持一定程度的泛型。  <br>
 *
 * <p>
 * 详情见: https://redkale.org
--- a/src/org/redkale/convert/CollectionEncoder.java
+++ b/src/org/redkale/convert/CollectionEncoder.java
@@ -9,9 +9,9 @@ import java.lang.reflect.*;
 import java.util.Collection;

 /**
- * Collection的序列化操作类
- * 集合大小不能超过 32767。 在BSON中集合大小设定的是short，对于大于32767长度的集合传输会影响性能，故没有采用int存储。
- * 支持一定程度的泛型。
+ * Collection的序列化操作类  <br>
+ * 集合大小不能超过 32767。 在BSON中集合大小设定的是short，对于大于32767长度的集合传输会影响性能，故没有采用int存储。  <br>
+ * 支持一定程度的泛型。  <br>
 *
 * <p>
 * 详情见: https://redkale.org
--- a/src/org/redkale/convert/ConvertEntity.java
+++ b/src/org/redkale/convert/ConvertEntity.java
@@ -10,8 +10,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 import java.lang.annotation.*;

 /**
- * 用于类名的别名
- * 该值必须是全局唯一
+ * 用于类名的别名, 该值必须是全局唯一   <br>
 * 使用场景: 当BSON序列化为了不指定class可以使用@ConvertEntity来取个别名。关联方法: Reader.readClassName() 和 Writer.writeClassName(String value) 。
 *
 * <p>
--- a/src/org/redkale/net/Transport.java
+++ b/src/org/redkale/net/Transport.java
@@ -44,7 +44,7 @@ public final class Transport {

    protected final String name; //即<group>的name属性

-    protected final String kind; //即<group>的kind属性
+    protected final String subprotocol; //即<group>的subprotocol属性

    protected final boolean tcp;

@@ -62,16 +62,16 @@ public final class Transport {

    protected final ConcurrentHashMap<SocketAddress, BlockingQueue<AsyncConnection>> connPool = new ConcurrentHashMap<>();

-    public Transport(String name, WatchFactory watch, String kind, final ObjectPool<ByteBuffer> transportBufferPool,
+    public Transport(String name, WatchFactory watch, String subprotocol, final ObjectPool<ByteBuffer> transportBufferPool,
        final AsynchronousChannelGroup transportChannelGroup, final InetSocketAddress clientAddress, final Collection<InetSocketAddress> addresses) {
-        this(name, DEFAULT_PROTOCOL, watch, kind, transportBufferPool, transportChannelGroup, clientAddress, addresses);
+        this(name, DEFAULT_PROTOCOL, watch, subprotocol, transportBufferPool, transportChannelGroup, clientAddress, addresses);
    }

-    public Transport(String name, String protocol, WatchFactory watch, String kind, final ObjectPool<ByteBuffer> transportBufferPool,
+    public Transport(String name, String protocol, WatchFactory watch, String subprotocol, final ObjectPool<ByteBuffer> transportBufferPool,
        final AsynchronousChannelGroup transportChannelGroup, final InetSocketAddress clientAddress, final Collection<InetSocketAddress> addresses) {
        this.name = name;
        this.watch = watch;
-        this.kind = kind == null ? "" : kind.trim();
+        this.subprotocol = subprotocol == null ? "" : subprotocol.trim();
        this.protocol = protocol;
        this.tcp = "TCP".equalsIgnoreCase(protocol);
        this.group = transportChannelGroup;
@@ -83,14 +83,17 @@ public final class Transport {
    public Transport(final Collection<Transport> transports) {
        Transport first = null;
        List<String> tmpgroup = new ArrayList<>();
-        for (Transport t : transports) {
-            if (first == null) first = t;
-            tmpgroup.add(t.name);
+        if (transports != null) {
+            for (Transport t : transports) {
+                if (first == null) first = t;
+                tmpgroup.add(t.name);
+            }
        }
+        if (first == null) throw new NullPointerException("Collection<Transport> is null or empty");
        //必须按字母排列顺序确保，相同内容的transport列表组合的name相同，而不会因为list的顺序不同产生不同的name
        this.name = tmpgroup.stream().sorted().collect(Collectors.joining(";"));
        this.watch = first.watch;
-        this.kind = first.kind;
+        this.subprotocol = first.subprotocol;
        this.protocol = first.protocol;
        this.tcp = "TCP".equalsIgnoreCase(first.protocol);
        this.group = first.group;
@@ -118,8 +121,8 @@ public final class Transport {
        return name;
    }

-    public String getKind() {
-        return kind;
+    public String getSubprotocol() {
+        return subprotocol;
    }

    public void close() {
--- a/src/org/redkale/net/http/HttpPrepareServlet.java
+++ b/src/org/redkale/net/http/HttpPrepareServlet.java
@@ -17,8 +17,8 @@ import org.redkale.util.*;
 import org.redkale.watch.*;

 /**
- * HTTP Servlet的总入口，请求在HttpPrepareServlet中进行分流。
- * 一个HttpServer只有一个HttpPrepareServlet， 用于管理所有HttpServlet。
+ * HTTP Servlet的总入口，请求在HttpPrepareServlet中进行分流。  <br>
+ * 一个HttpServer只有一个HttpPrepareServlet， 用于管理所有HttpServlet。  <br>
 *
 * <p>
 * 详情见: https://redkale.org
--- a/src/org/redkale/net/http/HttpRequest.java
+++ b/src/org/redkale/net/http/HttpRequest.java
@@ -22,7 +22,7 @@ import org.redkale.util.ByteArray;
 * 例如简单的翻页查询   <br>
 *      /pipes/record/query/offset:0/limit:20 <br>
 * 获取页号: int offset = request.getRequstURIPath("offset:", 0);   <br>
- * 获取行数: int limit = request.getRequstURIPath("limit:", 10);
+ * 获取行数: int limit = request.getRequstURIPath("limit:", 10);  <br>
 * <p>
 * 详情见: https://redkale.org
 *
--- a/src/org/redkale/net/http/HttpResponse.java
+++ b/src/org/redkale/net/http/HttpResponse.java
@@ -21,9 +21,9 @@ import org.redkale.util.AnyValue.Entry;
 import org.redkale.util.*;

 /**
- * Http响应包 与javax.servlet.http.HttpServletResponse 基本类似。
- * 同时提供发送json的系列接口: public void finishJson(Type type, Object obj)
- * Redkale提倡http+json的接口风格， 所以主要输出的数据格式为json， 同时提供异步接口。
+ * Http响应包 与javax.servlet.http.HttpServletResponse 基本类似。  <br>
+ * 同时提供发送json的系列接口: public void finishJson(Type type, Object obj)  <br>
+ * Redkale提倡http+json的接口风格， 所以主要输出的数据格式为json， 同时提供异步接口。  <br>
 * <p>
 * 详情见: https://redkale.org
 *
--- a/src/org/redkale/net/http/RestMapping.java
+++ b/src/org/redkale/net/http/RestMapping.java
@@ -10,8 +10,8 @@ import static java.lang.annotation.ElementType.*;
 import static java.lang.annotation.RetentionPolicy.*;

 /**
- * 只能依附在Service实现类的public方法上
- * value默认为"/" + Service的类名去掉Service字样的小写字符串 (如HelloService，的默认路径为/hello)。
+ * 只能依附在Service实现类的public方法上  <br>
+ * value默认为"/" + Service的类名去掉Service字样的小写字符串 (如HelloService，的默认路径为/hello)。  <br>
 * <p>
 * 详情见: https://redkale.org
 *
--- a/src/org/redkale/net/http/RestParam.java
+++ b/src/org/redkale/net/http/RestParam.java
@@ -11,10 +11,10 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;

 /**
 *
- * 依附在RestService类的方法的参数上
- * name='&#38;' 表示当前用户
- * name='#'表示截取uri最后一段
- * name='#xxx:'表示从uri中/pipes/xxx:v/截取xxx:的值
+ * 依附在RestService类的方法的参数上  <br>
+ * name='&#38;' 表示当前用户  <br>
+ * name='#'表示截取uri最后一段  <br>
+ * name='#xxx:'表示从uri中/pipes/xxx:v/截取xxx:的值  <br>
 * <p>
 * 详情见: https://redkale.org
 *
@@ -28,10 +28,10 @@ public @interface RestParam {

    //name='&'表示当前用户;
    /**
-     * 参数名 
-     * name='&#38;'表示当前用户;
-     * name='#'表示截取uri最后一段;
-     * name='#xxx:'表示从uri中/pipes/xxx:v/截取xxx:的值
+     * 参数名   <br>
+     * name='&#38;'表示当前用户;  <br>
+     * name='#'表示截取uri最后一段;  <br>
+     * name='#xxx:'表示从uri中/pipes/xxx:v/截取xxx:的值  <br>
     *
     * @return String
     */    
--- a/src/org/redkale/net/sncp/SncpClient.java
+++ b/src/org/redkale/net/sncp/SncpClient.java
@@ -287,7 +287,7 @@ public final class SncpClient {
    }

    private SncpFuture<byte[]> remote0(final BsonConvert bsonConvert, final JsonConvert jsonConvert, final Transport transport, final SocketAddress addr0, final SncpAction action, final Object... params) {
-        if ("rest".equalsIgnoreCase(transport.getKind())) {
+        if ("rest".equalsIgnoreCase(transport.getSubprotocol())) {
            return remoteRest0(jsonConvert, transport, addr0, action, params);
        }
        return remoteSncp0(bsonConvert, transport, addr0, action, params);
--- a/src/org/redkale/service/RetLabel.java
+++ b/src/org/redkale/service/RetLabel.java
@@ -10,12 +10,12 @@ import java.lang.reflect.*;
 import java.util.*;

 /**
- * 用于定义错误码的注解
- * 结果码定义范围:
- *    // 10000001 - 19999999 预留给Redkale的核心包使用
- *    // 20000001 - 29999999 预留给Redkale的扩展包使用
- *    // 30000001 - 99999999 预留给Dev开发系统自身使用
- *
+ * 用于定义错误码的注解  <br>
+ * 结果码定义范围:  <br>
+ *    // 10000001 - 19999999 预留给Redkale的核心包使用  <br>
+ *    // 20000001 - 29999999 预留给Redkale的扩展包使用  <br>
+ *    // 30000001 - 99999999 预留给Dev开发系统自身使用  <br>
+ * <p>
 * 详情见: https://redkale.org
 *
 * @author zhangjx
--- a/src/org/redkale/service/RetResult.java
+++ b/src/org/redkale/service/RetResult.java
@@ -8,13 +8,13 @@ package org.redkale.service;
 import org.redkale.convert.json.*;

 /**
- * 通用的结果对象，在常见的HTTP+JSON接口中返回的结果需要含结果码，错误信息，和实体对象。
- * 通常前四位为模块，后四位为操作。
- * 结果码定义范围:
- *    // 10000001 - 19999999 预留给Redkale的核心包使用
- *    // 20000001 - 29999999 预留给Redkale的扩展包使用
- *    // 30000001 - 99999999 预留给Dev开发系统自身使用
- *
+ * 通用的结果对象，在常见的HTTP+JSON接口中返回的结果需要含结果码，错误信息，和实体对象。  <br>
+ * 结果码定义通常前四位为模块，后四位为操作。<br>
+ * 结果码定义范围:  <br>
+ *    // 10000001 - 19999999 预留给Redkale的核心包使用  <br>
+ *    // 20000001 - 29999999 预留给Redkale的扩展包使用  <br>
+ *    // 30000001 - 99999999 预留给Dev开发系统自身使用  <br>
+ * <p>
 * 详情见: https://redkale.org
 *
 * @author zhangjx
@@ -112,10 +112,20 @@ public class RetResult<T> {
        this.retcode = retcode;
    }

+    /**
+     * 结果信息，通常retcode != 0时值为错误信息
+     *
+     * @return 结果信息
+     */
    public String getRetinfo() {
        return retinfo;
    }

+    /**
+     * 设置结果信息
+     *
+     * @param retinfo 结果信息
+     */
    public void setRetinfo(String retinfo) {
        this.retinfo = retinfo;
    }
@@ -129,6 +139,11 @@ public class RetResult<T> {
        return result;
    }

+    /**
+     * 设置结果对象
+     *
+     * @param result T
+     */
    public void setResult(T result) {
        this.result = result;
    }