Merge pull request #4 from ELDEpendenci/develop

ELDependenci · May 11, 2022 · 2946c19 · 2946c19
2 parents abe4923 + 3bdc0f3
commit 2946c19
Show file tree

Hide file tree

Showing 21 changed files with 159 additions and 4 deletions.
diff --git a/eldependenci-rpc-plugin/pom.xml b/eldependenci-rpc-plugin/pom.xml
@@ -3,7 +3,7 @@
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <parent>
-        <artifactId>ELDependenci-RPC-module</artifactId>
+        <artifactId>eldependenci-rpc-module</artifactId>
         <groupId>org.eldependenci</groupId>
         <version>0.0.2</version>
     </parent>

diff --git a/eldependenci-rpc/pom.xml b/eldependenci-rpc/pom.xml
@@ -3,7 +3,7 @@
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <parent>
-        <artifactId>ELDependenci-RPC-module</artifactId>
+        <artifactId>eldependenci-rpc-module</artifactId>
         <groupId>org.eldependenci</groupId>
         <version>0.0.2</version>
     </parent>

diff --git a/eldependenci-rpc/src/main/java/org/eldependenci/rpc/RPCInstallation.java b/eldependenci-rpc/src/main/java/org/eldependenci/rpc/RPCInstallation.java
@@ -3,14 +3,35 @@
 import org.eldependenci.rpc.protocol.RPCRequester;
 import org.eldependenci.rpc.protocol.RPCServiceable;
 
