AsyncKuduClient

java.lang.Object
- org.apache.kudu.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.
A single Kudu client instance corresponds to a single remote Kudu cluster, and can be used to read or write any number of tables within that cluster. An application should use exactly one Kudu client instance per distinct Kudu cluster it connects to. In rare cases where a single application needs multiple instances connected to the same cluster, or when many applications each using one or more Kudu client instances are running on the same machine, it may be necessary to adjust the instances to use less resources. See the options in AsyncKuduClient.AsyncKuduClientBuilder.
Creating a client instance
An AsyncKuduClient instance may be created using the AsyncKuduClient.AsyncKuduClientBuilder class. If a synchronous API is preferred, KuduClient.KuduClientBuilder may be used instead. See the documentation on these classes for more details on client configuration options.
Authenticating to a secure cluster
A Kudu cluster may be configured such that it requires clients to connect using strong authentication. Clients can authenticate to such clusters using either of two methods:
1. Kerberos credentials
2. Authentication tokens
In a typical environment, Kerberos credentials are used for non-distributed client applications and for applications which spawn distributed jobs. Tokens are used for the tasks of distributed jobs, since those tasks do not have access to the user's Kerberos credentials.
Authenticating using Kerberos credentials
In order to integrate with Kerberos, Kudu uses the standard Java Authentication and Authorization Service (JAAS) API provided by the JDK. JAAS provides a common way for applications to initialize Kerberos credentials, store these credentials in a Subject instance, and associate the Subject with the current thread of execution. The Kudu client then accesses the Kerberos credentials in the Subject and uses them to authenticate to the remote cluster as necessary.
Kerberos credentials are typically obtained in one of two ways:
1. The Kerberos ticket cache
2. A keytab file
Authenticating from the Kerberos ticket cache
The Kerberos ticket cache is a file stored on the local file system which is automatically initialized when a user runs kinit at the command line. This is the predominant method for authenticating users in interactive applications: the user is expected to have run kinit recently, and the application will find the appropriate credentials in the ticket cache.
In the case of the Kudu client, Kudu will automatically look for credentials in the standard system-configured ticket cache location. No additional code needs to be written to enable this behavior.
Kudu will automatically detect if the ticket it has obtained from the ticket cache is about to expire. When that is the case, it will attempt to re-read the ticket cache to obtain a new ticket with a later expiration time. So, if an application needs to run for longer than the lifetime of a single ticket, the user must ensure that the ticket cache is periodically refreshed, for example by re-running 'kinit' once each day.
Authenticating from a keytab
Long-running applications typically obtain Kerberos credentials from a Kerberos keytab file. A keytab is essentially a saved password, and allows the application to obtain new Kerberos tickets whenever the prior ticket is about to expire.
The Kudu client does not provide any utility code to facilitate logging in from a keytab. Instead, applications should invoke the JAAS APIs directly, and then ensure that the resulting Subject instance is associated with the current thread's AccessControlContext when instantiating the Kudu client instance for the first time. The Subject instance will be stored and used whenever Kerberos authentication is required.
Note: if the Kudu client is instantiated with a Subject as described above, it will not make any attempt to re-login from the keytab. Instead, the application should arrange to periodically re-initiate the login process and update the credentials stored in the same Subject instance as was provided when the client was instantiated.
The easiest way to authenticate using a keytab is by creating a JAAS config file such as this:
```
 ExampleLoginContextName {
   com.sun.security.auth.module.Krb5LoginModule required
   useKeyTab = true
   keyTab = "/path/to/app.keytab"
   principal = "appuser";
 };
 
```
This can then be passed to the application by adding -Djava.security.auth.login.config=/path/to/jaas.conf to the command when starting it. This authentication method needs to be set in the code as well by wrapping the code interacting with Kudu with a Subject.doAs(javax.security.auth.Subject, java.security.PrivilegedAction<T>) after creating a login context using the JAAS config, logging in, and passing the Subject to the doAs:
```
 LoginContext login = new LoginContext("ExampleLoginContextName");
 login.login();
 KuduClient c = Subject.doAs(login.getSubject(),
                             (PrivilegedAction<KuduClient>) () -> {
   return myClientBuilder.build();
 });
 
```
In this case it's necessary to periodically re-login as needed and run doAs using the new subject.
In the context of the Hadoop ecosystem, the org.apache.hadoop.security.UserGroupInformation class provides utility methods to login from a keytab and then run code as the resulting Subject:
```
   UserGroupInformation.loginUserFromKeytab("appuser", "/path/to/app.keytab");
   KuduClient c = UserGroupInformation.getLoginUser().doAs(
     new PrivilegedExceptionAction() {
       @Override
       public KuduClient run() throws Exception {
         return myClientBuilder.build();
       }
     }
   );
 
```
The UserGroupInformation class will also automatically start a thread to periodically re-login from the keytab. It's not necessary to pass a JAAS config.
Debugging Kudu's usage of Kerberos credentials
The Kudu client emits DEBUG-level logs under the org.apache.kudu.client.SecurityContext slf4j category. Enabling DEBUG logging for this class may help you understand which credentials are being obtained by the Kudu client when it is instantiated. Additionally, if the Java system property kudu.jaas.debug is set to true, Kudu will enable the debug option when configuring Krb5LoginModule when it attempts to log in from a ticket cache. JDK-specific system properties such as sun.security.krb5.debug may also be useful in troubleshooting Kerberos authentication failures.
Authenticating using tokens
In the case of distributed applications, the worker tasks often do not have access to Kerberos credentials such as ticket caches or keytabs. Additionally, there may be hundreds or thousands of workers with relatively short life-times, and if each task attempted to authenticate using Kerberos, the amount of load on the Kerberos infrastructure could be substantial enough to cause instability. To solve this issue, Kudu provides support for authentication tokens.
An authentication token is a time-limited credential which can be obtained by an application which has already authenticated via Kerberos. The token is represented by an opaque byte string, and it can be passed from one client to another to transfer credentials.
A token may be generated using the exportAuthenticationCredentials() API, and then imported to another client using importAuthenticationCredentials(byte[]).
Authentication in Spark jobs
Note that the Spark integration provided by the kudu-spark package automatically handles the interaction with Kerberos and the passing of tokens from the Spark driver to tasks. Refer to the Kudu documentation for details on how to submit a Spark job on a secure cluster.
API Compatibility
Note that some methods in the Kudu client implementation are public but annotated with the InterfaceAudience.Private annotation. This annotation indicates that, despite having public visibility, the method is not part of the public API and there is no guarantee that its existence or behavior will be maintained in subsequent versions of the Kudu client library. Other APIs are annotated with the InterfaceStability.Unstable annotation. These APIs are meant for public consumption but may change between minor releases. Note that the asynchronous client is currently considered unstable.
Thread Safety
The Kudu client instance itself is thread-safe; however, not all associated classes are themselves thread-safe. For example, neither AsyncKuduSession nor its synchronous wrapper KuduSession is thread-safe. Refer to the documentation for each individual class for more details.
Asynchronous usage
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.
The asynchronous calls themselves typically do not throw exceptions. Instead, an errback should be attached which will be called with the Exception that occurred.

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.

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_KEEP_ALIVE_PERIOD_MS`
`static long`	`DEFAULT_OPERATION_TIMEOUT_MS`
`static byte[]`	`EMPTY_ARRAY`
`static long`	`INVALID_TXN_ID`
`static org.slf4j.Logger`	`LOG`
`static long`	`NO_TIMESTAMP`
`static int`	`SLEEP_TIME`

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
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.
`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.
`com.stumbleupon.async.Deferred<byte[]>`	`exportAuthenticationCredentials()` Export serialized authentication data that may be passed to a different client instance and imported to provide that client the ability to connect to the cluster.
`String`	`getClusterId()` Returns the ID of the cluster that this client is connected to.
`long`	`getDefaultAdminOperationTimeoutMs()` Get the timeout used for admin operations.
`long`	`getDefaultOperationTimeoutMs()` Get the timeout used for operations on sessions and scanners.
`long`	`getDefaultSocketReadTimeoutMs()` Deprecated. socket read timeouts are no longer used
`long`	`getLastPropagatedTimestamp()` Returns the last timestamp received from a server.
`String`	`getLocationString()` Returns a string representation of this client's location.
`String`	`getMasterAddressesAsString()`
`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<KuduTableStatistics>`	`getTableStatistics(String name)` Get table's statistics from master.
`boolean`	`hasLastPropagatedTimestamp()` Checks if the client received any timestamps from a server.
`void`	`importAuthenticationCredentials(byte[] authnData)` Import data allowing this client to authenticate to the cluster.
`com.stumbleupon.async.Deferred<IsAlterTableDoneResponse>`	`isAlterTableDone(String name)` Check whether a previously issued alterTable() is done.
`com.stumbleupon.async.Deferred<IsCreateTableDoneResponse>`	`isCreateTableDone(String name)` Check whether a previously issued createTable() is done.
`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
  - INVALID_TXN_ID
```
public static final long INVALID_TXN_ID
```
    See Also:
    
    Constant Field Values
  - DEFAULT_OPERATION_TIMEOUT_MS
```
public static final long DEFAULT_OPERATION_TIMEOUT_MS
```
    See Also:
    
    Constant Field Values
  - DEFAULT_KEEP_ALIVE_PERIOD_MS
```
public static final long DEFAULT_KEEP_ALIVE_PERIOD_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.
    
    Parameters:
    
    lastPropagatedTimestamp - the last timestamp received from a server
  - getLastPropagatedTimestamp
