Initialize an OTSClient instance by using Tablestore SDK for Java - Tablestore

OTSClient is a Tablestore client that provides various methods for you to manage tables and perform read and write operations on one or more rows. If you want to use the Wide Column model to manage data tables and perform read and write operations on one or more rows, you must initialize an OTSClient instance and modify the default settings of the configuration items in OTSClientConfig based on your business requirements. If you want to use the TimeSeries model to manage time series tables, query time series, and read and write time series data, you must initialize a TimeseriesClient instance.

Usage notes

If you want to access Tablestore resources over HTTPS, use Java 7.
Tablestore SDK for Java supports multithreading. We recommend that you use the same OTSClient object to run multiple threads of a task.

Preparations

Before you initialize an OTSClient instance, you must configure an AccessKey pair, obtain an endpoint, and install Tablestore SDK for Java.

Configure an AccessKey pair

To access Tablestore, you must have a valid AccessKey pair to verify your identity. The following table describes three methods that you can use to obtain an AccessKey pair. To ensure the security of your AccessKey pair, we recommend that you configure the AccessKey pair in the environment variables of your operating system.

Obtain an AccessKey pair.

Important

To prevent security risks caused by the leak of the AccessKey pair of your Alibaba Cloud account, we recommend that you create a RAM user that has the permissions to access Tablestore and use the AccessKey pair of the RAM user to access Tablestore.

Method	Procedure
AccessKey pair of an Alibaba Cloud account	Create an Alibaba Cloud account on the Alibaba Cloud official website. Create an AccessKey pair that consists of an AccessKey ID and an AccessKey secret. For more information, see Create an AccessKey pair.
AccessKey pair of a RAM user that has the permissions to access Tablestore	Log on to the RAM console with an Alibaba Cloud account. Then, create a RAM user or find an existing RAM user. Use the Alibaba Cloud account to grant access permissions on Tablestore to the RAM user. For more information, see Use a RAM policy to grant permissions to a RAM user. Use the AccessKey pair of the RAM user to access Tablestore. For more information, see Create an AccessKey pair.
Temporary access credentials that are obtained from Security Token Service (STS)	Obtain temporary access credentials from the application server. The temporary access credentials consist of a temporary AccessKey ID, a temporary AccessKey secret, and a security token. The application server accesses RAM or STS to obtain the temporary access credentials and returns the temporary access credentials to you. Use the temporary access credentials to access Tablestore.

Run the following command to configure environment variables:
Tablestore uses the OTS_AK_ENV and OTS_SK_ENV environment variables to store an AccessKey pair. The OTS_AK_ENV environment variable stores the AccessKey ID of an Alibaba Cloud account or a RAM user. The OTS_SK_ENV environment variable stores the AccessKey secret of an Alibaba Cloud account or a RAM user. Configure the environment variables based on the AccessKey pair that you want to use.
Important
After you configure the environment variables, you may need to restart the relevant services or development tools such as Integrated Development Environment (IDE) to ensure that the new settings are applied as expected.
Configure environment variables in Windows
You can configure environment variables by using the GUI, Command Prompt, or Windows PowerShell. For more information, see Configure environment variables in Linux, macOS, and Windows.
Use the GUI
In the System Variable section of the Environment Variable dialog box, add the OTS_AK_ENV and OTS_SK_ENV environment variables, and set the OTS_AK_ENV environment variable to the AccessKey ID and the OTS_SK_ENV environment variable to the AccessKey secret that you obtained. Then, save the configurations.
Use the Command Prompt
Open a Command Prompt window as an administrator and run the following commands to add environment variables in the operating system: In the preceding commands, /M specifies system variables.
setx OTS_AK_ENV LT******************** /M setx OTS_SK_ENV Ir**************************** /M
After you configure the environment variables, run the echo %OTS_AK_ENV% and echo %OTS_SK_ENV% commands to check whether the environment variables take effect. If the correct AccessKey pair is returned, the environment variables take effect.
Use Windows PowerShell
Start Windows PowerShell as an administrator.
Run the following commands in PowerShell to configure environment variables:
[System.Environment]::SetEnvironmentVariable('OTS_AK_ENV', 'LT********************', [System.EnvironmentVariableTarget]::Machine) [System.Environment]::SetEnvironmentVariable('OTS_SK_ENV', 'Ir****************************', [System.EnvironmentVariableTarget]::Machine)
Restart PowerShell and run the following commands in PowerShell to check whether the environment variables take effect:
If the correct AccessKey pair is returned, the environment variables take effect.
Get-ChildItem env:OTS_AK_ENV Get-ChildItem env:OTS_SK_ENV
Configure environment variables in Linux and macOS
Note
The first time you configure environment variables, you can use the touch ~/.bash_profile command to create a configuration file. If a configuration file already exists, you can use the vim ~/.bash_profile command to edit the file.
1. Create a file named .bash_profile.
```
touch ~/.bash_profile
vim ~/.bash_profile
```
2. Configure environment variables in the .bash_profile file. Then, save the settings and exit the configuration file.
```
# In the following command, replace <ACCESS_KEY_ID> with the AccessKey ID you obtained and <ACCESS_KEY_SECRET> with the AccessKey secret you obtained. 
export OTS_AK_ENV=<ACCESS_KEY_ID>
export OTS_SK_ENV=<ACCESS_KEY_SECRET>
```
3. Make the configurations in the .bash_profile configuration file take effect and check whether the configurations take effect.
```
# Make the configurations in the configuration file take effect.
source ~/.bash_profile
# Check whether the configurations take effect.
echo $ALIBABA_CLOUD_ACCESS_KEY_ID
```
  If the correct AccessKey ID is returned, the configurations take effect.

