AsyncTable (Apache HBase 2.5.0 API)

```
@InterfaceAudience.Public
public interface AsyncTable<C extends ScanResultConsumerBase>
```
The interface for asynchronous version of Table. Obtain an instance from a AsyncConnection.
The implementation is required to be thread safe.
Usually the implementation will not throw any exception directly. You need to get the exception from the returned CompletableFuture.

Since:

2.0.0

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static interface AsyncTable.CoprocessorCallback<R>
The callback when we want to execute a coprocessor call on a range of regions.

Nested Classes
Modifier and Type	Interface and Description
`static interface`	`AsyncTable.CoprocessorCallback<R>` The callback when we want to execute a coprocessor call on a range of regions.

Method Summary

All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
Modifier and Type	Method and Description
`CompletableFuture<Result>`	`append(Append append)` Appends values to one or more columns within a single row.
`<T> List<CompletableFuture<T>>`	`batch(List<? extends Row> actions)` Method that does a batch call on Deletes, Gets, Puts, Increments, Appends and RowMutations.
`default <T> CompletableFuture<List<T>>`	`batchAll(List<? extends Row> actions)` A simple version of batch.
`org.apache.hadoop.hbase.client.AsyncTable.CheckAndMutateBuilder`	`checkAndMutate(byte[] row, byte[] family)` Deprecated. Since 2.4.0, will be removed in 4.0.0. For internal test use only, do not use it any more.
`org.apache.hadoop.hbase.client.AsyncTable.CheckAndMutateWithFilterBuilder`	`checkAndMutate(byte[] row, Filter filter)` Deprecated. Since 2.4.0, will be removed in 4.0.0. For internal test use only, do not use it any more.
`CompletableFuture<CheckAndMutateResult>`	`checkAndMutate(CheckAndMutate checkAndMutate)` checkAndMutate that atomically checks if a row matches the specified condition.
`List<CompletableFuture<CheckAndMutateResult>>`	`checkAndMutate(List<CheckAndMutate> checkAndMutates)` Batch version of checkAndMutate.
`default CompletableFuture<List<CheckAndMutateResult>>`	`checkAndMutateAll(List<CheckAndMutate> checkAndMutates)` A simple version of batch checkAndMutate.
`<S,R> org.apache.hadoop.hbase.client.AsyncTable.CoprocessorServiceBuilder<S,R>`	`coprocessorService(Function<com.google.protobuf.RpcChannel,S> stubMaker, ServiceCaller<S,R> callable, AsyncTable.CoprocessorCallback<R> callback)` Execute a coprocessor call on the regions which are covered by a range.
`<S,R> CompletableFuture<R>`	`coprocessorService(Function<com.google.protobuf.RpcChannel,S> stubMaker, ServiceCaller<S,R> callable, byte[] row)` Execute the given coprocessor call on the region which contains the given `row`.
`CompletableFuture<Void>`	`delete(Delete delete)` Deletes the specified cells/row.
`List<CompletableFuture<Void>>`	`delete(List<Delete> deletes)` Deletes the specified cells/rows in bulk.
`default CompletableFuture<Void>`	`deleteAll(List<Delete> deletes)` A simple version of batch delete.
`default CompletableFuture<Boolean>`	`exists(Get get)` Test for the existence of columns in the table, as specified by the Get.
`default List<CompletableFuture<Boolean>>`	`exists(List<Get> gets)` Test for the existence of columns in the table, as specified by the Gets.
`default CompletableFuture<List<Boolean>>`	`existsAll(List<Get> gets)` A simple version for batch exists.
`CompletableFuture<Result>`	`get(Get get)` Extracts certain cells from a given row.
`List<CompletableFuture<Result>>`	`get(List<Get> gets)` Extracts certain cells from the given rows, in batch.
`default CompletableFuture<List<Result>>`	`getAll(List<Get> gets)` A simple version for batch get.
`org.apache.hadoop.conf.Configuration`	`getConfiguration()` Returns the `Configuration` object used by this instance.
`CompletableFuture<TableDescriptor>`	`getDescriptor()` Gets the `TableDescriptor` for this table.
`TableName`	`getName()` Gets the fully qualified table name instance of this table.
`long`	`getOperationTimeout(TimeUnit unit)` Get timeout of each operation in Table instance.
`long`	`getReadRpcTimeout(TimeUnit unit)` Get timeout of each rpc read request in this Table instance.
`AsyncTableRegionLocator`	`getRegionLocator()` Gets the `AsyncTableRegionLocator` for this table.
`long`	`getRpcTimeout(TimeUnit unit)` Get timeout of each rpc request in this Table instance.
`default ResultScanner`	`getScanner(byte[] family)` Gets a scanner on the current table for the given family.
`default ResultScanner`	`getScanner(byte[] family, byte[] qualifier)` Gets a scanner on the current table for the given family and qualifier.
`ResultScanner`	`getScanner(Scan scan)` Returns a scanner on the current table as specified by the `Scan` object.
`long`	`getScanTimeout(TimeUnit unit)` Get the timeout of a single operation in a scan.
`long`	`getWriteRpcTimeout(TimeUnit unit)` Get timeout of each rpc write request in this Table instance.
`CompletableFuture<Result>`	`increment(Increment increment)` Increments one or more columns within a single row.
`default CompletableFuture<Long>`	`incrementColumnValue(byte[] row, byte[] family, byte[] qualifier, long amount)` See `incrementColumnValue(byte[], byte[], byte[], long, Durability)`
`default CompletableFuture<Long>`	`incrementColumnValue(byte[] row, byte[] family, byte[] qualifier, long amount, Durability durability)` Atomically increments a column value.
`CompletableFuture<Result>`	`mutateRow(RowMutations mutation)` Performs multiple mutations atomically on a single row.
`List<CompletableFuture<Void>>`	`put(List<Put> puts)` Puts some data in the table, in batch.
`CompletableFuture<Void>`	`put(Put put)` Puts some data to the table.
`default CompletableFuture<Void>`	`putAll(List<Put> puts)` A simple version of batch put.
`void`	`scan(Scan scan, C consumer)` The scan API uses the observer pattern.
`CompletableFuture<List<Result>>`	`scanAll(Scan scan)` Return all the results that match the given scan object.

