Skip to main content
Version: 3.12
Features and pricing

Write a ScalarDL Application with TableStore

This document explains how to write ScalarDL applications with TableStore. You will learn how to interact with ScalarDL TableStore in your applications, handle errors, and validate your data.

Use the ScalarDL TableStore Client SDK​

You have two options to interact with ScalarDL TableStore:

Using commands is a convenient way to try TableStore without writing an application. For building TableStore-based applications, however, the TableStore Client SDK is recommended, as it runs more efficiently without launching a separate process for each operation.

The TableStore Client SDK is available on Maven Central. You can install it in your application by using a build tool such as Gradle. For example, in Gradle, you can add the following dependency to build.gradle, replacing VERSION with the version of ScalarDL that you want to use.

dependencies {
    implementation group: 'com.scalar-labs', name: 'scalardl-tablestore-java-client-sdk', version: '<VERSION>'
}

The Client SDK APIs for TableStore are provided by a service class called TableStoreClientService. The following is a code snippet that shows how to use TableStoreClientService to manage table authenticity. TableStoreClientService provides the same functionalities as the TableStore client commands shown in Get Started with ScalarDL TableStore.

  // TableStoreClientServiceFactory should always be reused.
  TableStoreClientServiceFactory factory = new TableStoreClientServiceFactory();

  // TableStoreClientServiceFactory creates a new TableStoreClientService object in every create
  // method call but reuses the internal objects and connections as much as possible for better
  // performance and resource usage.
  TableStoreClientService service = factory.create(new ClientConfig(new File(properties)));
  try {
    // execute a SQL statement.
    String sql = "SELECT * FROM employee WHERE id = '1001'";
    ExecutionResult result = service.executeStatement(sql);
    result.getResult().ifPresent(System.out::println);
  } catch (ClientException e) {
    System.err.println(e.getStatusCode());
    System.err.println(e.getMessage());
  }

  factory.close();
note

You should always use TableStoreClientServiceFactory to create TableStoreClientService objects. TableStoreClientServiceFactory caches objects that are required to create TableStoreClientService and reuses them on the basis of the given configurations, so the TableStoreClientServiceFactory object should always be reused.

For more information about TableStoreClientServiceFactory and TableStoreClientService, see the scalardl-tablestore-java-client-sdk Javadoc.

Handle errors​

If an error occurs in your application, the Client SDK will return an exception with a status code and an error message with an error code. You should check the status code and the error code to identify the cause of the error. For details about the status code and the error codes, see Status codes and Error codes.

Implement error handling​

The SDK throws ClientException when an error occurs. You can handle errors by catching the exception as follows:

TableStoreClientService service = ...;
try {
    // interact with ScalarDL TableStore through a TableStoreClientService object
} catch (ClientException e) {
    // e.getStatusCode() returns the status of the error
}

Validate your data​

In ScalarDL, you occasionally need to validate your data to make sure all the data is in a valid state. Since you can learn the basics of how ScalarDL validates your data in Write a ScalarDL Application in Java, this section mainly describes how you can perform the validation in TableStore.

When validating assets (records, index records, and table schema here) in TableStore, you need to specify a table and a primary or index key if necessary. An example code for validating assets in TableStore is as follows:

  TableStoreClientService service = ...
  String tableName = "employee";
  String primaryKeyColumn = "id";
  String indexKeyColumn = "department";
  TextNode primaryKeyValue = TextNode.valueOf("1001");
  TextNode indexKeyValue = TextNode.valueOf("sales");
  try {
    LedgerValidationResult result1 =
        service.validateRecord(tableName, primaryKeyColumn, primaryKeyValue);
    LedgerValidationResult result2 =
        service.validateIndexRecord(tableName, indexKeyColumn, indexKeyValue);
    LedgerValidationResult result3 = service.validateTableSchema(tableName);
    // You can also specify age range.
    // LedgerValidationResult result1 =
    //     service.validateRecord(tableName, primaryKeyColumn, primaryKeyValue, startAge, endAge);
    // LedgerValidationResult result2 =
    //     service.validateIndexRecord(tableName, indexKeyColumn, indexKeyValue, startAge, endAge);
    // LedgerValidationResult result3 = service.validateTableSchema(tableName, startAge, endAge);
  } catch (ClientException e) {
  }
note

TableStore internally assigns a dedicated asset ID to an asset that represents a record, an index record, and a table schema. The asset ID consists of a prefix to show the asset type and a key; for example, a prefix rec_, a primary key column name, and a primary key value are used for asset IDs of records. You will see such raw asset IDs in AssetProof in LedgerValidationResult.