Obtain an endpoint of a Tablestore instance

After you create a Tablestore instance, you must obtain an endpoint of the instance. This way, you can use the endpoint to access the instance.

An endpoint is a domain name that is used to access a Tablestore instance in a region. For example, https://sun.cn-hangzhou.ots.aliyuncs.com is the public endpoint that is used to access the instance named sun in the China (Hangzhou) region over HTTPS. For more information, see Endpoints.

Important

You can access Tablestore by using public and internal endpoints.

If the Tablestore service is not activated, activate the service. For more information, see Step 1: Activate Tablestore.
Create a Tablestore instance. For more information, see Step 2: Create an instance.
Obtain an endpoint of the created instance.
1. Log on to the Tablestore console.
2. On the Overview page, find the instance that you created and click the name of the instance.
3. On the Instance Details tab, view the endpoints of the instance in the Instance Access URL section.

Install Tablestore SDK for Java

For more information, see Install Tablestore SDK for Java.

Initialize a client

If you want to use the Wide Column model by using Tablestore SDK for Java, you must create a client and call the operations in the client to access Tablestore. The operations in the client provide the same features as the RESTful API operations provided by Tablestore.

Tablestore SDK for Java provides the following clients: SyncClient and AsyncClient. SyncClient contains synchronous operations whereas 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 get started with various features of Tablestore. Compared with synchronous operations, asynchronous operations are more flexible. Multithreading provides higher performance than asynchronous operations. You can select 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.

The following examples show how to initiate a SyncClient after you obtain an AccessKey ID and an AccessKey secret.

Important

The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. We recommend that you use the AccessKey pair of a RAM user to call API operations or perform routine O&M. We recommend that you do not hard-code the AccessKey ID and AccessKey secret into your project code. Otherwise, the AccessKey pair may be leaked and the security of all resources in your account is compromised. In the following examples, the AccessKey pair is configured in the environment variables to verify your identity.

To ensure the security of your AccessKey pair, we recommend that you use the V4 signature algorithm to initialize client instances.

Note

For more information about how to use the V4 signature algorithm, see AccessKey pair security.

Use the V4 signature algorithm

Tablestore SDK for Java V5.16.1 and later support the V4 signature algorithm. Before you use the V4 signature algorithm, make sure that the SDK that you use supports this algorithm.

String region = "";
String endPoint = "";
String accessKeyId = System.getenv("OTS_AK_ENV");
String accessKeySecret = System.getenv("OTS_SK_ENV");
String instanceName = "";
/**
 * Construct V4 signature credentials. 
 */
DefaultCredentials credentials = new DefaultCredentials(accessKeyId, accessKeySecret);
V4Credentials credentialsV4 = V4Credentials.createByServiceCredentials(credentials, region);
CredentialsProvider provider = new DefaultCredentialProvider(credentialsV4);
/**
 * Use V4 signature credentials to construct the OTSClient instance. 
 */
SyncClient client = new SyncClient(endPoint, provider, instanceName, null, new ResourceManager(null, null));

The following table describes the parameters.