- Method Detail
  - getName
```
TableName getName()
```
    Gets the fully qualified table name instance of this table.
  - getConfiguration
```
org.apache.hadoop.conf.Configuration getConfiguration()
```
    Returns the Configuration object used by this instance.
    The reference returned is not a copy, so any change made to it will affect this instance.
  - getDescriptor
```
CompletableFuture<TableDescriptor> getDescriptor()
```
    Gets the TableDescriptor for this table.
  - getRegionLocator
```
AsyncTableRegionLocator getRegionLocator()
```
    Gets the AsyncTableRegionLocator for this table.
  - getRpcTimeout
```
long getRpcTimeout(TimeUnit unit)
```
    Get timeout of each rpc request in this Table instance. It will be overridden by a more specific rpc timeout config such as readRpcTimeout or writeRpcTimeout.
    
    Parameters:
    
    unit - the unit of time the timeout to be represented in
    
    Returns:
    
    rpc timeout in the specified time unit
    
    See Also:
    
    getReadRpcTimeout(TimeUnit), getWriteRpcTimeout(TimeUnit)
  - getReadRpcTimeout
```
long getReadRpcTimeout(TimeUnit unit)
```
    Get timeout of each rpc read request in this Table instance.
    
    Parameters:
    
    unit - the unit of time the timeout to be represented in
    
    Returns:
    
    read rpc timeout in the specified time unit
  - getWriteRpcTimeout
```
long getWriteRpcTimeout(TimeUnit unit)
```
    Get timeout of each rpc write request in this Table instance.
    
    Parameters:
    
    unit - the unit of time the timeout to be represented in
    
    Returns:
    
    write rpc timeout in the specified time unit
  - getOperationTimeout
```
long getOperationTimeout(TimeUnit unit)
```
    Get timeout of each operation in Table instance.
    
    Parameters:
    
    unit - the unit of time the timeout to be represented in
    
    Returns:
    
    operation rpc timeout in the specified time unit
  - getScanTimeout
