org.apache.kudu.client

Class KuduClient

java.lang.Object

org.apache.kudu.client.KuduClient

All Implemented Interfaces:

AutoCloseable

@InterfaceAudience.Public
 @InterfaceStability.Evolving
public class KuduClient
extends Object
implements AutoCloseable

A synchronous and thread-safe client for Kudu.

This class acts as a wrapper around AsyncKuduClient which contains all the relevant documentation.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	KuduClient.KuduClientBuilder Builder class to use in order to connect to Kudu.

Field Summary

Fields

Modifier and Type	Field and Description
static long	NO_TIMESTAMP

Method Summary

Modifier and Type	Method and Description
AlterTableResponse	alterTable(String name, AlterTableOptions ato) Alter a table on the cluster as specified by the builder.
void	close() Analogous to shutdown().
KuduTable	createTable(String name, Schema schema, CreateTableOptions builder) Create a table on the cluster with the specified name, schema, and table configurations.
DeleteTableResponse	deleteTable(String name) Delete a table on the cluster with the specified name.
DeleteTableResponse	deleteTable(String name, int reserveSeconds) SoftDelete a table on the cluster with the specified name, the table will be reserved for reserveSeconds before being purged.
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	getLastPropagatedTimestamp() Returns the last timestamp received from a server.
String	getLocationString() Returns a string representation of this client's location.
String	getMasterAddressesAsString()
ListTablesResponse	getSoftDeletedTablesList() Get the list of all the soft deleted tables.
ListTablesResponse	getSoftDeletedTablesList(String nameFilter) Get list of soft deleted table names.
Statistics	getStatistics() Get the statistics object of this client.
ListTablesResponse	getTablesList() Get the list of all the regular tables.
ListTablesResponse	getTablesList(String nameFilter) Get a list of regular table names.
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.
boolean	isAlterTableDone(String name) Waits for all of the tablets in a table to be altered, or until the default admin operation timeout is reached.
boolean	isCreateTableDone(String name) Waits for all of the tablets in a table to be created, or until the default admin operation timeout is reached.
boolean	isStatisticsEnabled() Check if statistics collection is enabled for this client.
void	jwt(String jwt) Set JWT (JSON Web Token) to authenticate the client to a server.
ListTabletServersResponse	listTabletServers() Get the list of running tablet servers.
KuduScanner.KuduScannerBuilder	newScannerBuilder(KuduTable table) Creates a new KuduScanner.KuduScannerBuilder for a particular table.
KuduScanToken.KuduScanTokenBuilder	newScanTokenBuilder(KuduTable table) Creates a new KuduScanToken.KuduScanTokenBuilder for a particular table.
KuduSession	newSession() Create a new session for interacting with the cluster.
KuduTransaction	newTransaction() Start a new multi-row distributed transaction.
KuduTable	openTable(String name) Open the table with the given name.
RecallDeletedTableResponse	recallDeletedTable(String id) Recall a deleted table on the cluster with the specified table id
RecallDeletedTableResponse	recallDeletedTable(String id, String newTableName) Recall a deleted table on the cluster with the specified table id and give the recalled table the new table name
void	shutdown() Performs a graceful shutdown of this instance.
boolean	tableExists(String name) Test if a table exists.
void	trustedCertificates(List<com.google.protobuf.ByteString> certificates) Mark the given CA certificates (in DER format) as the trusted ones for the client.
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

NO_TIMESTAMP

public static final long NO_TIMESTAMP

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

createTable

public KuduTable createTable(String name,
                             Schema schema,
                             CreateTableOptions builder)
                      throws KuduException

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:

an object to communicate with the created table

Throws:

KuduException - if anything went wrong

isCreateTableDone

public boolean isCreateTableDone(String name)
                          throws KuduException

Waits for all of the tablets in a table to be created, or until the default admin operation timeout is reached.

Parameters:

name - the table's name

Returns:

true if the table is done being created, or false if the default admin operation timeout was reached.

Throws:

KuduException - for any error returned by sending RPCs to the master (e.g. the table does not exist)

deleteTable

public DeleteTableResponse deleteTable(String name)
                                throws KuduException

Delete a table on the cluster with the specified name. The deleted table may turn to soft-deleted status with the flag default_deleted_table_reserve_seconds set to nonzero on the master side.

Parameters:

name - the table's name

Returns:

an rpc response object

Throws:

KuduException - if anything went wrong

deleteTable

public DeleteTableResponse deleteTable(String name,
                                       int reserveSeconds)
                                throws KuduException

SoftDelete a table on the cluster with the specified name, the table will be reserved for reserveSeconds before being purged.

Parameters:

name - the table's name

reserveSeconds - the soft deleted table to be alive time

Returns:

an rpc response object

Throws:

KuduException - if anything went wrong

recallDeletedTable

public RecallDeletedTableResponse recallDeletedTable(String id)
                                              throws KuduException

Recall a deleted table on the cluster with the specified table id