```
public long getLastPropagatedTimestamp()
```
    Returns the last timestamp received from a server. Used for CLIENT_PROPAGATED external consistency. Note that the returned timestamp is encoded and cannot be interpreted as a raw timestamp.
    
    Returns:
    
    a long indicating the specially-encoded last timestamp received from a server
  - hasLastPropagatedTimestamp
```
public boolean hasLastPropagatedTimestamp()
```
    Checks if the client received any timestamps from a server. Used for CLIENT_PROPAGATED external consistency.
    
    Returns:
    
    true if last propagated timestamp has been set
  - getLocationString
```
public String getLocationString()
```
    Returns a string representation of this client's location. If this client was not assigned a location, returns the empty string.
    
    Returns:
    
    a string representation of this client's location
  - getClusterId
```
public String getClusterId()
```
    Returns the ID of the cluster that this client is connected to. It will be an empty string if the client is not connected or the client is connected to a cluster that doesn't support cluster IDs.
    
    Returns:
    
    the ID of the cluster that this client is connected to
  - 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. If the primary key columns of the table schema aren't specified first, the deferred result will be a NonRecoverableException
    
    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
  - isCreateTableDone
```
public com.stumbleupon.async.Deferred<IsCreateTableDoneResponse> isCreateTableDone(String name)
```
    Check whether a previously issued createTable() is done.
    
    Parameters:
    
    name - table's name
    
    Returns:
    
    a deferred object to track the progress of the isCreateTableDone command
  - 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.
    
    Parameters:
    
    name - the table's name (old name if the table is being renamed)
    
    ato - the alter table options
    
    Returns:
    
    a deferred object to track the progress of the alter command
  - isAlterTableDone