```
long getScanTimeout(TimeUnit unit)
```
    Get the timeout of a single operation in a scan. It works like operation timeout for other operations.
    
    Parameters:
    
    unit - the unit of time the timeout to be represented in
    
    Returns:
    
    scan rpc timeout in the specified time unit
  - exists
```
default CompletableFuture<Boolean> exists(Get get)
```
    Test for the existence of columns in the table, as specified by the Get.
    This will return true if the Get matches one or more keys, false if not.
    This is a server-side call so it prevents any data from being transfered to the client.
    
    Returns:
    
    true if the specified Get matches one or more keys, false if not. The return value will be wrapped by a CompletableFuture.
  - get
```
CompletableFuture<Result> get(Get get)
```
    Extracts certain cells from a given row.
    
    Parameters:
    
    get - The object that specifies what data to fetch and from which row.
    
    Returns:
    
    The data coming from the specified row, if it exists. If the row specified doesn't exist, the Result instance returned won't contain any KeyValue, as indicated by Result.isEmpty(). The return value will be wrapped by a CompletableFuture.
  - put
```
CompletableFuture<Void> put(Put put)
```
    Puts some data to the table.
    
    Parameters:
    
    put - The data to put.
    
    Returns:
    
    A CompletableFuture that always returns null when complete normally.
  - delete
```
CompletableFuture<Void> delete(Delete delete)
```
    Deletes the specified cells/row.
    
    Parameters:
    
    delete - The object that specifies what to delete.
    
    Returns:
    
    A CompletableFuture that always returns null when complete normally.
  - append
```
CompletableFuture<Result> append(Append append)
```
    Appends values to one or more columns within a single row.
    This operation does not appear atomic to readers. Appends are done under a single row lock, so write operations to a row are synchronized, but readers do not take row locks so get and scan operations can see this operation partially completed.
    
    Parameters:
    
    append - object that specifies the columns and amounts to be used for the increment operations
    
    Returns:
    
    values of columns after the append operation (maybe null). The return value will be wrapped by a CompletableFuture.
  - increment
```
CompletableFuture<Result> increment(Increment increment)
```
    Increments one or more columns within a single row.
    This operation does not appear atomic to readers. Increments are done under a single row lock, so write operations to a row are synchronized, but readers do not take row locks so get and scan operations can see this operation partially completed.
    
    Parameters:
    
    increment - object that specifies the columns and amounts to be used for the increment operations
    
    Returns:
    
    values of columns after the increment. The return value will be wrapped by a CompletableFuture.
  - incrementColumnValue
```
default CompletableFuture<Long> incrementColumnValue(byte[] row,
                                                     byte[] family,
                                                     byte[] qualifier,
                                                     long amount)
```
    See incrementColumnValue(byte[], byte[], byte[], long, Durability)
    The Durability is defaulted to Durability.SYNC_WAL.
    
    Parameters:
    
    row - The row that contains the cell to increment.
    
    family - The column family of the cell to increment.
    
    qualifier - The column qualifier of the cell to increment.
    
    amount - The amount to increment the cell with (or decrement, if the amount is negative).
    
    Returns:
    
    The new value, post increment. The return value will be wrapped by a CompletableFuture.
  - incrementColumnValue
```
default CompletableFuture<Long> incrementColumnValue(byte[] row,
                                                     byte[] family,
                                                     byte[] qualifier,
                                                     long amount,
                                                     Durability durability)
```
    Atomically increments a column value. If the column value already exists and is not a big-endian long, this could throw an exception. If the column value does not yet exist it is initialized to amount and written to the specified column.
    Setting durability to Durability.SKIP_WAL means that in a fail scenario you will lose any increments that have not been flushed.
    
    Parameters:
    
    row - The row that contains the cell to increment.
    
    family - The column family of the cell to increment.
    
    qualifier - The column qualifier of the cell to increment.
    
    amount - The amount to increment the cell with (or decrement, if the amount is negative).
    
    durability - The persistence guarantee for this increment.
    
    Returns:
    
    The new value, post increment. The return value will be wrapped by a CompletableFuture.
  - checkAndMutate
