DistributedStorage (ScalarDB)

All Superinterfaces:

java.lang.AutoCloseable

All Known Implementing Classes:

AbstractDistributedStorage, Cassandra, Cosmos, Dynamo, GrpcStorage, JdbcDatabase, MultiStorage, StorageService
```
public interface DistributedStorage
extends java.lang.AutoCloseable
```
A storage abstraction for interacting with distributed storage implementations. The user can execute CRUD operations to the storage by passing Operation commands such as Get, Scan, Put and Delete, which specify the location of storage entries and optional information.
The data model behind this abstraction is a multi-dimensional map based on key-value data model. A logical record (or entry) is composed of partition key, clustering key and a set of columns. The column value is uniquely mapped by a primary key composed of partition key, clustering key and column name as described in the following scheme.
(partition key, clustering key, column name) => column value
The physical data model is a multi-dimensional map distributed to multiple nodes by key-based hash partitioning. Entries are assumed to be hash-partitioned by partition key (even though an underlying implementation supports range partitioning). Records with the same partition key, which we call a partition, are sorted by clustering key. Thus, each entry in the storage can be located with the partition key and the clustering key, which we call it primary key. Both a partition key and a clustering key also comprise a list of values. Having clustering key is optional, so in that case, primary key is composed of only partition key.
Usage Examples
Here is a simple example to demonstrate how to use them. (Exception handling is omitted for readability.)
```
 StorageFactory factory = StorageFactory.create(configFilePath);
 DistributedStorage storage = factory.getStorage();

 // Inserts a new entry which has the primary key value 0 to the storage.
 // Assumes that the namespace name and the table name are NAMESPACE and TABLE respectively, and
 // the primary key is composed of a integer column named COL_NAME.
 Put put =
     Put.newBuilder()
         .namespace(NAMESPACE)
         .table(TABLE)
         .partitionKey(Key.ofInt(COL_NAME, 0))
         ...
         .build();
 storage.put(put);

 // Retrieves the entry from the storage.
 Get get =
     Get.newBuilder()
         .namespace(NAMESPACE)
         .table(TABLE)
         .partitionKey(Key.ofInt(COL_NAME, 0))
         .build();
 Optional<Result> result = storage.get(get);

 // Deletes an entry which has the primary key value 1.
 Delete delete =
     Delete.newBuilder()
         .namespace(NAMESPACE)
         .table(TABLE)
         .partitionKey(Key.ofInt(COL_NAME, 0))
         .build();
 storage.delete(delete);
 
```

Method Summary

All Methods Instance Methods Abstract Methods Deprecated Methods
Modifier and Type	Method and Description
`void`	`close()` Closes connections to the cluster.
`void`	`delete(Delete delete)` Deletes an entry from the underlying storage with the specified `Delete` command.
`void`	`delete(java.util.List<Delete> deletes)` Deletes entries from the underlying storage with the specified list of `Delete` commands.
`java.util.Optional<Result>`	`get(Get get)` Retrieves a result from the underlying storage with the specified `Get` command with a primary key and returns the result.
`java.util.Optional<java.lang.String>`	`getNamespace()` Deprecated. As of release 3.6.0. Will be removed in release 5.0.0
`java.util.Optional<java.lang.String>`	`getTable()` Deprecated. As of release 3.6.0. Will be removed in release 5.0.0
`void`	`mutate(java.util.List<? extends Mutation> mutations)` Mutates entries of the underlying storage with the specified list of `Mutation` commands.
`void`	`put(java.util.List<Put> puts)` Inserts multiple entries into or updates multiple entries within the same partition to the underlying storage with the specified list of `Put` commands.
`void`	`put(Put put)` Inserts an entry into or updates an entry to the underlying storage with the specified `Put` command.
`Scanner`	`scan(Scan scan)` Retrieves results from the underlying storage with the specified `Scan` or `ScanAll` or `ScanWithIndex` command and returns `Scanner` to iterate the results.
`void`	`with(java.lang.String namespace, java.lang.String tableName)` Deprecated. As of release 3.6.0. Will be removed in release 5.0.0
`void`	`withNamespace(java.lang.String namespace)` Deprecated. As of release 3.6.0. Will be removed in release 5.0.0
`void`	`withTable(java.lang.String tableName)` Deprecated. As of release 3.6.0. Will be removed in release 5.0.0

