org.kududb.client

Class AsyncKuduClient

java.lang.Object

org.kududb.client.AsyncKuduClient

All Implemented Interfaces:

AutoCloseable

@InterfaceAudience.Public
 @InterfaceStability.Unstable
public class AsyncKuduClient
extends Object
implements AutoCloseable

A fully asynchronous and thread-safe client for Kudu.

This client should be instantiated only once. You can use it with any number of tables at the same time. The only case where you should have multiple instances is when you want to use multiple different clusters at the same time.

If you play by the rules, this client is completely thread-safe. Read the documentation carefully to know what the requirements are for this guarantee to apply.

This client is fully non-blocking, any blocking operation will return a Deferred instance to which you can attach a Callback chain that will execute when the asynchronous operation completes.

Note regarding KuduRpc instances passed to this class

Every KuduRpc passed to a method of this class should not be changed or re-used until the Deferred returned by that method calls you back. Changing or re-using any KuduRpc for an RPC in flight will lead to unpredictable results and voids your warranty.

throws clauses

None of the asynchronous methods in this API are expected to throw an exception. But the Deferred object they return to you can carry an exception that you should handle (using "errbacks", see the javadoc of Deferred). In order to be able to do proper asynchronous error handling, you need to know what types of exceptions you're expected to face in your errbacks. In order to document that, the methods of this API use javadoc's @throws to spell out the exception types you should handle in your errback. Asynchronous exceptions will be indicated as such in the javadoc with "(deferred)".

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AsyncKuduClient.AsyncKuduClientBuilder Builder class to use in order to connect to Kudu.

Field Summary

Fields

Modifier and Type	Field and Description
static long	DEFAULT_OPERATION_TIMEOUT_MS
static long	DEFAULT_SOCKET_READ_TIMEOUT_MS
static byte[]	EMPTY_ARRAY
static org.slf4j.Logger	LOG
static long	NO_TIMESTAMP
static int	SLEEP_TIME

Method Summary

Modifier and Type	Method and Description
com.stumbleupon.async.Deferred<AlterTableResponse>	alterTable(String name, AlterTableOptions ato) Alter a table on the cluster as specified by the builder.
void	close() Invokes shutdown() and waits for the configured admin timeout.
com.stumbleupon.async.Deferred<KuduTable>	createTable(String name, Schema schema, CreateTableOptions builder) Create a table on the cluster with the specified name, schema, and table configurations.
com.stumbleupon.async.Deferred<DeleteTableResponse>	deleteTable(String name) Delete a table on the cluster with the specified name.
long	getDefaultAdminOperationTimeoutMs() Get the timeout used for admin operations.
long	getDefaultOperationTimeoutMs() Get the timeout used for operations on sessions and scanners.
long	getDefaultSocketReadTimeoutMs() Get the timeout used when waiting to read data from a socket.
long	getLastPropagatedTimestamp()
Statistics	getStatistics() Get the statistics object of this client.
com.stumbleupon.async.Deferred<ListTablesResponse>	getTablesList() Get the list of all the tables.
com.stumbleupon.async.Deferred<ListTablesResponse>	getTablesList(String nameFilter) Get a list of table names.
com.stumbleupon.async.Deferred<IsAlterTableDoneResponse>	isAlterTableDone(String name) Helper method that checks and waits until the completion of an alter command.
boolean	isStatisticsEnabled() Check if statistics collection is enabled for this client.
com.stumbleupon.async.Deferred<ListTabletServersResponse>	listTabletServers() Get the list of running tablet servers.
AsyncKuduScanner.AsyncKuduScannerBuilder	newScannerBuilder(KuduTable table) Creates a new AsyncKuduScanner.AsyncKuduScannerBuilder for a particular table.
AsyncKuduSession	newSession() Create a new session for interacting with the cluster.
com.stumbleupon.async.Deferred<KuduTable>	openTable(String name) Open the table with the given name.
com.stumbleupon.async.Deferred<ArrayList<Void>>	shutdown() Performs a graceful shutdown of this instance.
KuduClient	syncClient() Returns a synchronous KuduClient which wraps this asynchronous client.
com.stumbleupon.async.Deferred<Boolean>	tableExists(String name) Test if a table exists.
void	updateLastPropagatedTimestamp(long lastPropagatedTimestamp) Updates the last timestamp received from a server.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LOG

public static final org.slf4j.Logger LOG

SLEEP_TIME

public static final int SLEEP_TIME

See Also:

Constant Field Values

EMPTY_ARRAY

public static final byte[] EMPTY_ARRAY

NO_TIMESTAMP

public static final long NO_TIMESTAMP

See Also:

Constant Field Values

DEFAULT_OPERATION_TIMEOUT_MS

public static final long DEFAULT_OPERATION_TIMEOUT_MS

See Also:

Constant Field Values

DEFAULT_SOCKET_READ_TIMEOUT_MS

public static final long DEFAULT_SOCKET_READ_TIMEOUT_MS

See Also:

Constant Field Values

Method Detail

updateLastPropagatedTimestamp

public void updateLastPropagatedTimestamp(long lastPropagatedTimestamp)

Updates the last timestamp received from a server. Used for CLIENT_PROPAGATED external consistency. This is only publicly visible so that it can be set on tests, users should generally disregard this method.

Parameters:

lastPropagatedTimestamp - the last timestamp received from a server

getLastPropagatedTimestamp

public long getLastPropagatedTimestamp()

syncClient

