org.apache.hadoop.hbase.client

Interface AsyncTableBase

All Known Subinterfaces:

AsyncTable, RawAsyncTable

@InterfaceAudience.Public
public interface AsyncTableBase

The base 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

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 and Appends.
default <T> CompletableFuture<List<T>>	batchAll(List<? extends Row> actions) A simple version of batch.
default CompletableFuture<Boolean>	checkAndDelete(byte[] row, byte[] family, byte[] qualifier, byte[] value, Delete delete) Atomically checks if a row/family/qualifier value equals to the expected value.
CompletableFuture<Boolean>	checkAndDelete(byte[] row, byte[] family, byte[] qualifier, CompareOperator compareOp, byte[] value, Delete delete) Atomically checks if a row/family/qualifier value matches the expected value.
default CompletableFuture<Boolean>	checkAndMutate(byte[] row, byte[] family, byte[] qualifier, byte[] value, RowMutations mutation) Atomically checks if a row/family/qualifier value equals to the expected value.
CompletableFuture<Boolean>	checkAndMutate(byte[] row, byte[] family, byte[] qualifier, CompareOperator compareOp, byte[] value, RowMutations mutation) Atomically checks if a row/family/qualifier value matches the expected value.
default CompletableFuture<Boolean>	checkAndPut(byte[] row, byte[] family, byte[] qualifier, byte[] value, Put put) Atomically checks if a row/family/qualifier value equals to the expected value.
CompletableFuture<Boolean>	checkAndPut(byte[] row, byte[] family, byte[] qualifier, CompareOperator compareOp, byte[] value, Put put) Atomically checks if a row/family/qualifier value matches the expected value.
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.
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.
long	getRpcTimeout(TimeUnit unit) Get timeout of each rpc request in this Table instance.
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.
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.

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.

See Also:

getReadRpcTimeout(TimeUnit), getWriteRpcTimeout(TimeUnit)

getReadRpcTimeout

long getReadRpcTimeout(TimeUnit unit)

Get timeout of each rpc read request in this Table instance.

getWriteRpcTimeout

long getWriteRpcTimeout(TimeUnit unit)

Get timeout of each rpc write request in this Table instance.

getOperationTimeout

long getOperationTimeout(TimeUnit unit)

Get timeout of each operation in Table instance.

getScanTimeout

long getScanTimeout(TimeUnit unit)

Get the timeout of a single operation in a scan. It works like operation timeout for other operations.

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.

checkAndPut

default CompletableFuture<Boolean> checkAndPut(byte[] row,
                                               byte[] family,
                                               byte[] qualifier,
                                               byte[] value,
                                               Put put)

Atomically checks if a row/family/qualifier value equals to the expected value. If it does, it adds the put. If the passed value is null, the check is for the lack of column (ie: non-existence)

Parameters:

row - to check

family - column family to check

qualifier - column qualifier to check

value - the expected value

put - data to put if check succeeds

Returns:

true if the new put was executed, false otherwise. The return value will be wrapped by a CompletableFuture.

checkAndPut

CompletableFuture<Boolean> checkAndPut(byte[] row,
                                       byte[] family,
                                       byte[] qualifier,
                                       CompareOperator compareOp,
                                       byte[] value,
                                       Put put)

Atomically checks if a row/family/qualifier value matches the expected value. If it does, it adds the put. If the passed value is null, the check is for the lack of column (ie: non-existence)

Parameters:

row - to check

family - column family to check

qualifier - column qualifier to check

compareOp - comparison operator to use

value - the expected value

put - data to put if check succeeds

Returns:

true if the new put was executed, false otherwise. The return value will be wrapped by a CompletableFuture.

checkAndDelete

default CompletableFuture<Boolean> checkAndDelete(byte[] row,
                                                  byte[] family,
                                                  byte[] qualifier,
                                                  byte[] value,
                                                  Delete delete)

Atomically checks if a row/family/qualifier value equals to the expected value. If it does, it adds the delete. If the passed value is null, the check is for the lack of column (ie: non-existence)

Parameters:

row - to check

family - column family to check

qualifier - column qualifier to check

value - the expected value

delete - data to delete if check succeeds

Returns:

true if the new delete was executed, false otherwise. The return value will be wrapped by a CompletableFuture.

checkAndDelete

CompletableFuture<Boolean> checkAndDelete(byte[] row,
                                          byte[] family,
                                          byte[] qualifier,
                                          CompareOperator compareOp,
                                          byte[] value,
                                          Delete delete)

Atomically checks if a row/family/qualifier value matches the expected value. If it does, it adds the delete. If the passed value is null, the check is for the lack of column (ie: non-existence)

Parameters:

row - to check

family - column family to check

qualifier - column qualifier to check

compareOp - comparison operator to use

value - the expected value

delete - data to delete if check succeeds

Returns:

true if the new delete was executed, false otherwise. The return value will be wrapped by a CompletableFuture.

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.

checkAndMutate

default CompletableFuture<Boolean> checkAndMutate(byte[] row,
                                                  byte[] family,
                                                  byte[] qualifier,
                                                  byte[] value,
                                                  RowMutations mutation)

Atomically checks if a row/family/qualifier value equals to the expected value. If it does, it performs the row mutations. If the passed value is null, the check is for the lack of column (ie: non-existence)

Parameters:

row - to check

family - column family to check

qualifier - column qualifier to check

value - the expected value

mutation - mutations to perform if check succeeds

Returns:

true if the new put was executed, false otherwise. The return value will be wrapped by a CompletableFuture.

checkAndMutate

CompletableFuture<Boolean> checkAndMutate(byte[] row,
                                          byte[] family,
                                          byte[] qualifier,
                                          CompareOperator compareOp,
                                          byte[] value,
                                          RowMutations mutation)

Atomically checks if a row/family/qualifier value matches the expected value. If it does, it performs the row mutations. If the passed value is null, the check is for the lack of column (ie: non-existence)

Parameters:

row - to check

family - column family to check

qualifier - column qualifier to check

compareOp - the comparison operator

value - the expected value

mutation - mutations to perform if check succeeds

Returns:

true if the new put was executed, false otherwise. The return value will be wrapped by a CompletableFuture.

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 and Appends. 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 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 objects

Returns:

A list of the result for the actions. Wrapped by a CompletableFuture.