OTSClient is a client for Tablestore. OTSClient provides various methods that you can use to manage tables and perform read and write operations on a single row or multiple rows. Before you can use Tablestore SDK for Java to send a request, you must initialize an OTSClient instance and modify the default configurations of ClientConfiguration. Before you can use the TimeSeries model, you must initialize the TimeseriesClient.

Obtain an endpoint

An endpoint is a domain name that is used to access a Tablestore instance in a region. The following table describes the examples of endpoints in the supported formats.

Example Description
http://sun.cn-hangzhou.ots.aliyuncs.com The public endpoint that is used to access the sun instance in the China (Hangzhou) region over HTTP.
https://sun.cn-hangzhou.ots.aliyuncs.com The public endpoint that is used to access the sun instance in the China (Hangzhou) region over HTTPS.
Notice You can connect to Tablestore by using public endpoints or private endpoints. For more information, see Endpoint.

To query the endpoints of your Tablestore instance, perform the following steps:

  1. Log on to the Tablestore console.
  2. Click the name of the instance to go to the Instance Details tab.
    On the Instance Details tab, you can view the endpoints of the instance in the Instance Access URL section.

Configure an AccessKey pair

Before you can connect to Tablestore, you must have an AccessKey pair that consists of an AccessKey ID and an AccessKey secret. The AccessKey pair is used to verify your identity. Tablestore supports the following types of AccessKey pairs:

  • The AccessKey pair of an Alibaba Cloud account. To obtain the AccessKey pair of an Alibaba Cloud account, perform the following steps:
    1. On the Alibaba Cloud official website, register an Alibaba Cloud account.
    2. Create an AccessKey pair in the RAM console.
  • The AccessKey pair of a RAM user that is authorized to access Tablestore. To obtain the AccessKey pair of a RAM user, perform the following steps:
    1. Log on to the RAM console by using an Alibaba Cloud account. Then, create a RAM user or find an existing RAM user.
    2. Grant the RAM user the permissions to access Tablestore.
    3. After the RAM user is granted the permissions to access Tablestore, you can use the AccessKey pair of the RAM user to access Tablestore.
  • Temporary access credentials that are obtained from Security Token Service (STS). The following process shows how temporary access credentials are obtained from STS:
    1. The application server uses RAM or STS to obtain access credentials that consist of a temporary AccessKey ID, an AccessKey secret, and a token, and then sends the access credentials to you.
    2. You can use the access credentials to access Tablestore.

Initialize a client

If you want to use the Tablestore SDK, you must create a client and call the operations in the client to access Tablestore. The operations in the client provide the same functions as the RESTful APIs provided by Tablestore.

The Tablestore SDK provides the following clients: SyncClient and AsyncClient. SyncClient contains synchronous operations and AsyncClient contains asynchronous operations. If you call a synchronous operation, the operation directly returns a response, which indicates that the request is executed. You can call synchronous operations to obtain information about various features of Tablestore. Compared with synchronous operations, asynchronous operations are more flexible. Asynchronous operations provide higher performance than multithreading. You can choose asynchronous operations or multithreading based on your business requirements.

Note SyncClient and AsyncClient are thread-safe. You can use the clients to manage internal threads and connection resources. We recommend that you create a global client. This way, you do not need to create a client for each thread or request.

After you obtain the AccessKey ID and AccessKey secret, you can perform the following steps to initialize a client:

  • Use the default configurations to create a SyncClient
    final String endPoint = ""; 
    final String accessKeyId = ""; 
    final String accessKeySecret = ""; 
    final String instanceName = "";
    SyncClient client = new SyncClient(endPoint, accessKeyId, accessKeySecret, instanceName);                        
  • Use the custom configurations to create a SyncClient
    // ClientConfiguration provides multiple configuration items. Only the most commonly used items are listed. 
    ClientConfiguration clientConfiguration = new ClientConfiguration();
    // Set the timeout until a connection is established. Unit: milliseconds. 
    clientConfiguration.setConnectionTimeoutInMillisecond(5000);
    // Specify a timeout period for the socket connection. Unit: milliseconds. 
    clientConfiguration.setSocketTimeoutInMillisecond(5000);
    // Configure a retry policy. If you do not configure a retry policy, the default retry policy is used. 
    clientConfiguration.setRetryStrategy(new AlwaysRetryStrategy());
    SyncClient client = new SyncClient(endPoint, accessId, accessKey, instanceName, clientConfiguration);

Initialize the TimeseriesClient

If you want to use the TimeSeries model, you must initialize the TimeseriesClient.

The Tablestore SDK provides the TimeseriesClient and AsyncTimeseriesClient methods. You can use the TimeseriesClient method for synchronous operations the AsyncTimeseriesClient method for asynchronous operations.

After you obtain the AccessKey ID and AccessKey secret, you can perform the following steps to initialize the TimeseriesClient:

  • Use the default configurations to create a TimeseriesClient
    final String endPoint = "";
    final String accessKeyId = "";
    final String accessKeySecret = "";
    final String instanceName = "";
    TimeseriesClient client = new TimeseriesClient(endPoint, accessKeyId, accessKeySecret, instanceName);
  • Use the custom configurations to create a TimeseriesClient
    // ClientConfiguration provides multiple configuration items. Only the most commonly used items are listed. 
    ClientConfiguration clientConfiguration = new ClientConfiguration();
    // Set the timeout until a connection is established. Unit: milliseconds. 
    clientConfiguration.setConnectionTimeoutInMillisecond(5000);
    // Specify a timeout period for the socket connection. Unit: milliseconds. 
     clientConfiguration.setSocketTimeoutInMillisecond(5000);
    // Configure a retry policy. If you do not configure a retry policy, the default retry policy is used. 
    clientConfiguration.setRetryStrategy(new AlwaysRetryStrategy());
    TimeseriesClient client = new TimeseriesClient(endPoint, accessId, accessKey, instanceName, clientConfiguration);

HTTPS

Upgrade to Java 7 for connection based on HTTPS.

Multithreading

  • Multithreading is supported.
  • We recommend that you use the same OTSClient object to run multithreading tasks.