```
public com.stumbleupon.async.Deferred<IsAlterTableDoneResponse> isAlterTableDone(String name)
```
    Check whether a previously issued alterTable() is done.
    
    Parameters:
    
    name - table name
    
    Returns:
    
    a deferred object to track the progress of the isAlterTableDone command
  - 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
  - getTableStatistics
```
public com.stumbleupon.async.Deferred<KuduTableStatistics> getTableStatistics(String name)
```
    Get table's statistics from master.
    
    Parameters:
    
    name - the table's name
    
    Returns:
    
    an deferred KuduTableStatistics
  - 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. New range partitions created by other clients will immediately be available after opening the table.
    
    Parameters:
    
    name - table to open
    
    Returns:
    
    a deferred KuduTable
  - exportAuthenticationCredentials
```
@InterfaceStability.Unstable
public com.stumbleupon.async.Deferred<byte[]> exportAuthenticationCredentials()
```
    Export serialized authentication data that may be passed to a different client instance and imported to provide that client the ability to connect to the cluster.
  - importAuthenticationCredentials
```
@InterfaceStability.Unstable
public void importAuthenticationCredentials(byte[] authnData)
```
    Import data allowing this client to authenticate to the cluster. This will typically be used before making any connections to servers in the cluster. Note that, if this client has already been used by one user, this method cannot be used to switch authenticated users. Attempts to do so have undefined results, and may throw an exception.
    
    Parameters:
    
    authnData - then authentication data provided by a prior call to exportAuthenticationCredentials()
  - 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
```
@Deprecated
public long getDefaultSocketReadTimeoutMs()
```
    Deprecated. socket read timeouts are no longer used
    
    Socket read timeouts are no longer used in the Java client and have no effect. This method always returns 0, as that previously indicated no socket read timeout.
    
    Returns:
    
    a timeout in milliseconds
  - getMasterAddressesAsString
```
public String getMasterAddressesAsString()
```
    Returns:
    
    the list of master addresses, stringified using commas to separate them
  - 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. 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.

Class AsyncKuduClient

Creating a client instance

Authenticating to a secure cluster

Authenticating using Kerberos credentials

Authenticating from the Kerberos ticket cache

Authenticating from a keytab

Debugging Kudu's usage of Kerberos credentials

Authenticating using tokens

Authentication in Spark jobs

API Compatibility

Thread Safety

Asynchronous usage

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

LOG

SLEEP_TIME

EMPTY_ARRAY

NO_TIMESTAMP

INVALID_TXN_ID

DEFAULT_OPERATION_TIMEOUT_MS

DEFAULT_KEEP_ALIVE_PERIOD_MS

Method Detail

updateLastPropagatedTimestamp

getLastPropagatedTimestamp

hasLastPropagatedTimestamp

getLocationString

getClusterId

syncClient

createTable

isCreateTableDone

deleteTable

alterTable

isAlterTableDone

listTabletServers

getTablesList

getTablesList

getTableStatistics

tableExists

openTable

exportAuthenticationCredentials

importAuthenticationCredentials

getDefaultOperationTimeoutMs

getDefaultAdminOperationTimeoutMs

getDefaultSocketReadTimeoutMs

getMasterAddressesAsString

isStatisticsEnabled

getStatistics

newScannerBuilder

newSession

close

shutdown