```
@Deprecated
org.apache.hadoop.hbase.client.AsyncTable.CheckAndMutateBuilder checkAndMutate(byte[] row,
                                                                                           byte[] family)
```
    Deprecated. Since 2.4.0, will be removed in 4.0.0. For internal test use only, do not use it any more.
    Atomically checks if a row/family/qualifier value matches the expected value. If it does, it adds the Put/Delete/RowMutations.
    Use the returned AsyncTable.CheckAndMutateBuilder to construct your request and then execute it. This is a fluent style API, the code is like:
```
 table.checkAndMutate(row, family).qualifier(qualifier).ifNotExists().thenPut(put)
   .thenAccept(succ -> {
     if (succ) {
       System.out.println("Check and put succeeded");
     } else {
       System.out.println("Check and put failed");
     }
   });
 
```
  - checkAndMutate
```
@Deprecated
org.apache.hadoop.hbase.client.AsyncTable.CheckAndMutateWithFilterBuilder checkAndMutate(byte[] row,
                                                                                                     Filter filter)
```
    Deprecated. Since 2.4.0, will be removed in 4.0.0. For internal test use only, do not use it any more.
    Atomically checks if a row matches the specified filter. If it does, it adds the Put/Delete/RowMutations.
    Use the returned AsyncTable.CheckAndMutateWithFilterBuilder to construct your request and then execute it. This is a fluent style API, the code is like:
```
 table.checkAndMutate(row, filter).thenPut(put).thenAccept(succ -> {
   if (succ) {
     System.out.println("Check and put succeeded");
   } else {
     System.out.println("Check and put failed");
   }
 });
 
```
  - checkAndMutate
```
CompletableFuture<CheckAndMutateResult> checkAndMutate(CheckAndMutate checkAndMutate)
```
    checkAndMutate that atomically checks if a row matches the specified condition. If it does, it performs the specified action.
    
    Parameters:
    
    checkAndMutate - The CheckAndMutate object.
    
    Returns:
    
    A CompletableFutures that represent the result for the CheckAndMutate.
  - checkAndMutate
```
List<CompletableFuture<CheckAndMutateResult>> checkAndMutate(List<CheckAndMutate> checkAndMutates)
```
    Batch version of checkAndMutate. The specified CheckAndMutates are batched only in the sense that they are sent to a RS in one RPC, but each CheckAndMutate operation is still executed atomically (and thus, each may fail independently of others).
    
    Parameters:
    
    checkAndMutates - The list of CheckAndMutate.
    
    Returns:
    
    A list of CompletableFutures that represent the result for each CheckAndMutate.
  - checkAndMutateAll
```
default CompletableFuture<List<CheckAndMutateResult>> checkAndMutateAll(List<CheckAndMutate> checkAndMutates)
```
    A simple version of batch checkAndMutate. It will fail if there are any failures.
    
    Parameters:
    
    checkAndMutates - The list of rows to apply.
    
    Returns:
    
    A CompletableFuture that wrapper the result list.
  - mutateRow
```
CompletableFuture<Result> mutateRow(RowMutations mutation)
```
    Performs multiple mutations atomically on a single row. Currently Put and Delete are supported.
    
    Parameters:
    
    mutation - object that specifies the set of mutations to perform atomically
    
    Returns:
    
    A CompletableFuture that returns results of Increment/Append operations
  - scan
```
void scan(Scan scan,
          C consumer)
```
    The scan API uses the observer pattern.
    
    Parameters:
    
    scan - A configured Scan object.
    
    consumer - the consumer used to receive results.
    
    See Also:
    
    ScanResultConsumer, AdvancedScanResultConsumer
  - getScanner
```
default ResultScanner getScanner(byte[] family)
```
    Gets a scanner on the current table for the given family.
    
    Parameters:
    
    family - The column family to scan.
    
    Returns:
    
    A scanner.
  - getScanner
