表格存储 Java SDK 初始化 TunnelClient - 表格存储

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	表格存储实例的访问地址。使用与客户端网络环境匹配的公网、VPC 或经典网 Endpoint。
credsProvider（必选）	CredentialsProvider	访问凭证提供器。示例使用 AccessKey ID、AccessKey Secret 和实例所属地域 ID 构造 V4 签名凭证。
instanceName（必选）	String	表格存储实例名称。
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();
}