Parameter	Example	Description
region	cn-hangzhou	The ID of the region in which the instance resides. For more information, see Regions.
endPoint	https://myinstance.cn-hangzhou.ots.aliyuncs.com	The endpoint that is used to access the Tablestore instance. For more information, see Obtain an endpoint of a Tablestore instance.
accessKeyId	System.getenv("OTS_AK_ENV")	The AccessKey pair that is used to access the Tablestore instance. Obtain the AccessKey pair by using environment variables. Make sure that the relevant environment variables are configured. For more information, see Configure an AccessKey pair.
accessKeySecret	System.getenv("OTS_SK_ENV")
instanceName	myinstance	The name of the Tablestore instance that you want to access. For more information, see Instances.

Use methods other than the V4 signature algorithm

You can use the default or custom configurations when you create a SyncClient.

Use the default configurations to create a SyncClient

final String endPoint = ""; 
String accessKeyId = System.getenv("OTS_AK_ENV");
String accessKeySecret = System.getenv("OTS_SK_ENV");
final String instanceName = "";
SyncClient client = new SyncClient(endPoint, accessKeyId, accessKeySecret, instanceName);

The following table describes the parameters.

Parameter	Example	Description
endPoint	https://myinstance.cn-hangzhou.ots.aliyuncs.com	The endpoint that is used to access the Tablestore instance. For more information, see Obtain an endpoint of a Tablestore instance.
accessKeyId	System.getenv("OTS_AK_ENV")	The AccessKey pair that is used to access the Tablestore instance. Obtain the AccessKey pair by using environment variables. Make sure that the relevant environment variables are configured. For more information, see Configure an AccessKey pair.
accessKeySecret	System.getenv("OTS_SK_ENV")
instanceName	myinstance	The name of the Tablestore instance that you want to access. For more information, see Instances.

Use custom configurations to create a SyncClient

// ClientConfiguration provides multiple configuration items. Only the most commonly used items are displayed. 
ClientConfiguration clientConfiguration = new ClientConfiguration();
// Specify a timeout period for establishing a connection. 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, accessKeyId, accessKeySecret, instanceName, clientConfiguration);

Initialize a TimeseriesClient instance

If you want to use the TimeSeries model by using Tablestore SDK for Java, you must create a TimeseriesClient instance and call the operations of the TimeseriesClient instance to access Tablestore. The TimeseriesClient instance must be separately initialized for the TimeSeries model.

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

The following examples show how to initialize a TimeseriesClient instance after you obtain an AccessKey ID and an AccessKey secret.

Use the default configurations to create a TimeseriesClient instance

final String endPoint = "";
String accessKeyId = System.getenv("OTS_AK_ENV");
String accessKeySecret = System.getenv("OTS_SK_ENV");
final String instanceName = "";
TimeseriesClient client = new TimeseriesClient(endPoint, accessKeyId, accessKeySecret, instanceName);

The following table describes the parameters.

Parameter	Example	Description
endPoint	https://myinstance.cn-hangzhou.ots.aliyuncs.com	The endpoint that is used to access the Tablestore instance. For more information, see Obtain an endpoint of a Tablestore instance.
accessKeyId	System.getenv("OTS_AK_ENV")	The AccessKey pair that is used to access the Tablestore instance. Obtain the AccessKey pair by using environment variables. Make sure that the relevant environment variables are configured. For more information, see Configure an AccessKey pair.
accessKeySecret	System.getenv("OTS_SK_ENV")
instanceName	myinstance	The name of the Tablestore instance that you want to access. For more information, see Instances.

Use custom configurations to create a TimeseriesClient instance

// ClientConfiguration provides multiple configuration items. Only the most commonly used items are displayed. 
ClientConfiguration clientConfiguration = new ClientConfiguration();
// Specify a timeout period for establishing a connection. 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, accessKeyId, accessKeySecret, instanceName, clientConfiguration);

Tablestore:Initialize an OTSClient instance

Usage notes

Preparations

Configure an AccessKey pair

Configure environment variables in Windows

Use the GUI

Use the Command Prompt

Use Windows PowerShell

Configure environment variables in Linux and macOS

Obtain an endpoint of a Tablestore instance

Install Tablestore SDK for Java

Initialize a client

Use the V4 signature algorithm

Use methods other than the V4 signature algorithm

Initialize a TimeseriesClient instance

Use the default configurations to create a TimeseriesClient instance

Use custom configurations to create a TimeseriesClient instance

FAQ