- Method Detail
  - with
```
@Deprecated
void with(java.lang.String namespace,
                      java.lang.String tableName)
```
    Deprecated. As of release 3.6.0. Will be removed in release 5.0.0
    
    Sets the specified namespace and the table name as default values in the instance.
    
    Parameters:
    
    namespace - default namespace to operate for
    
    tableName - default table name to operate for
  - withNamespace
```
@Deprecated
void withNamespace(java.lang.String namespace)
```
    Deprecated. As of release 3.6.0. Will be removed in release 5.0.0
    
    Sets the specified namespace as a default value in the instance.
    
    Parameters:
    
    namespace - default namespace to operate for
  - getNamespace
```
@Deprecated
java.util.Optional<java.lang.String> getNamespace()
```
    Deprecated. As of release 3.6.0. Will be removed in release 5.0.0
    
    Returns the namespace.
    
    Returns:
    
    an Optional with the namespace
  - withTable
```
@Deprecated
void withTable(java.lang.String tableName)
```
    Deprecated. As of release 3.6.0. Will be removed in release 5.0.0
    
    Sets the specified table name as a default value in the instance.
    
    Parameters:
    
    tableName - default table name to operate for
  - getTable
```
@Deprecated
java.util.Optional<java.lang.String> getTable()
```
    Deprecated. As of release 3.6.0. Will be removed in release 5.0.0
    
    Returns the table name.
    
    Returns:
    
    an Optional with the table name
  - get
```
java.util.Optional<Result> get(Get get)
                        throws ExecutionException
```
    Retrieves a result from the underlying storage with the specified Get command with a primary key and returns the result.
    
    Parameters:
    
    get - a Get command
    
    Returns:
    
    an Optional with the returned result
    
    Throws:
    
    ExecutionException - if the operation fails
  - scan
```
Scanner scan(Scan scan)
      throws ExecutionException
```
    Retrieves results from the underlying storage with the specified Scan or ScanAll or ScanWithIndex command and returns Scanner to iterate the results.
    - Scan : by specifying a partition key, it will return results within the partition. Results can be filtered by specifying a range of clustering keys.
    - ScanAll : for a given table, it will return all its records even if they span several partitions.
    - ScanWithIndex : by specifying an index key, it will return results within the index.
    Parameters:
    
    scan - a Scan or ScanAll command
    
    Returns:
    
    Scanner to iterate results
    
    Throws:
    
    ExecutionException - if the operation fails
  - put
```
void put(Put put)
  throws ExecutionException
```
    Inserts an entry into or updates an entry to the underlying storage with the specified Put command.
    
    Parameters:
    
    put - a Put command
    
    Throws:
    
    ExecutionException - if the operation fails
  - put
```
void put(java.util.List<Put> puts)
  throws ExecutionException
```
    Inserts multiple entries into or updates multiple entries within the same partition to the underlying storage with the specified list of Put commands. When entries spanning multiple partitions are inserted, this will throw MultiPartitionException.
    
    Parameters:
    
    puts - a list of Put commands
    
    Throws:
    
    ExecutionException - if the operation fails
  - delete
```
void delete(Delete delete)
     throws ExecutionException
```
    Deletes an entry from the underlying storage with the specified Delete command.
    
    Parameters:
    
    delete - a Delete command
    
    Throws:
    
    ExecutionException - if the operation fails
  - delete
```
void delete(java.util.List<Delete> deletes)
     throws ExecutionException
```
    Deletes entries from the underlying storage with the specified list of Delete commands.
    
    Parameters:
    
    deletes - a list of Delete commands
    
    Throws:
    
    ExecutionException - if the operation fails
  - mutate
```
void mutate(java.util.List<? extends Mutation> mutations)
     throws ExecutionException
```
    Mutates entries of the underlying storage with the specified list of Mutation commands.
    
    Parameters:
    
    mutations - a list of Mutation commands
    
    Throws:
    
    ExecutionException - if the operation fails
  - close
```
void close()
```
    Closes connections to the cluster. The connections are shared among multiple services such as StorageService and TransactionService, thus this should only be used when closing applications.
    
    Specified by:
    
    close in interface java.lang.AutoCloseable

Interface DistributedStorage

Usage Examples

Method Summary

Method Detail

with

withNamespace

getNamespace

withTable

getTable

get

scan

put

put

delete

delete

mutate

close