diff --git a/eldependenci-rpc-plugin/pom.xml b/eldependenci-rpc-plugin/pom.xml index 8014aef..91437f0 100644 --- 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"> - ELDependenci-RPC-module + eldependenci-rpc-module org.eldependenci 0.0.2 diff --git a/eldependenci-rpc/pom.xml b/eldependenci-rpc/pom.xml index e2e65ef..c0cfbfd 100644 --- 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"> - ELDependenci-RPC-module + eldependenci-rpc-module org.eldependenci 0.0.2 diff --git a/eldependenci-rpc/src/main/java/org/eldependenci/rpc/RPCInstallation.java b/eldependenci-rpc/src/main/java/org/eldependenci/rpc/RPCInstallation.java index 3447c2f..b83ee72 100644 --- 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 serviceable, Class 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 index 192238c..d1ba563 100644 --- 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 index 4963d32..11ae166 100644 --- 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 index d032de7..81f99c4 100644 --- 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 new file mode 100644 index 0000000..a6bb1a1 --- /dev/null +++ b/eldependenci-rpc/src/main/java/org/eldependenci/rpc/annotation/package-info.java @@ -0,0 +1,4 @@ +/** + * 標註類 + */ +package org.eldependenci.rpc.annotation; \ No newline at end of file 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 index 2359419..06abbbb 100644 --- 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 index d32b809..39656b5 100644 --- 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,7 +1,11 @@ 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) { @@ -9,10 +13,18 @@ public RPCException(long id, Exception 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 index 609ccc1..5c88d11 100644 --- 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 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 index 346ea13..e9e439b 100644 --- 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 index b0530b4..c36c136 100644 --- 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 回傳結果中的任一類型 + */ public record RPCResponse(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 index 71ab2af..cc3cc2e 100644 --- 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 index c874156..faad1ad 100644 --- 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 new file mode 100644 index 0000000..e52a855 --- /dev/null +++ b/eldependenci-rpc/src/main/java/org/eldependenci/rpc/context/package-info.java @@ -0,0 +1,4 @@ +/** + * 協定型別類 + */ +package org.eldependenci.rpc.context; \ No newline at end of file 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 index a2197eb..345c5b5 100644 --- 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; \ No newline at end of file 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 index 97a5dfe..1305471 100644 --- 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 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 index 88f2b8b..ad61786 100644 --- 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 index de10f1e..7bce9dc 100644 --- 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 new file mode 100644 index 0000000..312d34c --- /dev/null +++ b/eldependenci-rpc/src/main/java/org/eldependenci/rpc/protocol/package-info.java @@ -0,0 +1,4 @@ +/** + * 通訊協定接口 + */ +package org.eldependenci.rpc.protocol; \ No newline at end of file diff --git a/pom.xml b/pom.xml index aae405d..af2c99f 100644 --- a/pom.xml +++ b/pom.xml @@ -5,7 +5,7 @@ 4.0.0 org.eldependenci - ELDependenci-RPC-module + eldependenci-rpc-module pom 0.0.2