```
default ResultScanner getScanner(byte[] family,
                                 byte[] qualifier)
```
    Gets a scanner on the current table for the given family and qualifier.
    
    Parameters:
    
    family - The column family to scan.
    
    qualifier - The column qualifier to scan.
    
    Returns:
    
    A scanner.
  - getScanner
```
ResultScanner getScanner(Scan scan)
```
    Returns a scanner on the current table as specified by the Scan object.
    
    Parameters:
    
    scan - A configured Scan object.
    
    Returns:
    
    A scanner.
  - scanAll
```
CompletableFuture<List<Result>> scanAll(Scan scan)
```
    Return all the results that match the given scan object.
    Notice that usually you should use this method with a Scan object that has limit set. For example, if you want to get the closest row after a given row, you could do this:
```
 table.scanAll(new Scan().withStartRow(row, false).setLimit(1)).thenAccept(results -> {
   if (results.isEmpty()) {
     System.out.println("No row after " + Bytes.toStringBinary(row));
   } else {
     System.out.println("The closest row after " + Bytes.toStringBinary(row) + " is "
       + Bytes.toStringBinary(results.stream().findFirst().get().getRow()));
   }
 });
 
```
    If your result set is very large, you should use other scan method to get a scanner or use callback to process the results. They will do chunking to prevent OOM. The scanAll method will fetch all the results and store them in a List and then return the list to you.
    The scan metrics will be collected background if you enable it but you have no way to get it. Usually you can get scan metrics from ResultScanner, or through ScanResultConsumer.onScanMetricsCreated but this method only returns a list of results. So if you really care about scan metrics then you'd better use other scan methods which return a ResultScanner or let you pass in a ScanResultConsumer. There is no performance difference between these scan methods so do not worry.
    Parameters:
    
    scan - A configured Scan object. So if you use this method to fetch a really large result set, it is likely to cause OOM.
    
    Returns:
    
    The results of this small scan operation. The return value will be wrapped by a CompletableFuture.
  - exists
```
default List<CompletableFuture<Boolean>> exists(List<Get> gets)
```
    Test for the existence of columns in the table, as specified by the Gets.
    This will return a list of booleans. Each value will be true if the related Get matches one or more keys, false if not.
    This is a server-side call so it prevents any data from being transferred to the client.
    
    Parameters:
    
    gets - the Gets
    
    Returns:
    
    A list of CompletableFutures that represent the existence for each get.
  - existsAll
```
default CompletableFuture<List<Boolean>> existsAll(List<Get> gets)
```
    A simple version for batch exists. It will fail if there are any failures and you will get the whole result boolean list at once if the operation is succeeded.
    
    Parameters:
    
    gets - the Gets
    
    Returns:
    
    A CompletableFuture that wrapper the result boolean list.
  - get
```
List<CompletableFuture<Result>> get(List<Get> gets)
```
    Extracts certain cells from the given rows, in batch.
    Notice that you may not get all the results with this function, which means some of the returned CompletableFutures may succeed while some of the other returned CompletableFutures may fail.
    
    Parameters:
    
    gets - The objects that specify what data to fetch and from which rows.
    
    Returns:
    
    A list of CompletableFutures that represent the result for each get.
  - getAll
```
default CompletableFuture<List<Result>> getAll(List<Get> gets)
```
    A simple version for batch get. It will fail if there are any failures and you will get the whole result list at once if the operation is succeeded.
    
    Parameters:
    
    gets - The objects that specify what data to fetch and from which rows.
    
    Returns:
    
    A CompletableFuture that wrapper the result list.
  - put
```
List<CompletableFuture<Void>> put(List<Put> puts)
```
    Puts some data in the table, in batch.
    
    Parameters:
    
    puts - The list of mutations to apply.
    
    Returns:
    
    A list of CompletableFutures that represent the result for each put.
  - putAll
```
default CompletableFuture<Void> putAll(List<Put> puts)
```
    A simple version of batch put. It will fail if there are any failures.
    
    Parameters:
    
    puts - The list of mutations to apply.
    
    Returns:
    
    A CompletableFuture that always returns null when complete normally.
  - delete