+/**
+ * RPC 自定義安裝
+ */
 public interface RPCInstallation {
 
+    /**
+     * 註冊 Retrofit 服務
+     * @param services Retrofit 服務
+     */
     void retrofits(Class<?>... services);
 
+    /**
+     * 註冊 Remote 服務 (Consumer)
+     * @param services Remote 服務
+     */
     void remotes(Class<?>... services);
 
+    /**
+     * 註冊 Serve 服務 (Producer)
+     * @param serves Serve 服務
+     */
     void serves(Class<?>... serves);
 
+    /**
+     * 註冊新的 RPC 協定通訊
+     * @param protocolName 協定通訊名稱
+     * @param serviceable 協定通訊回應服務
+     * @param requester 協定通訊請求服務
+     */
     void registerProtocol(String protocolName, Class<? extends RPCServiceable> serviceable, Class<? extends RPCRequester> requester);
 
 

diff --git a/eldependenci-rpc/src/main/java/org/eldependenci/rpc/annotation/AuthorizationRequired.java b/eldependenci-rpc/src/main/java/org/eldependenci/rpc/annotation/AuthorizationRequired.java
@@ -5,6 +5,9 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * 啟用授權請求 (僅限 Serve 服務)
+ */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface AuthorizationRequired {

diff --git a/eldependenci-rpc/src/main/java/org/eldependenci/rpc/annotation/BaseURL.java b/eldependenci-rpc/src/main/java/org/eldependenci/rpc/annotation/BaseURL.java
@@ -5,6 +5,9 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Base URL (僅限 Retrofit 服務)
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
 public @interface BaseURL {

diff --git a/eldependenci-rpc/src/main/java/org/eldependenci/rpc/annotation/DoAsync.java b/eldependenci-rpc/src/main/java/org/eldependenci/rpc/annotation/DoAsync.java
@@ -5,6 +5,9 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * 是否啟用異步執行 (僅限 Serve 服務)
+ */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface DoAsync {

diff --git a/eldependenci-rpc/src/main/java/org/eldependenci/rpc/annotation/package-info.java b/eldependenci-rpc/src/main/java/org/eldependenci/rpc/annotation/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * 標註類
+ */
+package org.eldependenci.rpc.annotation;
diff --git a/eldependenci-rpc/src/main/java/org/eldependenci/rpc/context/RPCError.java b/eldependenci-rpc/src/main/java/org/eldependenci/rpc/context/RPCError.java
@@ -1,4 +1,10 @@
 package org.eldependenci.rpc.context;
 
+/**
+ * 錯誤協定
+ * @param code 錯誤代碼
+ * @param message 錯誤訊息
+ * @param errors 錯誤追蹤
+ */
 public record RPCError(int code, String message, String[] errors) {
 }
diff --git a/eldependenci-rpc/src/main/java/org/eldependenci/rpc/context/RPCException.java b/eldependenci-rpc/src/main/java/org/eldependenci/rpc/context/RPCException.java
@@ -1,18 +1,30 @@
 package org.eldependenci.rpc.context;
 
+/**
+ * RPC錯誤類
+ */
 public class RPCException extends Exception {
 
+
     private final long id;
     private final Exception real;
     public RPCException(long id, Exception e) {
         this.real = e;
         this.id = id;
     }
 
+    /**
+     *
+     * @return 真正的錯誤
+     */
     public Exception getReal() {
         return real;
     }
 
+    /**
+     *
+     * @return 追蹤 ID
+     */
     public long getId() {
         return id;
     }

diff --git a/eldependenci-rpc/src/main/java/org/eldependenci/rpc/context/RPCInfo.java b/eldependenci-rpc/src/main/java/org/eldependenci/rpc/context/RPCInfo.java
@@ -4,13 +4,14 @@
 import java.util.List;
 
 /**
- * RPC 遠端資訊
+ * RPC 遠端資訊, 認證 token 將在 Serve 服務啟用 {@link org.eldependenci.rpc.annotation.AuthorizationRequired} 的時候使用
  * @param locate Service Class 位置
  * @param host 遠端位址
  * @param protocol 遠端通訊協定
  * @param serviceName 遠端服務名稱, 如無則使用 Service Class 作為名稱
  * @param useTLS 是否使用 TLS
  * @param fallbackHosts 後備位址
+ * @param authToken 認證 Token (如果該 Serve 類別啟用了授權請求，則必須指定)
  */
 public record RPCInfo(
         String locate,
@@ -21,6 +22,12 @@ public record RPCInfo(
         List<FallbackHost> fallbackHosts
 ) {
 
+    /**
+     * 後備位址
+     * @param host 位址
+     * @param useTLS 是否使用 TLS
+     * @param authToken 認證 Token
+     */
     public record FallbackHost(String host, boolean useTLS, @Nullable String authToken){
     }
 

diff --git a/eldependenci-rpc/src/main/java/org/eldependenci/rpc/context/RPCPayload.java b/eldependenci-rpc/src/main/java/org/eldependenci/rpc/context/RPCPayload.java
@@ -2,6 +2,14 @@
 
 import javax.annotation.Nullable;
 
+/**
+ * RPC 傳入內容協定
+ * @param id 追蹤 ID
+ * @param method 方法名稱
+ * @param service 服務名稱
+ * @param parameters 參數
+ * @param token 認證 Token (由 {@link RPCInfo} 傳入)
+ */
 public record RPCPayload(long id, String method, String service, Object[] parameters, @Nullable String token) {
     public RPCPayload copyWithDiffToken(@Nullable String token) {
         return new RPCPayload(id, method, service, parameters, token);

diff --git a/eldependenci-rpc/src/main/java/org/eldependenci/rpc/context/RPCResponse.java b/eldependenci-rpc/src/main/java/org/eldependenci/rpc/context/RPCResponse.java
@@ -1,4 +1,11 @@
 package org.eldependenci.rpc.context;
 
+/**
+ * RPC 回傳內容協定
+ * @param id 追蹤 ID
+ * @param success 回傳是否成功
+ * @param result 回傳結果, {@link RPCResult} 或 {@link RPCError}
+ * @param <T> 回傳結果中的任一類型
+ */
 public record RPCResponse<T>(long id, boolean success, T result) {
 }
diff --git a/eldependenci-rpc/src/main/java/org/eldependenci/rpc/context/RPCResult.java b/eldependenci-rpc/src/main/java/org/eldependenci/rpc/context/RPCResult.java
@@ -1,4 +1,10 @@
 package org.eldependenci.rpc.context;
 
+/**
+ * RPC 標準回傳內容協定
+ * @param method 被使用方法名稱
+ * @param service 被使用服務名稱
+ * @param result 回傳結果
+ */
 public record RPCResult(String method, String service, Object result) {
 }
diff --git a/eldependenci-rpc/src/main/java/org/eldependenci/rpc/context/RPCUnauthorizedException.java b/eldependenci-rpc/src/main/java/org/eldependenci/rpc/context/RPCUnauthorizedException.java
@@ -1,7 +1,15 @@
 package org.eldependenci.rpc.context;
 
+/**
+ * 認證 token 授權錯誤時，用於 {@link org.eldependenci.rpc.annotation.AuthorizationRequired} 的 Serve 服務。
+ */
 public class RPCUnauthorizedException extends RPCException {
 
+    /**
+     *
+     * @param id 追蹤 ID
+     * @param e 原本錯誤
+     */
     public RPCUnauthorizedException(long id, Exception e) {
         super(id, e);
     }

diff --git a/eldependenci-rpc/src/main/java/org/eldependenci/rpc/context/package-info.java b/eldependenci-rpc/src/main/java/org/eldependenci/rpc/context/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * 協定型別類
+ */
+package org.eldependenci.rpc.context;
diff --git a/eldependenci-rpc/src/main/java/org/eldependenci/rpc/package-info.java b/eldependenci-rpc/src/main/java/org/eldependenci/rpc/package-info.java
@@ -1 +1,4 @@
+/**
+ * 主類
+ */
 package org.eldependenci.rpc;
diff --git a/eldependenci-rpc/src/main/java/org/eldependenci/rpc/protocol/RPCRequester.java b/eldependenci-rpc/src/main/java/org/eldependenci/rpc/protocol/RPCRequester.java
@@ -5,10 +5,23 @@
 
 import java.util.concurrent.CompletableFuture;
 
+/**
+ * 用於定義 新協定 (Protocol) 的 RPC 請求接口
+ */
 public interface RPCRequester {
 
+    /**
+     * 初始化 請求接口 (基於 Remote 服務)
+     * @param client RPC 資訊
+     */
     void initialize(RPCInfo client);
 
+    /**
+     * 執行 RPC 請求
+     * @param payload RPC 請求內容協定
+     * @return RPC 回應
+     * @throws Exception 請求錯誤
+     */
     CompletableFuture<Object> offerRequest(RPCPayload payload) throws Exception;
 
 }
diff --git a/eldependenci-rpc/src/main/java/org/eldependenci/rpc/protocol/RPCServiceable.java b/eldependenci-rpc/src/main/java/org/eldependenci/rpc/protocol/RPCServiceable.java
@@ -1,9 +1,19 @@
 package org.eldependenci.rpc.protocol;
 
+/**
+ * 用於 定義 新協定 (Protocol) 的 RPC 回應接口
+ */
 public interface RPCServiceable {
 
+    /**
+     * 啟動 Serve 服務
+     * @param handler 服務處理器
+     */
     void StartService(ServiceHandler handler);
 
+    /**
+     * 停止 Serve 服務
+     */
     void StopService();
 
 }
diff --git a/eldependenci-rpc/src/main/java/org/eldependenci/rpc/protocol/ServiceHandler.java b/eldependenci-rpc/src/main/java/org/eldependenci/rpc/protocol/ServiceHandler.java
@@ -5,16 +5,49 @@
 
 import java.lang.reflect.Type;
 
+/**
+ * 服務處理接口，用於傳入處理方法與參數
+ */
 public interface ServiceHandler {
 
+    /**
+     * 處理 RPC 請求
+     * @param payload 請求資料
+     * @return 處理結果
+     * @throws Exception 處理異常
+     */
     Response invokes(RPCPayload payload) throws Exception;
 
+    /**
+     * 轉換處理結果的型別
+     * @param result 處理結果
+     * @param returnType 處理方法的返回型別
+     * @return 轉換後的處理結果
+     * @throws Exception 轉換異常
+     */
     Object finalizeType(Object result, Type returnType) throws Exception;
 
+    /**
+     * 查看該 RPC 請求是否允許異步
+     * @param payload 請求資料
+     * @return 是否允許異步
+     * @throws Exception 查詢異常
+     */
     boolean shouldCallAsync(RPCPayload payload) throws Exception;
 
+    /**
+     * 將錯誤轉換為 RPC 錯誤回傳協定
+     * @param e 錯誤
+     * @param debug 是否啟用除錯, 若是，則會填入 {@link RPCError#errors() } 參數
+     * @return 錯誤回傳協定
+     */
     RPCError toRPCError(Exception e, boolean debug);
 
+    /**
+     * 處理結果的型別
+     * @param result 處理結果
+     * @param returnType 處理方法的返回型別
+     */
     record Response(Object result, Type returnType){
     }
 

diff --git a/eldependenci-rpc/src/main/java/org/eldependenci/rpc/protocol/package-info.java b/eldependenci-rpc/src/main/java/org/eldependenci/rpc/protocol/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * 通訊協定接口
+ */
+package org.eldependenci.rpc.protocol;
diff --git a/pom.xml b/pom.xml
@@ -5,7 +5,7 @@
     <modelVersion>4.0.0</modelVersion>
 
     <groupId>org.eldependenci</groupId>
-    <artifactId>ELDependenci-RPC-module</artifactId>
+    <artifactId>eldependenci-rpc-module</artifactId>
     <packaging>pom</packaging>
     <version>0.0.2</version>
     <modules>