refactor: Enhance code documentation and improve method visibility

Author: seymourtang

agora-rest-client-core/src/main/java/io/agora/rest/core/AgoraConfig.java

@@ -74,7 +74,7 @@ public Builder domainArea(DomainArea domainArea) {
             return this;
         }
 
-        private Builder httpProperty(HttpProperty httpProperty) {
+        public Builder httpProperty(HttpProperty httpProperty) {
             this.httpProperty = httpProperty;
             return this;
         }

agora-rest-client-core/src/main/java/io/agora/rest/core/BasicAuthCredential.java

@@ -2,6 +2,10 @@
 
 import io.netty.handler.codec.http.HttpHeaders;
 
+/**
+ * @brief BasicAuthCredential provides basic authentication for agora rest client
+ * @since v0.3.0
+ */
 public class BasicAuthCredential implements Credential {
 
     private final String username;
@@ -10,6 +14,10 @@ public class BasicAuthCredential implements Credential {
 
     private final static String name = "BasicAuth";
 
+    /**
+     * @param username Customer ID obtained from the Agora console
+     * @param password Customer secret obtained from the Agora console
+     */
     public BasicAuthCredential(String username, String password) {
         this.username = username;
         this.password = password;

agora-rest-client-core/src/main/java/io/agora/rest/core/DefaultContext.java

@@ -38,7 +38,8 @@ public <T> Mono<T> sendRequest(String path, HttpMethod method, Object requestBod
 
             return Mono.defer(() -> httpClient
                             .doOnRequest((req, conn) ->
-                                    logger.debug("request:{},{}{}", req.method(), req.requestHeaders().get("host"), req.uri()))
+                                    logger.debug("start request:{},{}", req.method(), req.resourceUrl())
+                            )
                             .headers(h -> h.add("Content-Type", "application/json"))
                             .request(method)
                             .uri(Mono.just(this.domainPool.getCurrentUrl() + path))
@@ -53,11 +54,16 @@ public <T> Mono<T> sendRequest(String path, HttpMethod method, Object requestBod
 
                                         return Mono.just(byteBuf);
                                     })
-                            ).map(buf -> {
-                                T response = codec.decode(buf, clazz);
-                                buf.release();
-                                logger.debug("response:{}", response);
-                                return response;
+                            ).flatMap(buf -> {
+                                if (clazz == Void.class) {
+                                    buf.release();
+                                    return Mono.empty();
+                                } else {
+                                    T response = codec.decode(buf, clazz);
+                                    buf.release();
+                                    logger.debug("response:{}", response);
+                                    return Mono.just(response);
+                                }
                             }))
                     .retryWhen(Retry.fixedDelay(3, Duration.ofMillis(500)).
                             filter(e -> e instanceof ChannelBindException || e instanceof UnknownHostException)

agora-rest-client-core/src/main/java/io/agora/rest/core/DefaultErrorMapper.java

@@ -36,10 +36,11 @@ public void checkError(ByteBuf buf) {
 
     public AgoraException convertException(HttpClientResponse response, ByteBuf buf) {
         HttpResponseStatus status = response.status();
+        String xRequestId = response.responseHeaders().get("x-request-id");
 
         byte[] body = ByteUtils.toByteArray(buf);
-        String reason = String.format("%s %s -> %d %s,body:%s", response.method(), response.uri(), status.code(),
-                status.reasonPhrase(), new String(body));
+        String reason = String.format("%s %s -> %d %s,body:%s,x-request-id:%s", response.method(), response.resourceUrl(), status.code(),
+                status.reasonPhrase(), new String(body), xRequestId);
         logger.info("reason:{}", reason);
 
         AgoraException exception = new AgoraUnknownException(reason);

agora-rest-client-core/src/main/java/io/agora/rest/core/DomainArea.java

@@ -4,35 +4,36 @@
 import java.util.Collections;
 import java.util.List;
 
-public enum DomainArea {
-    /**
-     * Unknown domain area
-     */
-    Unknown(Collections.emptyList(), Collections.emptyList()),
 
+/**
+ * @brief DomainArea represents the global regions where the Open API gateway endpoint is located
+ * @note Choose the appropriate area based on your service deployment region.
+ * @since v0.3.0
+ */
+public enum DomainArea {
     /**
-     * US domain area
+     * US represents the western and eastern regions of the United States
      */
     US(
             Arrays.asList("api-us-west-1", "api-us-east-1"),
             Arrays.asList("agora.io", "sd-rtn.com")),
 
     /**
-     * EU domain area
+     * EU represents the western and central regions of Europe
      */
     EU(
             Arrays.asList("api-eu-west-1", "api-eu-central-1"),
             Arrays.asList("agora.io", "sd-rtn.com")),
 
     /**
-     * AP domain area
+     * AP represents the southeastern and northeastern regions of Asia-Pacific
      */
     AP(
             Arrays.asList("api-ap-southeast-1", "api-ap-northeast-1"),
             Arrays.asList("agora.io", "sd-rtn.com")),
 
     /**
-     * CN domain area
+     * CN represents the eastern and northern regions of Chinese mainland
      */
     CN(
             Arrays.asList("api-cn-east-1", "api-cn-north-1"),

agora-rest-client-core/src/main/java/io/agora/rest/core/DomainPool.java

@@ -31,7 +31,7 @@ public class DomainPool {
     private final Logger logger = LoggerFactory.getLogger(DomainPool.class);
 
     public DomainPool(DomainArea domainArea) {
-        if (domainArea == null || domainArea == DomainArea.Unknown) {
+        if (domainArea == null) {
             throw new AgoraInvalidArgumentException("invalid domain area");
         }
 

agora-rest-client-core/src/main/java/io/agora/rest/core/HttpClientFactory.java

@@ -6,6 +6,7 @@
 import org.slf4j.LoggerFactory;
 import reactor.netty.http.client.HttpClient;
 import reactor.netty.resources.ConnectionProvider;
+import reactor.netty.transport.logging.AdvancedByteBufFormat;
 
 import java.time.Duration;
 
@@ -36,7 +37,7 @@ public static HttpClient createHttpClient(AgoraConfig agoraConfig) {
                         agoraConfig.getCredential().setAuthorization(h);
                     }
                 })
-                .wiretap("io.agora.rest.core.http", LogLevel.DEBUG, agoraConfig.getHttpProperty().getHttpLogFormat())
+                .wiretap("io.agora.rest.core.http", LogLevel.DEBUG, AdvancedByteBufFormat.SIMPLE)
                 .doOnRequestError((req, t) -> logger.error("request error:{}", t.getMessage()));
 
     }

agora-rest-client-core/src/main/java/io/agora/rest/core/HttpProperty.java

@@ -1,23 +1,41 @@
 package io.agora.rest.core;
 
-import reactor.netty.transport.logging.AdvancedByteBufFormat;
-
+/**
+ * @brief HttpProperty represents the properties of the HTTP client
+ * @since v0.3.0
+ */
 public class HttpProperty {
 
+    /**
+     * Maximum number of connections in the connection pool
+     */
     private final int httpConnectionPoolSize;
 
+    /**
+     * Maximum idle time of a connection in the connection pool, unit: ms
+     */
     private final int httpConnectionMaxIdleTime;
 
+    /**
+     * Maximum lifetime of a connection in the connection pool，unit: ms
+     */
     private final int httpConnectionMaxLifeTime;
 
+    /**
+     * Time to evict connections in the background, unit: ms
+     */
     private final int httpConnectionEvictInBackground;
 
+    /**
+     * Timeout for acquiring a connection from the connection pool, unit: ms
+     */
     private final int httpConnectionPendingAcquireTimout;
 
+    /**
+     * The maximum number of registered requests for acquire to keep in a pending queue
+     */
     private final int httpConnectionPendingAcquireMaxCount;
 
-    private final AdvancedByteBufFormat httpLogFormat;
-
     public static Builder builder() {
         return new Builder();
     }
@@ -29,7 +47,6 @@ private HttpProperty(Builder builder) {
         httpConnectionEvictInBackground = builder.httpConnectionEvictInBackground;
         httpConnectionPendingAcquireTimout = builder.httpConnectionPendingAcquireTimout;
         httpConnectionPendingAcquireMaxCount = builder.httpConnectionPendingAcquireMaxCount;
-        httpLogFormat = builder.httpLogFormat;
     }
 
     public int getHttpConnectionPoolSize() {
@@ -56,10 +73,6 @@ public int getHttpConnectionPendingAcquireMaxCount() {
         return httpConnectionPendingAcquireMaxCount;
     }
 
-    public AdvancedByteBufFormat getHttpLogFormat() {
-        return httpLogFormat;
-    }
-
     @Override
     public String toString() {
         return "HttpProperty{" +
@@ -69,10 +82,10 @@ public String toString() {
                 ", httpConnectionEvictInBackground=" + httpConnectionEvictInBackground +
                 ", httpConnectionPendingAcquireTimout=" + httpConnectionPendingAcquireTimout +
                 ", httpConnectionPendingAcquireMaxCount=" + httpConnectionPendingAcquireMaxCount +
-                ", httpLogFormat=" + httpLogFormat +
                 '}';
     }
 
+
     public static final class Builder {
         private int httpConnectionPoolSize = 50;
 
@@ -86,8 +99,6 @@ public static final class Builder {
 
         private int httpConnectionPendingAcquireMaxCount = 100;
 
-        private AdvancedByteBufFormat httpLogFormat = AdvancedByteBufFormat.SIMPLE;
-
         private Builder() {
 
         }
@@ -122,11 +133,6 @@ public Builder httpConnectionPendingAcquireMaxCount(int val) {
             return this;
         }
 
-        public Builder httpLogFormat(AdvancedByteBufFormat val) {
-            httpLogFormat = val;
-            return this;
-        }
-
         public HttpProperty build() {
             return new HttpProperty(this);
         }