public KuduClient syncClient()

Returns a synchronous KuduClient which wraps this asynchronous client. Calling KuduClient.close() on the returned client will close this client. If this asynchronous client should outlive the returned synchronous client, then do not close the synchronous client.

Returns:

a new synchronous KuduClient

createTable

public com.stumbleupon.async.Deferred<KuduTable> createTable(String name,
                                                             Schema schema,
                                                             CreateTableOptions builder)

Create a table on the cluster with the specified name, schema, and table configurations.

Parameters:

name - the table's name

schema - the table's schema

builder - a builder containing the table's configurations

Returns:

a deferred object to track the progress of the createTable command that gives an object to communicate with the created table

deleteTable

public com.stumbleupon.async.Deferred<DeleteTableResponse> deleteTable(String name)

Delete a table on the cluster with the specified name.

Parameters:

name - the table's name

Returns:

a deferred object to track the progress of the deleteTable command

alterTable

public com.stumbleupon.async.Deferred<AlterTableResponse> alterTable(String name,
                                                                     AlterTableOptions ato)

Alter a table on the cluster as specified by the builder. When the returned deferred completes it only indicates that the master accepted the alter command, use isAlterTableDone(String) to know when the alter finishes.

Parameters:

name - the table's name, if this is a table rename then the old table name must be passed

ato - the alter table builder

Returns:

a deferred object to track the progress of the alter command

isAlterTableDone

public com.stumbleupon.async.Deferred<IsAlterTableDoneResponse> isAlterTableDone(String name)
                                                                          throws Exception

Helper method that checks and waits until the completion of an alter command. It will block until the alter command is done or the deadline is reached.

Parameters:

name - the table's name, if the table was renamed then that name must be checked against

Returns:

a deferred object to track the progress of the isAlterTableDone command

Throws:

Exception

listTabletServers

public com.stumbleupon.async.Deferred<ListTabletServersResponse> listTabletServers()

Get the list of running tablet servers.

Returns:

a deferred object that yields a list of tablet servers

getTablesList

public com.stumbleupon.async.Deferred<ListTablesResponse> getTablesList()

Get the list of all the tables.

Returns:

a deferred object that yields a list of all the tables

getTablesList

public com.stumbleupon.async.Deferred<ListTablesResponse> getTablesList(String nameFilter)

Get a list of table names. Passing a null filter returns all the tables. When a filter is specified, it only returns tables that satisfy a substring match.

Parameters:

nameFilter - an optional table name filter

Returns:

a deferred that yields the list of table names

tableExists

public com.stumbleupon.async.Deferred<Boolean> tableExists(String name)

Test if a table exists.

Parameters:

name - a non-null table name

Returns:

true if the table exists, else false

openTable

public com.stumbleupon.async.Deferred<KuduTable> openTable(String name)

Open the table with the given name. If the table was just created, the Deferred will only get called back when all the tablets have been successfully created.

Parameters:

name - table to open

Returns:

a KuduTable if the table exists, else a MasterErrorException

getDefaultOperationTimeoutMs

public long getDefaultOperationTimeoutMs()

Get the timeout used for operations on sessions and scanners.

Returns:

a timeout in milliseconds

getDefaultAdminOperationTimeoutMs

public long getDefaultAdminOperationTimeoutMs()

Get the timeout used for admin operations.

Returns:

a timeout in milliseconds

getDefaultSocketReadTimeoutMs

public long getDefaultSocketReadTimeoutMs()

Get the timeout used when waiting to read data from a socket. Will be triggered when nothing has been read on a socket connected to a tablet server for timeout milliseconds.

Returns:

a timeout in milliseconds

isStatisticsEnabled

public boolean isStatisticsEnabled()

Check if statistics collection is enabled for this client.

Returns:

true if it is enabled, else false

getStatistics

public Statistics getStatistics()

Get the statistics object of this client.

Returns:

this client's Statistics object

Throws:

IllegalStateException - thrown if statistics collection has been disabled

newScannerBuilder

public AsyncKuduScanner.AsyncKuduScannerBuilder newScannerBuilder(KuduTable table)

Creates a new AsyncKuduScanner.AsyncKuduScannerBuilder for a particular table.

Parameters:

table - the name of the table you intend to scan. The string is assumed to use the platform's default charset.

Returns:

a new scanner builder for this table

newSession

public AsyncKuduSession newSession()

Create a new session for interacting with the cluster. User is responsible for destroying the session object. This is a fully local operation (no RPCs or blocking).

Returns:

a new AsyncKuduSession

close

public void close()
           throws Exception

Invokes shutdown() and waits for the configured admin timeout. This method returns void, so consider invoking shutdown directly if there's a need to handle dangling RPCs.

Specified by:

close in interface AutoCloseable

Throws:

Exception - if an error happens while closing the connections

shutdown

public com.stumbleupon.async.Deferred<ArrayList<Void>> shutdown()

Performs a graceful shutdown of this instance.

• Flushes all buffered edits.
• Cancels all the other requests.
• Terminates all connections.
• Releases all other resources.

Not calling this method before losing the last reference to this instance may result in data loss and other unwanted side effects

Returns:

A Deferred, whose callback chain will be invoked once all of the above have been done. If this callback chain doesn't fail, then the clean shutdown will be successful, and all the data will be safe on the Kudu side. In case of a failure (the "errback" is invoked) you will have to open a new AsyncKuduClient if you want to retry those operations. The Deferred doesn't actually hold any content.