org.apache.hadoop.hbase.client

Interface AsyncTable<C extends ScanResultConsumerBase>

All Known Implementing Classes:

AsyncTableImpl, RawAsyncTableImpl

@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.CheckAndMutateBuilder A helper class for sending checkAndMutate request.
static interface	AsyncTable.CheckAndMutateWithFilterBuilder A helper class for sending checkAndMutate request with a filter.
static interface	AsyncTable.CoprocessorCallback<R> The callback when we want to execute a coprocessor call on a range of regions.
static interface	AsyncTable.CoprocessorServiceBuilder<S,R> Helper class for sending coprocessorService request that executes a coprocessor call on regions which are covered by a range.

Method Summary

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.
AsyncTable.CheckAndMutateBuilder	checkAndMutate(byte[] row, byte[] family) Atomically checks if a row/family/qualifier value matches the expected value.
AsyncTable.CheckAndMutateWithFilterBuilder	checkAndMutate(byte[] row, Filter filter) Atomically checks if a row matches the specified filter.
<S,R> 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<Void>	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

AsyncTable.CheckAndMutateBuilder checkAndMutate(byte[] row,
                                                byte[] family)

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

AsyncTable.CheckAndMutateWithFilterBuilder checkAndMutate(byte[] row,
                                                          Filter filter)

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");
       }
     });
 
 

mutateRow

CompletableFuture<Void> 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 always returns null when complete normally.

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> 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.