```
List<CompletableFuture<Void>> delete(List<Delete> deletes)
```
    Deletes the specified cells/rows in bulk.
    
    Parameters:
    
    deletes - list of things to delete.
    
    Returns:
    
    A list of CompletableFutures that represent the result for each delete.
  - deleteAll
```
default CompletableFuture<Void> deleteAll(List<Delete> deletes)
```
    A simple version of batch delete. It will fail if there are any failures.
    
    Parameters:
    
    deletes - list of things to delete.
    
    Returns:
    
    A CompletableFuture that always returns null when complete normally.
  - batch
```
<T> List<CompletableFuture<T>> batch(List<? extends Row> actions)
```
    Method that does a batch call on Deletes, Gets, Puts, Increments, Appends and RowMutations. The ordering of execution of the actions is not defined. Meaning if you do a Put and a Get in the same batch(java.util.List<? extends org.apache.hadoop.hbase.client.Row>) call, you will not necessarily be guaranteed that the Get returns what the Put had put.
    
    Parameters:
    
    actions - list of Get, Put, Delete, Increment, Append, and RowMutations objects
    
    Returns:
    
    A list of CompletableFutures that represent the result for each action.
  - batchAll
```
default <T> CompletableFuture<List<T>> batchAll(List<? extends Row> actions)
```
    A simple version of batch. It will fail if there are any failures and you will get the whole result list at once if the operation is succeeded.
    
    Parameters:
    
    actions - list of Get, Put, Delete, Increment, Append and RowMutations objects
    
    Returns:
    
    A list of the result for the actions. Wrapped by a CompletableFuture.
  - coprocessorService
```
<S,R> CompletableFuture<R> coprocessorService(Function<com.google.protobuf.RpcChannel,S> stubMaker,
                                              ServiceCaller<S,R> callable,
                                              byte[] row)
```
    Execute the given coprocessor call on the region which contains the given row.
    The stubMaker is just a delegation to the newStub call. Usually it is only a one line lambda expression, like:
```
 channel -> xxxService.newStub(channel)
 
```
    Type Parameters:
    
    S - the type of the asynchronous stub
    
    R - the type of the return value
    
    Parameters:
    
    stubMaker - a delegation to the actual newStub call.
    
    callable - a delegation to the actual protobuf rpc call. See the comment of ServiceCaller for more details.
    
    row - The row key used to identify the remote region location
    
    Returns:
    
    the return value of the protobuf rpc call, wrapped by a CompletableFuture.
    
    See Also:
    
    ServiceCaller
  - coprocessorService
```
<S,R> org.apache.hadoop.hbase.client.AsyncTable.CoprocessorServiceBuilder<S,R> coprocessorService(Function<com.google.protobuf.RpcChannel,S> stubMaker,
                                                                                                  ServiceCaller<S,R> callable,
                                                                                                  AsyncTable.CoprocessorCallback<R> callback)
```
    Execute a coprocessor call on the regions which are covered by a range.
    Use the returned AsyncTable.CoprocessorServiceBuilder construct your request and then execute it.
    The stubMaker is just a delegation to the xxxService.newStub call. Usually it is only a one line lambda expression, like:
```
 channel -> xxxService.newStub(channel)
 
```
    Parameters:
    
    stubMaker - a delegation to the actual newStub call.
    
    callable - a delegation to the actual protobuf rpc call. See the comment of ServiceCaller for more details.
    
    callback - callback to get the response. See the comment of AsyncTable.CoprocessorCallback for more details.

Interface AsyncTable<C extends ScanResultConsumerBase>

Nested Class Summary

Method Summary

Method Detail

getName

getConfiguration

getDescriptor

getRegionLocator

getRpcTimeout

getReadRpcTimeout

getWriteRpcTimeout

getOperationTimeout

getScanTimeout

exists

get

put

delete

append

increment

incrementColumnValue

incrementColumnValue

checkAndMutate

checkAndMutate

checkAndMutate

checkAndMutate

checkAndMutateAll

mutateRow

scan

getScanner

getScanner

getScanner

scanAll

exists

existsAll

get

getAll

put

putAll

delete

deleteAll

batch

batchAll

coprocessorService

coprocessorService