Table Store Java SDK 初始化 TunnelClient - Tablestore

Java SDK 使用專用用戶端管理通道和啟動資料消費。初始化時需配置執行個體名稱、Endpoint 和訪問憑證。

前提條件

安裝 Tablestore Java SDK 並配置訪問憑證。以下樣本使用 V4 簽名，需要 5.17.5 及以上版本。

功能說明

TunnelClient 是通道服務的專用用戶端，通道管理介面和資料消費任務均通過該用戶端訪問服務。在同一業務進程內複用用戶端執行個體，完成所有通道操作後調用 shutdown 關閉用戶端。

使用以下構造方法初始化 TunnelClient：

public TunnelClient(
    String endpoint,
    CredentialsProvider credsProvider,
    String instanceName,
    ClientConfiguration config,
    ResourceManager resourceManager
)

以下樣本使用預設用戶端配置和獨佔資源管理員初始化 TunnelClient，並針對已有資料表調用唯讀 listTunnel 方法，以驗證 Endpoint、訪問憑證和網路連接。運行前，根據執行個體資訊設定 region、instanceName 和 endpoint，並將 tableName 設定為用於連通性驗證的已有寬表名稱。

import com.alicloud.openservices.tablestore.TunnelClient;
import com.alicloud.openservices.tablestore.core.auth.CredentialsProvider;
import com.alicloud.openservices.tablestore.core.auth.DefaultCredentialProvider;
import com.alicloud.openservices.tablestore.core.auth.DefaultCredentials;
import com.alicloud.openservices.tablestore.core.auth.V4Credentials;
import com.alicloud.openservices.tablestore.model.tunnel.ListTunnelRequest;
import com.alicloud.openservices.tablestore.model.tunnel.ListTunnelResponse;

public class InitTunnelClient {

    public static void main(String[] args) {
        String accessKeyId = System.getenv("TABLESTORE_ACCESS_KEY_ID");
        String accessKeySecret = System.getenv("TABLESTORE_ACCESS_KEY_SECRET");
        String region = "<region-id>";
        String instanceName = "<instance-name>";
        String endpoint = "<instance-endpoint>";
        String tableName = "<table-name>";

        TunnelClient tunnelClient = null;
        try {
            DefaultCredentials credentials = new DefaultCredentials(accessKeyId, accessKeySecret);
            V4Credentials credentialsV4 = V4Credentials.createByServiceCredentials(credentials, region);
            CredentialsProvider provider = new DefaultCredentialProvider(credentialsV4);

            tunnelClient = new TunnelClient(
                endpoint,
                provider,
                instanceName,
                null,
                null
            );

            ListTunnelResponse response = tunnelClient.listTunnel(new ListTunnelRequest(tableName));
            System.out.println("TunnelClient initialized. Tunnels: " + response.getTunnelInfos().size());
            System.out.println("RequestId: " + response.getRequestId());
        } finally {
            if (tunnelClient != null) {
                tunnelClient.shutdown();
            }
        }
    }
}

參數說明

用戶端

TunnelClient 構造方法包含以下參數。

名稱	類型	說明
endpoint（必選）	String	Table Store執行個體的訪問地址。使用與用戶端網路環境匹配的公網、VPC 或經典網 Endpoint。
credsProvider（必選）	CredentialsProvider	訪問憑證提供器。樣本使用 AccessKey ID、AccessKey Secret 和執行個體所屬地區 ID 構造 V4 簽名憑證。
instanceName（必選）	String	Table Store執行個體名稱。
config（可選）	ClientConfiguration	用戶端配置。設定為 `null` 時使用預設配置。需要調整串連、逾時或重試策略時傳入自訂配置。
resourceManager（可選）	ResourceManager	用戶端資源管理員，用於管理串連和線程資源。設定為 `null` 時由當前用戶端建立和釋放。多個用戶端需要共用底層資源時傳入共用資源管理器。

用戶端配置

config 的類型為 ClientConfiguration。通過對應的 setXxx 方法配置用戶端的串連、逾時和重試策略；無需自訂時傳入 null。常用配置如下。

名稱	類型	說明
maxConnections（可選）	int	允許開啟的最大 HTTP 串連數。預設值為 `300`。
ioThreadCount（可選）	int	HTTP 非同步用戶端的 I/O 線程數。預設值為當前運行環境可用的處理器數量。
connectionTimeoutInMillisecond（可選）	int	建立串連的逾時時間，單位為毫秒。預設值為 `30000`。
socketTimeoutInMillisecond（可選）	int	通過已建立串連傳輸資料的逾時時間，單位為毫秒。預設值為 `30000`。
connectionRequestTimeoutInMillisecond（可選）	int	從串連池擷取串連的逾時時間，單位為毫秒。預設值為 `-1`，表示不單獨設定。
retryThreadCount（可選）	int	執行錯誤重試的線程數。預設值為 `1`。
retryStrategy（可選）	RetryStrategy	請求重試策略。預設值為 `DefaultRetryStrategy`。

代理、壓縮、DNS 緩衝、鏈路追蹤和 SSL 會話等其他用戶端配置，也通過 ClientConfiguration 的對應方法設定。

資源管理員

resourceManager 的類型為 ResourceManager。獨立使用 TunnelClient 時傳入 null，用戶端會根據 config 建立資源管理員，並在調用 shutdown 時釋放資源。

需要自訂或共用資源時，可通過 ResourceManager(ClientConfiguration configuration, ExecutorService callbackExecutor) 構造擁有資源的 ResourceManager，構造參數如下。

名稱	類型	說明
configuration（可選）	ClientConfiguration	建立 HTTP 串連和重試線程時使用的用戶端配置。設定為 `null` 時使用預設配置。
callbackExecutor（可選）	ExecutorService	執行非同步回調的線程池。設定為 `null` 時由 SDK 建立預設線程池。擁有資源的 `ResourceManager` 關閉時，該線程池也會關閉。

情境樣本

自訂用戶端配置

如需調整預設的串連、逾時或重試配置，在基礎樣本中匯入 ClientConfiguration，並使用以下代碼替換用戶端初始化代碼。

ClientConfiguration config = new ClientConfiguration();
config.setMaxConnections(200);
config.setConnectionTimeoutInMillisecond(10000);
config.setSocketTimeoutInMillisecond(30000);
config.setRetryThreadCount(2);

tunnelClient = new TunnelClient(
    endpoint,
    provider,
    instanceName,
    config,
    null
);

共用用戶端資源

多個用戶端需要共用 HTTP 串連、重試線程和回調線程時，建立一個擁有資源的 ResourceManager，並將其 sharedResourceManager() 方法返回的共用執行個體傳給各用戶端。關閉所有用戶端後，再關閉擁有資源的 ResourceManager。

重要

不要將擁有資源的 ResourceManager 直接傳給多個用戶端，否則任一用戶端調用 shutdown 都會釋放共用資源。

以下程式碼片段複用基礎樣本中的變數和訪問憑證提供器。運行前需匯入 ClientConfiguration 和 ResourceManager。

ClientConfiguration config = new ClientConfiguration();
ResourceManager owner = new ResourceManager(config);
TunnelClient tunnelClientA = new TunnelClient(
    endpoint, provider, instanceName, config, owner.sharedResourceManager());
TunnelClient tunnelClientB = new TunnelClient(
    endpoint, provider, instanceName, config, owner.sharedResourceManager());

try {
    tunnelClientA.listTunnel(new ListTunnelRequest(tableName));
    tunnelClientB.listTunnel(new ListTunnelRequest(tableName));
} finally {
    tunnelClientA.shutdown();
    tunnelClientB.shutdown();
    owner.shutdown();
}