Parameters:

id - the table's id

Returns:

an rpc response object

Throws:

KuduException - if anything went wrong

recallDeletedTable

public RecallDeletedTableResponse recallDeletedTable(String id,
                                                     String newTableName)
                                              throws KuduException

Recall a deleted table on the cluster with the specified table id and give the recalled table the new table name

Parameters:

id - the table's id

newTableName - the recalled table's new name

Returns:

an rpc response object

Throws:

KuduException - if anything went wrong

alterTable

public AlterTableResponse alterTable(String name,
                                     AlterTableOptions ato)
                              throws KuduException

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:

an rpc response object

Throws:

KuduException - if anything went wrong

isAlterTableDone

public boolean isAlterTableDone(String name)
                         throws KuduException

Waits for all of the tablets in a table to be altered, or until the default admin operation timeout is reached.

Parameters:

name - the table's name

Returns:

true if the table is done being altered, or false if the default admin operation timeout was reached.

Throws:

KuduException - for any error returned by sending RPCs to the master (e.g. the table does not exist)

listTabletServers

public ListTabletServersResponse listTabletServers()
                                            throws KuduException

Get the list of running tablet servers.

Returns:

a list of tablet servers

Throws:

KuduException - if anything went wrong

getTablesList

public ListTablesResponse getTablesList()
                                 throws KuduException

Get the list of all the regular tables.

Returns:

a list of all the regular tables

Throws:

KuduException - if anything went wrong

getTablesList

public ListTablesResponse getTablesList(String nameFilter)
                                 throws KuduException

Get a list of regular 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 contains the list of table names

Throws:

KuduException - if anything went wrong

getSoftDeletedTablesList

public ListTablesResponse getSoftDeletedTablesList()
                                            throws KuduException

Get the list of all the soft deleted tables.

Returns:

a list of all the soft deleted tables

Throws:

KuduException - if anything went wrong

getSoftDeletedTablesList

public ListTablesResponse getSoftDeletedTablesList(String nameFilter)
                                            throws KuduException

Get list of soft deleted 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 contains the list of table names

Throws:

KuduException - if anything went wrong

getTableStatistics

public KuduTableStatistics getTableStatistics(String name)
                                       throws KuduException

Get table's statistics from master.

Parameters:

name - the table's name

Returns:

the statistics of table

Throws:

KuduException - if anything went wrong

tableExists

public boolean tableExists(String name)
                    throws KuduException

Test if a table exists.

Parameters:

name - a non-null table name

Returns:

true if the table exists, else false

Throws:

KuduException - if anything went wrong

openTable

public KuduTable openTable(String name)
                    throws KuduException

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 KuduTable if the table exists

Throws:

KuduException - if anything went wrong

newSession

public KuduSession 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 synchronous wrapper around KuduSession.

newTransaction

public KuduTransaction newTransaction()
                               throws KuduException

Start a new multi-row distributed transaction.

Start a new multi-row transaction and return a handle for the transactional object to manage the newly started transaction. Under the hood, this makes an RPC call to the Kudu cluster and registers a newly created transaction in the system. This call is blocking.

Returns:

a handle to the newly started transaction in case of success

Throws:

KuduException

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 KuduScanner.KuduScannerBuilder newScannerBuilder(KuduTable table)

Creates a new KuduScanner.KuduScannerBuilder for a particular table.

Parameters:

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

Returns:

a new scanner builder for the table

newScanTokenBuilder

public KuduScanToken.KuduScanTokenBuilder newScanTokenBuilder(KuduTable table)

Creates a new KuduScanToken.KuduScanTokenBuilder for a particular table. Used for integrations with compute frameworks.

Parameters:

table - the table you intend to scan

Returns:

a new scan token builder for the table

close

public void close()
           throws KuduException

Analogous to shutdown().

Specified by:

close in interface AutoCloseable

Throws:

KuduException - if an error happens while closing the connections

shutdown

public void shutdown()
              throws KuduException

Performs a graceful shutdown of this instance.

Throws:

KuduException - if anything went wrong

exportAuthenticationCredentials

@InterfaceStability.Unstable
public byte[] exportAuthenticationCredentials()
                                                                    throws KuduException

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.

Throws:

KuduException

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()

trustedCertificates

@InterfaceStability.Unstable
public void trustedCertificates(List<com.google.protobuf.ByteString> certificates)
                                                      throws CertificateException

Mark the given CA certificates (in DER format) as the trusted ones for the client. The provided list of certificates replaces any previously set ones.

Parameters:

certificates - list of certificates to trust (in DER format)

Throws:

CertificateException - if any of the specified certificates were invalid

jwt

@InterfaceStability.Unstable
public void jwt(String jwt)

Set JWT (JSON Web Token) to authenticate the client to a server.

Parameters:

jwt - The JSON web token to set.

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

getMasterAddressesAsString

public String getMasterAddressesAsString()

Returns:

the list of master addresses, stringified using commas to separate them