Tablestore SDK for Java - Tablestore - Alibaba Cloud Documentation Center

The Tablestore SDK for Java supports wide column, timeseries, and message model operations.

Quick integration

Integrate the Tablestore SDK for Java, from environment setup to client verification.

Prepare the environment

Install the Java runtime (Java 6 or later). Run java -version to verify.

Install the SDK

Use the latest SDK version to ensure code examples run correctly.

Add a Maven dependency (Recommended)

To use the Tablestore SDK for Java in a Maven project, add the following dependency to your pom.xml file.

<dependency>
    <groupId>com.aliyun.openservices</groupId>
    <artifactId>tablestore</artifactId>
    <version>5.17.7</version>
</dependency>

Import JAR packages into an Eclipse project

For non-Maven projects, import the JAR packages manually.

Download the Java SDK package.
Unzip the package.
In Eclipse, right-click your project and choose Properties > Java Build Path > Libraries > Add External JARs.
Select the tablestore-5.17.7.jar file and all JAR files in the lib folder from the unzipped package, then click Open.
Verify the JAR packages appear under Libraries, then click Apply and Close.

Note
If you use Java SE 9 or later, you must import the JAR packages to Modulepath under Libraries.

Configure access credentials

Create an AccessKey for your Alibaba Cloud account or RAM user, then configure it as an environment variable to avoid hard-coding credentials.

Restart your IDE, terminal, other desktop applications, and background services after configuration to load the updated environment variables. For more information about other types of access credentials, see Configure access credentials.

Linux

Append the environment variables to ~/.bashrc:

echo "export TABLESTORE_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
echo "export TABLESTORE_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc

Apply the changes:
```
source ~/.bashrc
```

Verify the environment variables:

echo $TABLESTORE_ACCESS_KEY_ID
echo $TABLESTORE_ACCESS_KEY_SECRET

macOS

Check your default shell:
```
echo $SHELL
```

Configure based on your shell type:

Zsh

Append the environment variables to ~/.zshrc:

echo "export TABLESTORE_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc
echo "export TABLESTORE_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc

Apply the changes:
```
source ~/.zshrc
```

Verify the environment variables:

echo $TABLESTORE_ACCESS_KEY_ID
echo $TABLESTORE_ACCESS_KEY_SECRET

Bash

Append the environment variables to ~/.bash_profile:

echo "export TABLESTORE_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile
echo "export TABLESTORE_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile

Apply the changes:
```
source ~/.bash_profile
```

Verify the environment variables:

echo $TABLESTORE_ACCESS_KEY_ID
echo $TABLESTORE_ACCESS_KEY_SECRET

Windows

CMD

Set the environment variables in CMD:

setx TABLESTORE_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
setx TABLESTORE_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

Restart CMD and verify:

echo %TABLESTORE_ACCESS_KEY_ID%
echo %TABLESTORE_ACCESS_KEY_SECRET%

PowerShell

Run in PowerShell:

[Environment]::SetEnvironmentVariable("TABLESTORE_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
[Environment]::SetEnvironmentVariable("TABLESTORE_ACCESS_KEY_SECRET", "YOUR_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

Verify the environment variables:

[Environment]::GetEnvironmentVariable("TABLESTORE_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
[Environment]::GetEnvironmentVariable("TABLESTORE_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

Initialize the client

Initialize a synchronous client with a V4 signature and verify the connection by listing data tables.

The client is thread-safe and automatically manages internal thread pools and connection resources. Share a single instance across threads instead of creating one per thread or request.

Important

Public network access is disabled by default for new instances. To access an instance over the Internet, enable it on the Network Management page.

Wide column model

import com.alicloud.openservices.tablestore.SyncClient;
import com.alicloud.openservices.tablestore.core.ResourceManager;
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.ListTableResponse;

public class SyncClientV4 {
    
    public static void main(String[] args) {
        
        // Obtain access credentials from environment variables. You must configure TABLESTORE_ACCESS_KEY_ID and TABLESTORE_ACCESS_KEY_SECRET.
        final String accessKeyId = System.getenv("TABLESTORE_ACCESS_KEY_ID");
        final String accessKeySecret = System.getenv("TABLESTORE_ACCESS_KEY_SECRET");

        // TODO: Modify the following configurations as needed.
        final String region = "cn-hangzhou"; // Specify the region ID of the instance, for example, "cn-hangzhou".
        final String instanceName = "n01k********"; // Specify the instance name.
        final String endpoint = "https://n01k********.cn-hangzhou.ots.aliyuncs.com"; // Specify the instance endpoint.

        SyncClient client = null;
        try {
            // Construct credentials.
            DefaultCredentials credentials = new DefaultCredentials(accessKeyId, accessKeySecret);
            V4Credentials credentialsV4 = V4Credentials.createByServiceCredentials(credentials, region);
            CredentialsProvider provider = new DefaultCredentialProvider(credentialsV4);

            // Create a client instance.
            client = new SyncClient(endpoint, provider, instanceName, null, new ResourceManager(null, null));

            // List all data tables.
            ListTableResponse listTableResponse = client.listTable();

            // Print the list of data tables.
            System.out.println("Found " + listTableResponse.getTableNames().size() + " data tables in instance '" + instanceName + "':");

            listTableResponse.getTableNames().forEach(System.out::println);
        } catch (Exception e) {
            System.err.println("Failed to list data tables. Details:");
            e.printStackTrace();
        } finally {
            // Shut down the client.
            if (client != null) {
                client.shutdown();
            }
        }
    }
}

Timeseries model

import com.alicloud.openservices.tablestore.TimeseriesClient;
import com.alicloud.openservices.tablestore.core.ResourceManager;
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.timeseries.ListTimeseriesTableResponse;

public class TimeseriesSyncClientV4 {
    
    public static void main(String[] args) {
        
        // Obtain access credentials from environment variables. You must configure TABLESTORE_ACCESS_KEY_ID and TABLESTORE_ACCESS_KEY_SECRET.
        final String accessKeyId = System.getenv("TABLESTORE_ACCESS_KEY_ID");
        final String accessKeySecret = System.getenv("TABLESTORE_ACCESS_KEY_SECRET");

        // TODO: Modify the following configurations as needed.
        final String region = "cn-hangzhou"; // Specify the region ID of the instance, for example, "cn-hangzhou".
        final String instanceName = "n01k********"; // Specify the instance name.
        final String endpoint = "https://n01k********.cn-hangzhou.ots.aliyuncs.com"; // Specify the instance endpoint.

        TimeseriesClient client = null;
        try {
            // Construct V4 signature credentials.
            DefaultCredentials credentials = new DefaultCredentials(accessKeyId, accessKeySecret);
            V4Credentials credentialsV4 = V4Credentials.createByServiceCredentials(credentials, region);
            CredentialsProvider provider = new DefaultCredentialProvider(credentialsV4);

            // Create a timeseries client instance.
            client = new TimeseriesClient(endpoint, provider, instanceName, null, new ResourceManager(null, null));

            // List all timeseries tables.
            ListTimeseriesTableResponse listTimeseriesTableResponse = client.listTimeseriesTable();

            // Print the list of timeseries tables.
            System.out.println("Found " + listTimeseriesTableResponse.getTimeseriesTableNames().size() + " timeseries tables in instance '" + instanceName + "':");

            listTimeseriesTableResponse.getTimeseriesTableNames().forEach(System.out::println);
        } catch (Exception e) {
            System.err.println("Failed to list timeseries tables. Details:");
            e.printStackTrace();
        } finally {
            // Shut down the client.
            if (client != null) {
                client.shutdown();
            }
        }
    }
}

Client configuration

The Tablestore SDK for Java supports synchronous and asynchronous clients. The asynchronous client offers higher throughput for concurrent workloads.

Asynchronous client

The asynchronous client uses callbacks to process results without blocking threads.

Wide column model

import com.alicloud.openservices.tablestore.AsyncClient;
import com.alicloud.openservices.tablestore.TableStoreCallback;
import com.alicloud.openservices.tablestore.core.ResourceManager;
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.ListTableRequest;
import com.alicloud.openservices.tablestore.model.ListTableResponse;

import java.util.concurrent.*;

public class AsyncClientV4 {
    
    public static void main(String[] args) {
        
        // Obtain access credentials from environment variables. You must configure TABLESTORE_ACCESS_KEY_ID and TABLESTORE_ACCESS_KEY_SECRET.
        final String accessKeyId = System.getenv("TABLESTORE_ACCESS_KEY_ID");
        final String accessKeySecret = System.getenv("TABLESTORE_ACCESS_KEY_SECRET");

        // TODO: Modify the following configurations as needed.
        final String region = "cn-hangzhou"; // Specify the region ID of the instance, for example, "cn-hangzhou".
        final String instanceName = "n01k********"; // Specify the instance name.
        final String endpoint = "https://n01k********.cn-hangzhou.ots.aliyuncs.com"; // Specify the instance endpoint.

        AsyncClient client = null;
        try {
            // Construct V4 signature credentials.
            DefaultCredentials credentials = new DefaultCredentials(accessKeyId, accessKeySecret);
            V4Credentials credentialsV4 = V4Credentials.createByServiceCredentials(credentials, region);
            CredentialsProvider provider = new DefaultCredentialProvider(credentialsV4);

            // Create an asynchronous client instance.
            client = new AsyncClient(endpoint, provider, instanceName, null, new ResourceManager(null, null));

            // Use CompletableFuture for asynchronous processing.
            CompletableFuture<ListTableResponse> future = new CompletableFuture<>();

            // Process the asynchronous result in the callback.
            client.listTable(new TableStoreCallback<ListTableRequest, ListTableResponse>() {
                @Override
                public void onCompleted(ListTableRequest req, ListTableResponse res) {
                    System.out.println("Asynchronous request completed successfully.");
                    future.complete(res); // Complete the Future when the asynchronous operation is successful.
                }
                @Override
                public void onFailed(ListTableRequest req, Exception ex) {
                    System.err.println("Asynchronous request failed.");
                    future.completeExceptionally(ex); // Complete the Future with an exception when the asynchronous operation fails.
                }
            });

            System.out.println("Asynchronous listTable request sent. Waiting for result...");

            // Block and wait for the result, and set a timeout.
            // In practice, continue to execute other non-blocking tasks or pass the future to other processes.
            ListTableResponse response = future.get(5, TimeUnit.SECONDS);

            // Process the successful result in the main thread.
            System.out.println("Found " + response.getTableNames().size() + " data tables in instance '" + instanceName + "':");
            response.getTableNames().forEach(System.out::println);
        } catch (Exception e) {
            System.err.println("Failed to list data tables. Details:");
            e.printStackTrace();
        } finally {
            // Shut down the client.
            if (client != null) {
                client.shutdown();
            }
        }
    }
}

Timeseries model

import com.alicloud.openservices.tablestore.AsyncTimeseriesClient;
import com.alicloud.openservices.tablestore.TableStoreCallback;
import com.alicloud.openservices.tablestore.core.ResourceManager;
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.timeseries.ListTimeseriesTableRequest;
import com.alicloud.openservices.tablestore.model.timeseries.ListTimeseriesTableResponse;

import java.util.concurrent.*;

public class TimeseriesAsyncClientV4 {
    
    public static void main(String[] args) {
        
        // Obtain access credentials from environment variables. You must configure TABLESTORE_ACCESS_KEY_ID and TABLESTORE_ACCESS_KEY_SECRET.
        final String accessKeyId = System.getenv("TABLESTORE_ACCESS_KEY_ID");
        final String accessKeySecret = System.getenv("TABLESTORE_ACCESS_KEY_SECRET");

        // TODO: Modify the following configurations as needed.
        final String region = "cn-hangzhou"; // Specify the region ID of the instance, for example, "cn-hangzhou".
        final String instanceName = "n01k********"; // Specify the instance name.
        final String endpoint = "https://n01k********.cn-hangzhou.ots.aliyuncs.com"; // Specify the instance endpoint.

        AsyncTimeseriesClient client = null;
        try {
            // Construct V4 signature credentials.
            DefaultCredentials credentials = new DefaultCredentials(accessKeyId, accessKeySecret);
            V4Credentials credentialsV4 = V4Credentials.createByServiceCredentials(credentials, region);
            CredentialsProvider provider = new DefaultCredentialProvider(credentialsV4);

            // Create an asynchronous timeseries client instance.
            client = new AsyncTimeseriesClient(endpoint, provider, instanceName, null, new ResourceManager(null, null));

            // Use CompletableFuture for asynchronous processing.
            CompletableFuture<ListTimeseriesTableResponse> future = new CompletableFuture<>();

            // Process the asynchronous result in the callback.
            client.listTimeseriesTable(new TableStoreCallback<ListTimeseriesTableRequest, ListTimeseriesTableResponse>() {
                @Override
                public void onCompleted(ListTimeseriesTableRequest req, ListTimeseriesTableResponse res) {
                    System.out.println("Asynchronous request completed successfully.");
                    future.complete(res); // Complete the Future when the asynchronous operation is successful.
                }
                @Override
                public void onFailed(ListTimeseriesTableRequest req, Exception ex) {
                    System.err.println("Asynchronous request failed.");
                    future.completeExceptionally(ex); // Complete the Future with an exception when the asynchronous operation fails.
                }
            });

            System.out.println("Asynchronous listTimeseriesTable request sent. Waiting for result...");

            // Block and wait for the result, and set a timeout.
            // In a real-world application, you can continue to execute other non-blocking tasks or pass the future to other processes.
            ListTimeseriesTableResponse response = future.get(5, TimeUnit.SECONDS);

            // Process the successful result in the main thread.
            if (response.getTimeseriesTableNames() != null) {
                System.out.println("Found " + response.getTimeseriesTableNames().size() + " timeseries tables in instance '" + instanceName + "':");
                response.getTimeseriesTableNames().forEach(System.out::println);
            }
        } catch (Exception e) {
            System.err.println("Failed to list timeseries tables. Details:");
            e.printStackTrace();
        } finally {
            // Shut down the client.
            if (client != null) {
                client.shutdown();
            }
        }
    }
}

Signature version

V4 signatures, available since SDK 5.16.1, use a stronger encryption algorithm and signing mechanism for improved security. Upgrade to V4 if possible. The following code shows V2 signature initialization.

Wide column model

Sync

import com.alicloud.openservices.tablestore.SyncClient;
import com.alicloud.openservices.tablestore.core.ResourceManager;
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.model.ListTableResponse;

public class SyncClientV2 {
    
    public static void main(String[] args) {
        
        // Obtain access credentials from environment variables. You must configure TABLESTORE_ACCESS_KEY_ID and TABLESTORE_ACCESS_KEY_SECRET.
        final String accessKeyId = System.getenv("TABLESTORE_ACCESS_KEY_ID");
        final String accessKeySecret = System.getenv("TABLESTORE_ACCESS_KEY_SECRET");

        // TODO: Modify the following configurations as needed.
        final String instanceName = "n01k********"; // Specify the instance name.
        final String endpoint = "https://n01k********.cn-hangzhou.ots.aliyuncs.com"; // Specify the instance endpoint.

        SyncClient client = null;
        try {
            // Construct V2 signature credentials.
            DefaultCredentials credentials = new DefaultCredentials(accessKeyId, accessKeySecret);
            CredentialsProvider provider = new DefaultCredentialProvider(credentials);

            // Create a client instance.
            client = new SyncClient(endpoint, provider, instanceName, null, new ResourceManager(null, null));

            // List all data tables.
            ListTableResponse listTableResponse = client.listTable();

            // Print the list of data tables.
            System.out.println("Found " + listTableResponse.getTableNames().size() + " data tables in instance '" + instanceName + "':");

            listTableResponse.getTableNames().forEach(System.out::println);
        } catch (Exception e) {
            System.err.println("Failed to list data tables. Details:");
            e.printStackTrace();
        } finally {
            // Shut down the client.
            if (client != null) {
                client.shutdown();
            }
        }
    }
}

Asynchronous

import com.alicloud.openservices.tablestore.AsyncClient;
import com.alicloud.openservices.tablestore.TableStoreCallback;
import com.alicloud.openservices.tablestore.core.ResourceManager;
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.model.ListTableRequest;
import com.alicloud.openservices.tablestore.model.ListTableResponse;

import java.util.concurrent.*;

public class AsyncClientV2 {
    
    public static void main(String[] args) {
        
        // Obtain access credentials from environment variables. You must configure TABLESTORE_ACCESS_KEY_ID and TABLESTORE_ACCESS_KEY_SECRET.
        final String accessKeyId = System.getenv("TABLESTORE_ACCESS_KEY_ID");
        final String accessKeySecret = System.getenv("TABLESTORE_ACCESS_KEY_SECRET");

        // TODO: Modify the following configurations as needed.
        final String instanceName = "n01k********"; // Specify the instance name.
        final String endpoint = "https://n01k********.cn-hangzhou.ots.aliyuncs.com"; // Specify the instance endpoint.

        AsyncClient client = null;
        try {
            // Construct V2 signature credentials.
            DefaultCredentials credentials = new DefaultCredentials(accessKeyId, accessKeySecret);
            CredentialsProvider provider = new DefaultCredentialProvider(credentials);

            // Create an asynchronous client instance.
            client = new AsyncClient(endpoint, provider, instanceName, null, new ResourceManager(null, null));

            // Use CompletableFuture for asynchronous processing.
            CompletableFuture<ListTableResponse> future = new CompletableFuture<>();

            // Process the asynchronous result in the callback.
            client.listTable(new TableStoreCallback<ListTableRequest, ListTableResponse>() {
                @Override
                public void onCompleted(ListTableRequest req, ListTableResponse res) {
                    System.out.println("Asynchronous request completed successfully.");
                    future.complete(res); // Complete the Future when the asynchronous operation is successful.
                }
                @Override
                public void onFailed(ListTableRequest req, Exception ex) {
                    System.err.println("Asynchronous request failed.");
                    future.completeExceptionally(ex); // Complete the Future with an exception when the asynchronous operation fails.
                }
            });

            System.out.println("Asynchronous listTable request sent. Waiting for result...");

            // Block and wait for the result, and set a timeout.
            // In practice, continue to execute other non-blocking tasks or pass the future to other processes.
            ListTableResponse response = future.get(5, TimeUnit.SECONDS);

            // Process the successful result in the main thread.
            System.out.println("Found " + response.getTableNames().size() + " data tables in instance '" + instanceName + "':");
            response.getTableNames().forEach(System.out::println);
        } catch (Exception e) {
            System.err.println("Failed to list data tables. Details:");
            e.printStackTrace();
        } finally {
            // Shut down the client.
            if (client != null) {
                client.shutdown();
            }
        }
    }
}

Timeseries model

Sync

import com.alicloud.openservices.tablestore.TimeseriesClient;
import com.alicloud.openservices.tablestore.core.ResourceManager;
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.model.timeseries.ListTimeseriesTableResponse;

public class TimeseriesSyncClientV2 {
    
    public static void main(String[] args) {
        
        // Obtain access credentials from environment variables. You must configure TABLESTORE_ACCESS_KEY_ID and TABLESTORE_ACCESS_KEY_SECRET.
        final String accessKeyId = System.getenv("TABLESTORE_ACCESS_KEY_ID");
        final String accessKeySecret = System.getenv("TABLESTORE_ACCESS_KEY_SECRET");

        // TODO: Modify the following configurations as needed.
        final String instanceName = "n01k********"; // Specify the instance name.
        final String endpoint = "https://n01k********.cn-hangzhou.ots.aliyuncs.com"; // Specify the instance endpoint.

        TimeseriesClient client = null;
        try {
            // Construct V2 signature credentials.
            DefaultCredentials credentials = new DefaultCredentials(accessKeyId, accessKeySecret);
            CredentialsProvider provider = new DefaultCredentialProvider(credentials);

            // Create a timeseries client instance.
            client = new TimeseriesClient(endpoint, provider, instanceName, null, new ResourceManager(null, null));

            // List all timeseries tables.
            ListTimeseriesTableResponse listTimeseriesTableResponse = client.listTimeseriesTable();

            // Print the list of timeseries tables.
            System.out.println("Found " + listTimeseriesTableResponse.getTimeseriesTableNames().size() + " timeseries tables in instance '" + instanceName + "':");

            listTimeseriesTableResponse.getTimeseriesTableNames().forEach(System.out::println);
        } catch (Exception e) {
            System.err.println("Failed to list timeseries tables. Details:");
            e.printStackTrace();
        } finally {
            // Shut down the client.
            if (client != null) {
                client.shutdown();
            }
        }
    }
}

Asynchronous

import com.alicloud.openservices.tablestore.AsyncTimeseriesClient;
import com.alicloud.openservices.tablestore.TableStoreCallback;
import com.alicloud.openservices.tablestore.core.ResourceManager;
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.model.timeseries.ListTimeseriesTableRequest;
import com.alicloud.openservices.tablestore.model.timeseries.ListTimeseriesTableResponse;

import java.util.concurrent.*;

public class TimeseriesAsyncClientV2 {
    
    public static void main(String[] args) {
        
        // Obtain access credentials from environment variables. You must configure TABLESTORE_ACCESS_KEY_ID and TABLESTORE_ACCESS_KEY_SECRET.
        final String accessKeyId = System.getenv("TABLESTORE_ACCESS_KEY_ID");
        final String accessKeySecret = System.getenv("TABLESTORE_ACCESS_KEY_SECRET");

        // TODO: Modify the following configurations as needed.
        final String instanceName = "n01k********"; // Specify the instance name.
        final String endpoint = "https://n01k********.cn-hangzhou.ots.aliyuncs.com"; // Specify the instance endpoint.

        AsyncTimeseriesClient client = null;
        try {
            // Construct V2 signature credentials.
            DefaultCredentials credentials = new DefaultCredentials(accessKeyId, accessKeySecret);
            CredentialsProvider provider = new DefaultCredentialProvider(credentials);

            // Create an asynchronous timeseries client instance.
            client = new AsyncTimeseriesClient(endpoint, provider, instanceName, null, new ResourceManager(null, null));

            // Use CompletableFuture for asynchronous processing.
            CompletableFuture<ListTimeseriesTableResponse> future = new CompletableFuture<>();

            // Process the asynchronous result in the callback.
            client.listTimeseriesTable(new TableStoreCallback<ListTimeseriesTableRequest, ListTimeseriesTableResponse>() {
                @Override
                public void onCompleted(ListTimeseriesTableRequest req, ListTimeseriesTableResponse res) {
                    System.out.println("Asynchronous request completed successfully.");
                    future.complete(res); // Complete the Future when the asynchronous operation is successful.
                }
                @Override
                public void onFailed(ListTimeseriesTableRequest req, Exception ex) {
                    System.err.println("Asynchronous request failed.");
                    future.completeExceptionally(ex); // Complete the Future with an exception when the asynchronous operation fails.
                }
            });

            System.out.println("Asynchronous listTimeseriesTable request sent. Waiting for result...");

            // Block and wait for the result, and set a timeout.
            // In practice, continue to execute other non-blocking tasks or pass the future to other processes.
            ListTimeseriesTableResponse response = future.get(5, TimeUnit.SECONDS);

            // Process the successful result in the main thread.
            if (response.getTimeseriesTableNames() != null) {
                System.out.println("Found " + response.getTimeseriesTableNames().size() + " timeseries tables in instance '" + instanceName + "':");
                response.getTimeseriesTableNames().forEach(System.out::println);
            }
        } catch (Exception e) {
            System.err.println("Failed to list timeseries tables. Details:");
            e.printStackTrace();
        } finally {
            // Shut down the client.
            if (client != null) {
                client.shutdown();
            }
        }
    }
}

Version compatibility

The latest version is 5.x.x. Compatibility with earlier versions:

The 4.x.x series SDKs are compatible.
Tablestore SDK for Java V2.x.x: incompatible

FAQ

What do I do if a PB library dependency conflict occurs when I use the SDK?

If java.lang.ExceptionInInitializerError occurs, your project likely has a Protocol Buffers (PB) library dependency conflict. Resolve it by following PB library conflicts when using the Java SDK.

What do I do if a "Signature mismatch" exception occurs when I use the SDK?

The following exception occurs:

Error Code: OTSAuthFailed, Message: Signature mismatch., RequestId: 0005f55a-xxxx-xxxx-xxxx-xxxxxxxxxxxx, TraceId: 10b0f0e0-xxxx-xxxx-xxxx-xxxxxxxxxxxx, HttpStatus: 403

Cause: The AccessKey ID or AccessKey secret is incorrect.
Solution: Provide the correct AccessKey ID and AccessKey secret.

What do I do if a "Request denied by instance ACL policies" exception occurs when I use the SDK?

The SDK may return a Request denied by instance ACL policies error:

[ErrorCode]:OTSAuthFailed, [Message]:Request denied by instance ACL policies., [RequestId]:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX, [TraceId]:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX, [HttpStatus:]403

Cause: The client's network type does not match the instance's access policy. For example, the instance does not allow Internet access.
Solution: Public network access is disabled by default. To enable it:
1. In the Tablestore console, click the target instance.
2. Click Network Management. For Allowed Network Type, select Internet, and then click Settings.

What do I do if a "Request denied because this instance can only be accessed from the binded VPC" exception occurs when I use the SDK?

The SDK may return a Request denied because this instance can only be accessed from the bound VPC error:

[ErrorCode]:OTSAuthFailed, [Message]:Request denied because this instance can only be accessed from the binded VPC., [RequestId]:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX, [TraceId]:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX, [HttpStatus:]403

Cause: The instance access type is set to Bound VPCs Only or Tablestore Console or Bound VPCs, but the client is not in an attached VPC or is not accessing Tablestore using a VPC endpoint.
Solution: Either allow Internet access, or attach a VPC and connect the client from within it:
1. In the Tablestore console, click the target instance.
2. Click Network Management > Bind VPC. Select a VPC ID and a VSwitch, enter a VPC Name, and then click OK.

What do I do if a SocketTimeoutException occurs when I use the SDK?

Client timeouts can result from network failures, jitter, high server load, or a full GC. Check network connectivity, server latency, and GC activity. What do I do if a SocketTimeoutException occurs when I use the Java SDK to access Tablestore?.

What do I do if a "The access key id is invalid" exception occurs when I use the SDK?

The following exception occurs when you use the SDK:

java.lang.IllegalArgumentException: The access key id is invalid:xxx.

Cause: The AccessKey, which includes the AccessKey ID and AccessKey secret, is incorrect or contains an invalid character.
Solution: Provide the correct AccessKey information.

What do I do if a "java.lang.IllegalStateException: Request cannot be executed; I/O reactor status: STOPPED" exception occurs when I use the SDK?

The following exception occurs when you use the SDK:

java.lang.IllegalStateException: Request cannot be executed; I/O reactor status: STOPPED

Cause: The shutDown method was already called, closing the client's I/O reactors.
Solution: After shutDown, re-initialize the client. A shutDown client cannot serve new requests.

Tablestore:Java SDK

Quick integration

Prepare the environment

Install the SDK

Add a Maven dependency (Recommended)

Import JAR packages into an Eclipse project

Configure access credentials

Linux

macOS

Zsh

Bash

Windows

CMD

PowerShell

Initialize the client

Wide column model

Timeseries model

Client configuration

Asynchronous client

Wide column model

Timeseries model

Signature version

Wide column model

Sync

Asynchronous

Timeseries model

Sync

Asynchronous

Version compatibility

FAQ

What do I do if a PB library dependency conflict occurs when I use the SDK?

What do I do if a "Signature mismatch" exception occurs when I use the SDK?

What do I do if a "Request denied by instance ACL policies" exception occurs when I use the SDK?

What do I do if a "Request denied because this instance can only be accessed from the binded VPC" exception occurs when I use the SDK?

What do I do if a SocketTimeoutException occurs when I use the SDK?

What do I do if a "The access key id is invalid" exception occurs when I use the SDK?

What do I do if a "java.lang.IllegalStateException: Request cannot be executed; I/O reactor status: STOPPED" exception occurs when I use the SDK?

References