org.apache.hadoop.hbase.client

Class HTable

java.lang.Object

org.apache.hadoop.hbase.client.HTable

All Implemented Interfaces:

Closeable, AutoCloseable, HTableInterface

@InterfaceAudience.Public
@InterfaceStability.Stable
public class HTable
extends Object
implements HTableInterface

Used to communicate with a single HBase table. An implementation of HTableInterface. Instances of this class can be constructed directly but it is encouraged that users get instances via HConnection and HConnectionManager. See HConnectionManager class comment for an example.

This class is not thread safe for reads nor write.

In case of writes (Put, Delete), the underlying write buffer can be corrupted if multiple threads contend over a single HTable instance.

In case of reads, some fields used by a Scan are shared among all threads. The HTable implementation can either not contract to be safe in case of a Get

Instances of HTable passed the same Configuration instance will share connections to servers out on the cluster and to the zookeeper ensemble as well as caches of region locations. This is usually a *good* thing and it is recommended to reuse the same configuration object for all your tables. This happens because they will all share the same underlying HConnection instance. See HConnectionManager for more on how this mechanism works.

HConnection will read most of the configuration it needs from the passed Configuration on initial construction. Thereafter, for settings such as hbase.client.pause, hbase.client.retries.number, and hbase.client.rpc.maxattempts updating their values in the passed Configuration subsequent to HConnection construction will go unnoticed. To run with changed values, make a new HTable passing a new Configuration instance that has the new configuration.

Note that this class implements the Closeable interface. When a HTable instance is no longer required, it *should* be closed in order to ensure that the underlying resources are promptly released. Please note that the close method can throw java.io.IOException that must be handled.

See Also:

for create, drop, list, enable and disable of tables., HConnection, HConnectionManager

Field Summary

Fields

Modifier and Type	Field and Description
protected org.apache.hadoop.hbase.client.AsyncProcess<Object>	ap The Async process for puts with autoflush set to false or multiputs
protected HConnection	connection
protected long	currentWriteBufferSize
protected int	scannerCaching
protected List<Row>	writeAsyncBuffer

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	HTable() For internal testing.
	HTable(byte[] tableName, HConnection connection, ExecutorService pool) Creates an object to access a HBase table.
	HTable(org.apache.hadoop.conf.Configuration conf, byte[] tableName) Creates an object to access a HBase table.
	HTable(org.apache.hadoop.conf.Configuration conf, byte[] tableName, ExecutorService pool) Creates an object to access a HBase table.
	HTable(org.apache.hadoop.conf.Configuration conf, String tableName) Creates an object to access a HBase table.
	HTable(org.apache.hadoop.conf.Configuration conf, TableName tableName) Creates an object to access a HBase table.
	HTable(org.apache.hadoop.conf.Configuration conf, TableName tableName, ExecutorService pool) Creates an object to access a HBase table.
	HTable(TableName tableName, HConnection connection) Creates an object to access a HBase table.
	HTable(TableName tableName, HConnection connection, ExecutorService pool) Creates an object to access a HBase table.

Method Summary

Methods

Modifier and Type	Method and Description
Result	append(Append append) Appends values to one or more columns within a single row.
Object[]	batch(List<? extends Row> actions) Deprecated. If any exception is thrown by one of the actions, there is no way to retrieve the partially executed results. Use batch(List, Object[]) instead.
void	batch(List<? extends Row> actions, Object[] results) Method that does a batch call on Deletes, Gets, Puts, Increments, Appends and RowMutations.
<R> Object[]	batchCallback(List<? extends Row> actions, Batch.Callback<R> callback) Deprecated. If any exception is thrown by one of the actions, there is no way to retrieve the partially executed results. Use batchCallback(List, Object[], org.apache.hadoop.hbase.client.coprocessor.Batch.Callback) instead.
<R> void	batchCallback(List<? extends Row> actions, Object[] results, Batch.Callback<R> callback) Same as HTableInterface.batch(List, Object[]), but with a callback.
<R extends com.google.protobuf.Message> Map<byte[],R>	batchCoprocessorService(com.google.protobuf.Descriptors.MethodDescriptor methodDescriptor, com.google.protobuf.Message request, byte[] startKey, byte[] endKey, R responsePrototype) Creates an instance of the given Service subclass for each table region spanning the range from the startKey row to endKey row (inclusive), all the invocations to the same region server will be batched into one call.
<R extends com.google.protobuf.Message> void	batchCoprocessorService(com.google.protobuf.Descriptors.MethodDescriptor methodDescriptor, com.google.protobuf.Message request, byte[] startKey, byte[] endKey, R responsePrototype, Batch.Callback<R> callback) Creates an instance of the given Service subclass for each table region spanning the range from the startKey row to endKey row (inclusive), all the invocations to the same region server will be batched into one call.
boolean	checkAndDelete(byte[] row, byte[] family, byte[] qualifier, byte[] value, Delete delete) Atomically checks if a row/family/qualifier value matches the expected value.
boolean	checkAndMutate(byte[] row, byte[] family, byte[] qualifier, CompareFilter.CompareOp compareOp, byte[] value, RowMutations rm) Atomically checks if a row/family/qualifier value matches the expected val If it does, it performs the row mutations.
boolean	checkAndPut(byte[] row, byte[] family, byte[] qualifier, byte[] value, Put put) Atomically checks if a row/family/qualifier value matches the expected value.
void	clearRegionCache() Explicitly clears the region cache to fetch the latest value from META.
void	close() Releases any resources held or pending changes in internal buffers.
CoprocessorRpcChannel	coprocessorService(byte[] row) Creates and returns a RpcChannel instance connected to the table region containing the specified row.
<T extends com.google.protobuf.Service,R> Map<byte[],R>	coprocessorService(Class<T> service, byte[] startKey, byte[] endKey, Batch.Call<T,R> callable) Creates an instance of the given Service subclass for each table region spanning the range from the startKey row to endKey row (inclusive), and invokes the passed Batch.Call.call(T) method with each Service instance.
<T extends com.google.protobuf.Service,R> void	coprocessorService(Class<T> service, byte[] startKey, byte[] endKey, Batch.Call<T,R> callable, Batch.Callback<R> callback) Creates an instance of the given Service subclass for each table region spanning the range from the startKey row to endKey row (inclusive), and invokes the passed Batch.Call.call(T) method with each Service instance.
void	delete(Delete delete) Deletes the specified cells/row.
void	delete(List<Delete> deletes) Deletes the specified cells/rows in bulk.
boolean	exists(Get get) Test for the existence of columns in the table, as specified by the Get.
Boolean[]	exists(List<Get> gets) Test for the existence of columns in the table, as specified by the Gets.
void	flushCommits() Executes all the buffered Put operations.
Result	get(Get get) Extracts certain cells from a given row.
Result[]	get(List<Get> gets) Extracts certain cells from the given rows, in batch.
org.apache.hadoop.conf.Configuration	getConfiguration() Returns the Configuration object used by this instance.
HConnection	getConnection() Deprecated. This method will be changed from public to package protected.
static ThreadPoolExecutor	getDefaultExecutor(org.apache.hadoop.conf.Configuration conf)
byte[][]	getEndKeys() Gets the ending row key for every region in the currently open table.
static int	getMaxKeyValueSize(org.apache.hadoop.conf.Configuration conf)
TableName	getName() Gets the fully qualified table name instance of this table.
int	getOperationTimeout()
static boolean	getRegionCachePrefetch(byte[] tableName) Check whether region cache prefetch is enabled or not for the table.
static boolean	getRegionCachePrefetch(org.apache.hadoop.conf.Configuration conf, byte[] tableName) Check whether region cache prefetch is enabled or not for the table.
static boolean	getRegionCachePrefetch(org.apache.hadoop.conf.Configuration conf, TableName tableName)
static boolean	getRegionCachePrefetch(TableName tableName)
HRegionLocation	getRegionLocation(byte[] row) Finds the region on which the given row is being served.
HRegionLocation	getRegionLocation(byte[] row, boolean reload) Finds the region on which the given row is being served.
HRegionLocation	getRegionLocation(String row) Find region location hosting passed row using cached info
NavigableMap<HRegionInfo,ServerName>	getRegionLocations() Gets all the regions and their address for this table.
List<HRegionLocation>	getRegionsInRange(byte[] startKey, byte[] endKey) Get the corresponding regions for an arbitrary range of keys.
List<HRegionLocation>	getRegionsInRange(byte[] startKey, byte[] endKey, boolean reload) Get the corresponding regions for an arbitrary range of keys.
Result	getRowOrBefore(byte[] row, byte[] family) Return the row that matches row exactly, or the one that immediately precedes it.
ResultScanner	getScanner(byte[] family) Gets a scanner on the current table for the given family.
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.
int	getScannerCaching() Deprecated. Use Scan.setCaching(int) and Scan.getCaching()
Pair<byte[][],byte[][]>	getStartEndKeys() Gets the starting and ending row keys for every region in the currently open table.
byte[][]	getStartKeys() Gets the starting row key for every region in the currently open table.
HTableDescriptor	getTableDescriptor() Gets the table descriptor for this table.
byte[]	getTableName() Gets the name of this table.
List<Row>	getWriteBuffer() Deprecated. since 0.96. This is an internal buffer that should not be read nor write.
long	getWriteBufferSize() Returns the maximum size in bytes of the write buffer for this HTable.
Result	increment(Increment increment) Increments one or more columns within a single row.
long	incrementColumnValue(byte[] row, byte[] family, byte[] qualifier, long amount) See HTableInterface.incrementColumnValue(byte[], byte[], byte[], long, Durability)
long	incrementColumnValue(byte[] row, byte[] family, byte[] qualifier, long amount, boolean writeToWAL) Deprecated. Use incrementColumnValue(byte[], byte[], byte[], long, Durability)
long	incrementColumnValue(byte[] row, byte[] family, byte[] qualifier, long amount, Durability durability) Atomically increments a column value.
boolean	isAutoFlush() Tells whether or not 'auto-flush' is turned on.
static boolean	isTableEnabled(byte[] tableName) Deprecated. use HBaseAdmin.isTableEnabled(byte[])
static boolean	isTableEnabled(org.apache.hadoop.conf.Configuration conf, byte[] tableName) Deprecated. use HBaseAdmin.isTableEnabled(byte[])
static boolean	isTableEnabled(org.apache.hadoop.conf.Configuration conf, String tableName) Deprecated. use HBaseAdmin.isTableEnabled(byte[])
static boolean	isTableEnabled(org.apache.hadoop.conf.Configuration conf, TableName tableName) Deprecated. use HBaseAdmin.isTableEnabled(org.apache.hadoop.hbase.TableName tableName)
static boolean	isTableEnabled(String tableName) Deprecated. use HBaseAdmin.isTableEnabled(byte[])
static boolean	isTableEnabled(TableName tableName) Deprecated. use HBaseAdmin.isTableEnabled(byte[])
static void	main(String[] args) Run basic test.
void	mutateRow(RowMutations rm) Performs multiple mutations atomically on a single row.
void	processBatch(List<? extends Row> list, Object[] results) Parameterized batch processing, allowing varying return types for different Row implementations.
<R> void	processBatchCallback(List<? extends Row> list, Object[] results, Batch.Callback<R> callback) Process a mixed batch of Get, Put and Delete actions.
void	put(List<Put> puts) Puts some data in the table, in batch.
void	put(Put put) Puts some data in the table.
void	setAutoFlush(boolean autoFlush) Deprecated.
void	setAutoFlush(boolean autoFlush, boolean clearBufferOnFail) Turns 'auto-flush' on or off.
void	setAutoFlushTo(boolean autoFlush) Set the autoFlush behavior, without changing the value of clearBufferOnFail
void	setOperationTimeout(int operationTimeout)
static void	setRegionCachePrefetch(byte[] tableName, boolean enable) Enable or disable region cache prefetch for the table.
static void	setRegionCachePrefetch(org.apache.hadoop.conf.Configuration conf, byte[] tableName, boolean enable) Enable or disable region cache prefetch for the table.
static void	setRegionCachePrefetch(org.apache.hadoop.conf.Configuration conf, TableName tableName, boolean enable)
static void	setRegionCachePrefetch(TableName tableName, boolean enable)
void	setScannerCaching(int scannerCaching) Deprecated. Use Scan.setCaching(int)
void	setWriteBufferSize(long writeBufferSize) Sets the size of the buffer in bytes.
String	toString()
void	validatePut(Put put)
static void	validatePut(Put put, int maxKeyValueSize)

Methods inherited from class java.lang.Object

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

Field Detail

connection

protected HConnection connection

writeAsyncBuffer

protected List<Row> writeAsyncBuffer

currentWriteBufferSize

protected long currentWriteBufferSize

scannerCaching

protected int scannerCaching

ap

protected org.apache.hadoop.hbase.client.AsyncProcess<Object> ap

The Async process for puts with autoflush set to false or multiputs

Constructor Detail

HTable

public HTable(org.apache.hadoop.conf.Configuration conf,
      String tableName)
       throws IOException

Creates an object to access a HBase table. Shares zookeeper connection and other resources with other HTable instances created with the same conf instance. Uses already-populated region cache if one is available, populated by any other HTable instances sharing this conf instance. Recommended.

Parameters:

conf - Configuration object to use.

tableName - Name of the table.

Throws:

IOException - if a remote or network exception occurs

HTable

public HTable(org.apache.hadoop.conf.Configuration conf,
      byte[] tableName)
       throws IOException

Creates an object to access a HBase table. Shares zookeeper connection and other resources with other HTable instances created with the same conf instance. Uses already-populated region cache if one is available, populated by any other HTable instances sharing this conf instance. Recommended.

Parameters:

conf - Configuration object to use.

tableName - Name of the table.

Throws:

IOException - if a remote or network exception occurs

HTable

public HTable(org.apache.hadoop.conf.Configuration conf,
      TableName tableName)
       throws IOException

Creates an object to access a HBase table. Shares zookeeper connection and other resources with other HTable instances created with the same conf instance. Uses already-populated region cache if one is available, populated by any other HTable instances sharing this conf instance. Recommended.

Parameters:

conf - Configuration object to use.

tableName - table name pojo

Throws:

IOException - if a remote or network exception occurs

HTable

public HTable(TableName tableName,
      HConnection connection)
       throws IOException

Creates an object to access a HBase table. Shares zookeeper connection and other resources with other HTable instances created with the same connection instance. Use this constructor when the HConnection instance is externally managed.

Parameters:

tableName - Name of the table.

connection - HConnection to be used.

Throws:

IOException - if a remote or network exception occurs

HTable

public HTable(org.apache.hadoop.conf.Configuration conf,
      byte[] tableName,
      ExecutorService pool)
       throws IOException

Creates an object to access a HBase table. Shares zookeeper connection and other resources with other HTable instances created with the same conf instance. Uses already-populated region cache if one is available, populated by any other HTable instances sharing this conf instance. Use this constructor when the ExecutorService is externally managed.

Parameters:

conf - Configuration object to use.

tableName - Name of the table.

pool - ExecutorService to be used.

Throws:

IOException - if a remote or network exception occurs

HTable

public HTable(org.apache.hadoop.conf.Configuration conf,
      TableName tableName,
      ExecutorService pool)
       throws IOException

Creates an object to access a HBase table. Shares zookeeper connection and other resources with other HTable instances created with the same conf instance. Uses already-populated region cache if one is available, populated by any other HTable instances sharing this conf instance. Use this constructor when the ExecutorService is externally managed.

Parameters:

conf - Configuration object to use.

tableName - Name of the table.

pool - ExecutorService to be used.

Throws:

IOException - if a remote or network exception occurs

HTable

public HTable(byte[] tableName,
      HConnection connection,
      ExecutorService pool)
       throws IOException

Creates an object to access a HBase table. Shares zookeeper connection and other resources with other HTable instances created with the same connection instance. Use this constructor when the ExecutorService and HConnection instance are externally managed.

Parameters:

tableName - Name of the table.

connection - HConnection to be used.

pool - ExecutorService to be used.

Throws:

IOException - if a remote or network exception occurs

HTable

public HTable(TableName tableName,
      HConnection connection,
      ExecutorService pool)
       throws IOException

Creates an object to access a HBase table. Shares zookeeper connection and other resources with other HTable instances created with the same connection instance. Use this constructor when the ExecutorService and HConnection instance are externally managed.

Parameters:

tableName - Name of the table.

connection - HConnection to be used.

pool - ExecutorService to be used.

Throws:

IOException - if a remote or network exception occurs

HTable

protected HTable()

For internal testing.

Method Detail

getDefaultExecutor

public static ThreadPoolExecutor getDefaultExecutor(org.apache.hadoop.conf.Configuration conf)

getMaxKeyValueSize

public static int getMaxKeyValueSize(org.apache.hadoop.conf.Configuration conf)

Returns:

maxKeyValueSize from configuration.

getConfiguration

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

Specified by:

getConfiguration in interface HTableInterface

isTableEnabled

@Deprecated
public static boolean isTableEnabled(String tableName)
                              throws IOException

Deprecated. use HBaseAdmin.isTableEnabled(byte[])

Tells whether or not a table is enabled or not. This method creates a new HBase configuration, so it might make your unit tests fail due to incorrect ZK client port.

Parameters:

tableName - Name of table to check.

Returns:

true if table is online.

Throws:

IOException - if a remote or network exception occurs

isTableEnabled

@Deprecated
public static boolean isTableEnabled(byte[] tableName)
                              throws IOException

Deprecated. use HBaseAdmin.isTableEnabled(byte[])

Tells whether or not a table is enabled or not. This method creates a new HBase configuration, so it might make your unit tests fail due to incorrect ZK client port.

Parameters:

tableName - Name of table to check.

Returns:

true if table is online.

Throws:

IOException - if a remote or network exception occurs

isTableEnabled

@Deprecated
public static boolean isTableEnabled(TableName tableName)
                              throws IOException

Deprecated. use HBaseAdmin.isTableEnabled(byte[])

Tells whether or not a table is enabled or not. This method creates a new HBase configuration, so it might make your unit tests fail due to incorrect ZK client port.

Parameters:

tableName - Name of table to check.

Returns:

true if table is online.

Throws:

IOException - if a remote or network exception occurs

isTableEnabled

@Deprecated
public static boolean isTableEnabled(org.apache.hadoop.conf.Configuration conf,
                                String tableName)
                              throws IOException

Deprecated. use HBaseAdmin.isTableEnabled(byte[])

Tells whether or not a table is enabled or not.

Parameters:

conf - The Configuration object to use.

tableName - Name of table to check.

Returns:

true if table is online.

Throws:

IOException - if a remote or network exception occurs

isTableEnabled

@Deprecated
public static boolean isTableEnabled(org.apache.hadoop.conf.Configuration conf,
                                byte[] tableName)
                              throws IOException

Deprecated. use HBaseAdmin.isTableEnabled(byte[])

Tells whether or not a table is enabled or not.

Parameters:

conf - The Configuration object to use.

tableName - Name of table to check.

Returns:

true if table is online.

Throws:

IOException - if a remote or network exception occurs

isTableEnabled

@Deprecated
public static boolean isTableEnabled(org.apache.hadoop.conf.Configuration conf,
                                TableName tableName)
                              throws IOException

Deprecated. use HBaseAdmin.isTableEnabled(org.apache.hadoop.hbase.TableName tableName)

Tells whether or not a table is enabled or not.

Parameters:

conf - The Configuration object to use.

tableName - Name of table to check.

Returns:

true if table is online.

Throws:

IOException - if a remote or network exception occurs

getRegionLocation

public HRegionLocation getRegionLocation(String row)
                                  throws IOException

Find region location hosting passed row using cached info

Parameters:

row - Row to find.

Returns:

The location of the given row.

Throws:

IOException - if a remote or network exception occurs

getRegionLocation

public HRegionLocation getRegionLocation(byte[] row)
                                  throws IOException

Finds the region on which the given row is being served. Does not reload the cache.

Parameters:

row - Row to find.

Returns:

Location of the row.

Throws:

IOException - if a remote or network exception occurs

getRegionLocation

public HRegionLocation getRegionLocation(byte[] row,
                                boolean reload)
                                  throws IOException

Finds the region on which the given row is being served.

Parameters:

row - Row to find.

reload - true to reload information or false to use cached information

Returns:

Location of the row.

Throws:

IOException - if a remote or network exception occurs

getTableName

public byte[] getTableName()

Gets the name of this table.

Specified by:

getTableName in interface HTableInterface

Returns:

the table name.

getName

public TableName getName()

Description copied from interface: HTableInterface

Gets the fully qualified table name instance of this table.

Specified by:

getName in interface HTableInterface

getConnection

@Deprecated
public HConnection getConnection()

Deprecated. This method will be changed from public to package protected.

INTERNAL Used by unit tests and tools to do low-level manipulations.

Returns:

An HConnection instance.

getScannerCaching

@Deprecated
public int getScannerCaching()

Deprecated. Use Scan.setCaching(int) and Scan.getCaching()

Gets the number of rows that a scanner will fetch at once.

The default value comes from hbase.client.scanner.caching.

getWriteBuffer

@Deprecated
public List<Row> getWriteBuffer()

Deprecated. since 0.96. This is an internal buffer that should not be read nor write.

Kept in 0.96 for backward compatibility

setScannerCaching

@Deprecated
public void setScannerCaching(int scannerCaching)

Deprecated. Use Scan.setCaching(int)

Sets the number of rows that a scanner will fetch at once.

This will override the value specified by hbase.client.scanner.caching. Increasing this value will reduce the amount of work needed each time next() is called on a scanner, at the expense of memory use (since more rows will need to be maintained in memory by the scanners).

Parameters:

scannerCaching - the number of rows a scanner will fetch at once.

getTableDescriptor

public HTableDescriptor getTableDescriptor()
                                    throws IOException

Gets the table descriptor for this table.

Specified by:

getTableDescriptor in interface HTableInterface

Throws:

IOException - if a remote or network exception occurs.

getStartKeys

public byte[][] getStartKeys()
                      throws IOException

Gets the starting row key for every region in the currently open table.

This is mainly useful for the MapReduce integration.

Returns:

Array of region starting row keys

Throws:

IOException - if a remote or network exception occurs

getEndKeys

public byte[][] getEndKeys()
                    throws IOException

Gets the ending row key for every region in the currently open table.

This is mainly useful for the MapReduce integration.

Returns:

Array of region ending row keys

Throws:

IOException - if a remote or network exception occurs

getStartEndKeys

public Pair<byte[][],byte[][]> getStartEndKeys()
                                        throws IOException

Gets the starting and ending row keys for every region in the currently open table.

This is mainly useful for the MapReduce integration.

Returns:

Pair of arrays of region starting and ending row keys

Throws:

IOException - if a remote or network exception occurs

getRegionLocations

public NavigableMap<HRegionInfo,ServerName> getRegionLocations()
                                                        throws IOException

Gets all the regions and their address for this table.

This is mainly useful for the MapReduce integration.

Returns:

A map of HRegionInfo with it's server address

Throws:

IOException - if a remote or network exception occurs

getRegionsInRange

public List<HRegionLocation> getRegionsInRange(byte[] startKey,
                                      byte[] endKey)
                                        throws IOException

Get the corresponding regions for an arbitrary range of keys.

Parameters:

startKey - Starting row in range, inclusive

endKey - Ending row in range, exclusive

Returns:

A list of HRegionLocations corresponding to the regions that contain the specified range

Throws:

IOException - if a remote or network exception occurs

getRegionsInRange

public List<HRegionLocation> getRegionsInRange(byte[] startKey,
                                      byte[] endKey,
                                      boolean reload)
                                        throws IOException

Get the corresponding regions for an arbitrary range of keys.

Parameters:

startKey - Starting row in range, inclusive

endKey - Ending row in range, exclusive

reload - true to reload information or false to use cached information

Returns:

A list of HRegionLocations corresponding to the regions that contain the specified range

Throws:

IOException - if a remote or network exception occurs

getRowOrBefore

public Result getRowOrBefore(byte[] row,
                    byte[] family)
                      throws IOException

Return the row that matches row exactly, or the one that immediately precedes it.

Specified by:

getRowOrBefore in interface HTableInterface

Parameters:

row - A row key.

family - Column family to include in the Result.

Throws:

IOException - if a remote or network exception occurs.

getScanner

public ResultScanner getScanner(Scan scan)
                         throws IOException

Returns a scanner on the current table as specified by the Scan object. Note that the passed Scan's start row and caching properties maybe changed.

Specified by:

getScanner in interface HTableInterface

Parameters:

scan - A configured Scan object.

Returns:

A scanner.

Throws:

IOException - if a remote or network exception occurs.

getScanner

public ResultScanner getScanner(byte[] family)
                         throws IOException

Gets a scanner on the current table for the given family.

Specified by:

getScanner in interface HTableInterface

Parameters:

family - The column family to scan.

Returns:

A scanner.

Throws:

IOException - if a remote or network exception occurs.

getScanner

public ResultScanner getScanner(byte[] family,
                       byte[] qualifier)
                         throws IOException

Gets a scanner on the current table for the given family and qualifier.

Specified by:

getScanner in interface HTableInterface

Parameters:

family - The column family to scan.

qualifier - The column qualifier to scan.

Returns:

A scanner.

Throws:

IOException - if a remote or network exception occurs.

get

public Result get(Get get)
           throws IOException

Extracts certain cells from a given row.

Specified by:

get in interface HTableInterface

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

Throws:

IOException - if a remote or network exception occurs.

get

public Result[] get(List<Get> gets)
             throws IOException

Extracts certain cells from the given rows, in batch.

Specified by:

get in interface HTableInterface

Parameters:

gets - The objects that specify what data to fetch and from which rows.

Returns:

The data coming from the specified rows, if it exists. If the row specified doesn't exist, the Result instance returned won't contain any KeyValue, as indicated by Result.isEmpty(). If there are any failures even after retries, there will be a null in the results array for those Gets, AND an exception will be thrown.

Throws:

IOException - if a remote or network exception occurs.

batch

public void batch(List<? extends Row> actions,
         Object[] results)
           throws InterruptedException,
                  IOException

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 HTableInterface.batch(java.util.List<? extends org.apache.hadoop.hbase.client.Row>, java.lang.Object[]) call, you will not necessarily be guaranteed that the Get returns what the Put had put.

Specified by:

batch in interface HTableInterface

Parameters:

actions - list of Get, Put, Delete, Increment, Append, RowMutations objects

results - Empty Object[], same size as actions. Provides access to partial results, in case an exception is thrown. A null in the result array means that the call for that action failed, even after retries

Throws:

IOException

InterruptedException

batch

public Object[] batch(List<? extends Row> actions)
               throws InterruptedException,
                      IOException

Deprecated. If any exception is thrown by one of the actions, there is no way to retrieve the partially executed results. Use batch(List, Object[]) instead.

Same as HTableInterface.batch(List, Object[]), but returns an array of results instead of using a results parameter reference.

Specified by:

batch in interface HTableInterface

Parameters:

actions - list of Get, Put, Delete, Increment, Append, RowMutations objects

Returns:

the results from the actions. A null in the return array means that the call for that action failed, even after retries

Throws:

IOException

InterruptedException

batchCallback

public <R> void batchCallback(List<? extends Row> actions,
                     Object[] results,
                     Batch.Callback<R> callback)
                   throws IOException,
                          InterruptedException

Same as HTableInterface.batch(List, Object[]), but with a callback.

Specified by:

batchCallback in interface HTableInterface

Throws:

IOException

InterruptedException

batchCallback

public <R> Object[] batchCallback(List<? extends Row> actions,
                         Batch.Callback<R> callback)
                       throws IOException,
                              InterruptedException

Deprecated. If any exception is thrown by one of the actions, there is no way to retrieve the partially executed results. Use batchCallback(List, Object[], org.apache.hadoop.hbase.client.coprocessor.Batch.Callback) instead.

Same as HTableInterface.batch(List), but with a callback.

Specified by:

batchCallback in interface HTableInterface

Throws:

IOException

InterruptedException

delete

public void delete(Delete delete)
            throws IOException

Deletes the specified cells/row.

Specified by:

delete in interface HTableInterface

Parameters:

delete - The object that specifies what to delete.

Throws:

IOException - if a remote or network exception occurs.

delete

public void delete(List<Delete> deletes)
            throws IOException

Deletes the specified cells/rows in bulk.

Specified by:

delete in interface HTableInterface

Parameters:

deletes - List of things to delete. List gets modified by this method (in particular it gets re-ordered, so the order in which the elements are inserted in the list gives no guarantee as to the order in which the Deletes are executed).

Throws:

IOException - if a remote or network exception occurs. In that case the deletes argument will contain the Delete instances that have not be successfully applied.

put

public void put(Put put)
         throws InterruptedIOException,
                RetriesExhaustedWithDetailsException

Puts some data in the table.

If isAutoFlush is false, the update is buffered until the internal buffer is full.

Specified by:

put in interface HTableInterface

Parameters:

put - The data to put.

Throws:

InterruptedIOException

RetriesExhaustedWithDetailsException

put

public void put(List<Put> puts)
         throws InterruptedIOException,
                RetriesExhaustedWithDetailsException

Puts some data in the table, in batch.

If isAutoFlush is false, the update is buffered until the internal buffer is full.

This can be used for group commit, or for submitting user defined batches. The writeBuffer will be periodically inspected while the List is processed, so depending on the List size the writeBuffer may flush not at all, or more than once.

Specified by:

put in interface HTableInterface

Parameters:

puts - The list of mutations to apply. The batch put is done by aggregating the iteration of the Puts over the write buffer at the client-side for a single RPC call.

Throws:

InterruptedIOException

RetriesExhaustedWithDetailsException

mutateRow

public void mutateRow(RowMutations rm)
               throws IOException

Performs multiple mutations atomically on a single row. Currently Put and Delete are supported.

Specified by:

mutateRow in interface HTableInterface

Parameters:

rm - object that specifies the set of mutations to perform atomically

Throws:

IOException

append

public Result append(Append append)
              throws IOException

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.

Specified by:

append in interface HTableInterface

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)

Throws:

IOException - e

increment

public Result increment(Increment increment)
                 throws IOException

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.

Specified by:

increment in interface HTableInterface

Parameters:

increment - object that specifies the columns and amounts to be used for the increment operations

Returns:

values of columns after the increment

Throws:

IOException - e

incrementColumnValue

public long incrementColumnValue(byte[] row,
                        byte[] family,
                        byte[] qualifier,
                        long amount)
                          throws IOException

See HTableInterface.incrementColumnValue(byte[], byte[], byte[], long, Durability)

The Durability is defaulted to Durability.SYNC_WAL.

Specified by:

incrementColumnValue in interface HTableInterface

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.

Throws:

IOException - if a remote or network exception occurs.

incrementColumnValue

@Deprecated
public long incrementColumnValue(byte[] row,
                                   byte[] family,
                                   byte[] qualifier,
                                   long amount,
                                   boolean writeToWAL)
                          throws IOException

Deprecated. Use incrementColumnValue(byte[], byte[], byte[], long, Durability)

Specified by:

incrementColumnValue in interface HTableInterface

Throws:

IOException

incrementColumnValue

public long incrementColumnValue(byte[] row,
                        byte[] family,
                        byte[] qualifier,
                        long amount,
                        Durability durability)
                          throws IOException

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.

Specified by:

incrementColumnValue in interface HTableInterface

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.

Throws:

IOException - if a remote or network exception occurs.

checkAndPut

public boolean checkAndPut(byte[] row,
                  byte[] family,
                  byte[] qualifier,
                  byte[] value,
                  Put put)
                    throws IOException

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

Specified by:

checkAndPut in interface HTableInterface

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

Throws:

IOException - e

checkAndDelete

public boolean checkAndDelete(byte[] row,
                     byte[] family,
                     byte[] qualifier,
                     byte[] value,
                     Delete delete)
                       throws IOException

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

Specified by:

checkAndDelete in interface HTableInterface

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

Throws:

IOException - e

checkAndMutate

public boolean checkAndMutate(byte[] row,
                     byte[] family,
                     byte[] qualifier,
                     CompareFilter.CompareOp compareOp,
                     byte[] value,
                     RowMutations rm)
                       throws IOException

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

Specified by:

checkAndMutate in interface HTableInterface

Parameters:

row - to check

family - column family to check

qualifier - column qualifier to check

compareOp - the comparison operator

value - the expected value

rm - mutations to perform if check succeeds

Returns:

true if the new put was executed, false otherwise

Throws:

IOException - e

exists

public boolean exists(Get get)
               throws IOException

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.

Specified by:

exists in interface HTableInterface

Parameters:

get - the Get

Returns:

true if the specified Get matches one or more keys, false if not

Throws:

IOException - e

exists

public Boolean[] exists(List<Get> gets)
                 throws IOException

Test for the existence of columns in the table, as specified by the Gets.

This will return an array 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 transfered to the client.

Specified by:

exists in interface HTableInterface

Parameters:

gets - the Gets

Returns:

Array of Boolean true if the specified Get matches one or more keys, false if not

Throws:

IOException - e

flushCommits

public void flushCommits()
                  throws InterruptedIOException,
                         RetriesExhaustedWithDetailsException

Executes all the buffered Put operations.

This method gets called once automatically for every Put or batch of Puts (when put(List) is used) when HTableInterface.isAutoFlush() is true.

Specified by:

flushCommits in interface HTableInterface

Throws:

InterruptedIOException

RetriesExhaustedWithDetailsException

processBatchCallback

public <R> void processBatchCallback(List<? extends Row> list,
                            Object[] results,
                            Batch.Callback<R> callback)
                          throws IOException,
                                 InterruptedException

Process a mixed batch of Get, Put and Delete actions. All actions for a RegionServer are forwarded in one RPC call. Queries are executed in parallel.

Parameters:

list - The collection of actions.

results - An empty array, same size as list. If an exception is thrown, you can test here for partial results, and to determine which actions processed successfully.

Throws:

IOException - if there are problems talking to META. Per-item exceptions are stored in the results array.

InterruptedException

processBatch

public void processBatch(List<? extends Row> list,
                Object[] results)
                  throws IOException,
                         InterruptedException

Parameterized batch processing, allowing varying return types for different Row implementations.

Throws:

IOException

InterruptedException

close

public void close()
           throws IOException

Description copied from interface: HTableInterface

Releases any resources held or pending changes in internal buffers.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Specified by:

close in interface HTableInterface

Throws:

IOException - if a remote or network exception occurs.

validatePut

public void validatePut(Put put)
                 throws IllegalArgumentException

Throws:

IllegalArgumentException

validatePut

public static void validatePut(Put put,
               int maxKeyValueSize)
                        throws IllegalArgumentException

Throws:

IllegalArgumentException

isAutoFlush

public boolean isAutoFlush()

Tells whether or not 'auto-flush' is turned on.

Specified by:

isAutoFlush in interface HTableInterface

Returns:

true if 'auto-flush' is enabled (default), meaning Put operations don't get buffered/delayed and are immediately executed.

setAutoFlush

@Deprecated
public void setAutoFlush(boolean autoFlush)

Deprecated.

See HTableInterface.setAutoFlush(boolean, boolean)

Specified by:

setAutoFlush in interface HTableInterface

Parameters:

autoFlush - Whether or not to enable 'auto-flush'.

setAutoFlushTo

public void setAutoFlushTo(boolean autoFlush)

Set the autoFlush behavior, without changing the value of clearBufferOnFail

Specified by:

setAutoFlushTo in interface HTableInterface

setAutoFlush

public void setAutoFlush(boolean autoFlush,
                boolean clearBufferOnFail)

Turns 'auto-flush' on or off.

When enabled (default), Put operations don't get buffered/delayed and are immediately executed. Failed operations are not retried. This is slower but safer.

Turning off #autoFlush means that multiple Puts will be accepted before any RPC is actually sent to do the write operations. If the application dies before pending writes get flushed to HBase, data will be lost.

When you turn #autoFlush off, you should also consider the #clearBufferOnFail option. By default, asynchronous Put requests will be retried on failure until successful. However, this can pollute the writeBuffer and slow down batching performance. Additionally, you may want to issue a number of Put requests and call HTableInterface.flushCommits() as a barrier. In both use cases, consider setting clearBufferOnFail to true to erase the buffer after HTableInterface.flushCommits() has been called, regardless of success.

In other words, if you call #setAutoFlush(false); HBase will retry N time for each flushCommit, including the last one when closing the table. This is NOT recommended, most of the time you want to call #setAutoFlush(false, true).

Specified by:

setAutoFlush in interface HTableInterface

Parameters:

autoFlush - Whether or not to enable 'auto-flush'.

clearBufferOnFail - Whether to keep Put failures in the writeBuffer. If autoFlush is true, then the value of this parameter is ignored and clearBufferOnFail is set to true. Setting clearBufferOnFail to false is deprecated since 0.96.

See Also:

HTableInterface.flushCommits()

getWriteBufferSize

public long getWriteBufferSize()

Returns the maximum size in bytes of the write buffer for this HTable.

The default value comes from the configuration parameter hbase.client.write.buffer.

Specified by:

getWriteBufferSize in interface HTableInterface

Returns:

The size of the write buffer in bytes.

setWriteBufferSize

public void setWriteBufferSize(long writeBufferSize)
                        throws IOException

Sets the size of the buffer in bytes.

If the new size is less than the current amount of data in the write buffer, the buffer gets flushed.

Specified by:

setWriteBufferSize in interface HTableInterface

Parameters:

writeBufferSize - The new write buffer size, in bytes.

Throws:

IOException - if a remote or network exception occurs.

setRegionCachePrefetch

public static void setRegionCachePrefetch(byte[] tableName,
                          boolean enable)
                                   throws IOException

Enable or disable region cache prefetch for the table. It will be applied for the given table's all HTable instances who share the same connection. By default, the cache prefetch is enabled.

Parameters:

tableName - name of table to configure.

enable - Set to true to enable region cache prefetch. Or set to false to disable it.

Throws:

IOException

setRegionCachePrefetch

public static void setRegionCachePrefetch(TableName tableName,
                          boolean enable)
                                   throws IOException

Throws:

IOException

setRegionCachePrefetch

public static void setRegionCachePrefetch(org.apache.hadoop.conf.Configuration conf,
                          byte[] tableName,
                          boolean enable)
                                   throws IOException

Enable or disable region cache prefetch for the table. It will be applied for the given table's all HTable instances who share the same connection. By default, the cache prefetch is enabled.

Parameters:

conf - The Configuration object to use.

tableName - name of table to configure.

enable - Set to true to enable region cache prefetch. Or set to false to disable it.

Throws:

IOException

setRegionCachePrefetch

public static void setRegionCachePrefetch(org.apache.hadoop.conf.Configuration conf,
                          TableName tableName,
                          boolean enable)
                                   throws IOException

Throws:

IOException

getRegionCachePrefetch

public static boolean getRegionCachePrefetch(org.apache.hadoop.conf.Configuration conf,
                             byte[] tableName)
                                      throws IOException

Check whether region cache prefetch is enabled or not for the table.

Parameters:

conf - The Configuration object to use.

tableName - name of table to check

Returns:

true if table's region cache prefecth is enabled. Otherwise it is disabled.

Throws:

IOException

getRegionCachePrefetch

public static boolean getRegionCachePrefetch(org.apache.hadoop.conf.Configuration conf,
                             TableName tableName)
                                      throws IOException

Throws:

IOException

getRegionCachePrefetch

public static boolean getRegionCachePrefetch(byte[] tableName)
                                      throws IOException

Check whether region cache prefetch is enabled or not for the table.

Parameters:

tableName - name of table to check

Returns:

true if table's region cache prefecth is enabled. Otherwise it is disabled.

Throws:

IOException

getRegionCachePrefetch

public static boolean getRegionCachePrefetch(TableName tableName)
                                      throws IOException

Throws:

IOException

clearRegionCache

public void clearRegionCache()

Explicitly clears the region cache to fetch the latest value from META. This is a power user function: avoid unless you know the ramifications.

coprocessorService

public CoprocessorRpcChannel coprocessorService(byte[] row)

Creates and returns a RpcChannel instance connected to the table region containing the specified row. The row given does not actually have to exist. Whichever region would contain the row based on start and end keys will be used. Note that the row parameter is also not passed to the coprocessor handler registered for this protocol, unless the row is separately passed as an argument in the service request. The parameter here is only used to locate the region used to handle the call.

The obtained RpcChannel instance can be used to access a published coprocessor Service using standard protobuf service invocations:

 CoprocessorRpcChannel channel = myTable.coprocessorService(rowkey);
 MyService.BlockingInterface service = MyService.newBlockingStub(channel);
 MyCallRequest request = MyCallRequest.newBuilder()
     ...
     .build();
 MyCallResponse response = service.myCall(null, request);
 

Specified by:

coprocessorService in interface HTableInterface

Parameters:

row - The row key used to identify the remote region location

Returns:

A CoprocessorRpcChannel instance

coprocessorService

public <T extends com.google.protobuf.Service,R> Map<byte[],R> coprocessorService(Class<T> service,
                                                                         byte[] startKey,
                                                                         byte[] endKey,
                                                                         Batch.Call<T,R> callable)
                                 throws com.google.protobuf.ServiceException,
                                        Throwable

Creates an instance of the given Service subclass for each table region spanning the range from the startKey row to endKey row (inclusive), and invokes the passed Batch.Call.call(T) method with each Service instance.

Specified by:

coprocessorService in interface HTableInterface

Type Parameters:

T - the Service subclass to connect to

R - Return type for the callable parameter's Batch.Call.call(T) method

Parameters:

service - the protocol buffer Service implementation to call

startKey - start region selection with region containing this row. If null, the selection will start with the first table region.

endKey - select regions up to and including the region containing this row. If null, selection will continue through the last table region.

callable - this instance's Batch.Call.call(T) method will be invoked once per table region, using the Service instance connected to that region.

Returns:

a map of result values keyed by region name

Throws:

com.google.protobuf.ServiceException

Throwable

coprocessorService

public <T extends com.google.protobuf.Service,R> void coprocessorService(Class<T> service,
                                                                byte[] startKey,
                                                                byte[] endKey,
                                                                Batch.Call<T,R> callable,
                                                                Batch.Callback<R> callback)
                        throws com.google.protobuf.ServiceException,
                               Throwable

Creates an instance of the given Service subclass for each table region spanning the range from the startKey row to endKey row (inclusive), and invokes the passed Batch.Call.call(T) method with each Service instance.

The given Batch.Callback.update(byte[], byte[], Object) method will be called with the return value from each region's Batch.Call.call(T) invocation.

Specified by:

coprocessorService in interface HTableInterface

Type Parameters:

T - the Service subclass to connect to

R - Return type for the callable parameter's Batch.Call.call(T) method

Parameters:

service - the protocol buffer Service implementation to call

startKey - start region selection with region containing this row. If null, the selection will start with the first table region.

endKey - select regions up to and including the region containing this row. If null, selection will continue through the last table region.

callable - this instance's Batch.Call.call(T) method will be invoked once per table region, using the Service instance connected to that region.

Throws:

com.google.protobuf.ServiceException

Throwable

setOperationTimeout

public void setOperationTimeout(int operationTimeout)

getOperationTimeout

public int getOperationTimeout()

toString

public String toString()

Overrides:

toString in class Object

main

public static void main(String[] args)
                 throws IOException

Run basic test.

Parameters:

args - Pass table name and row and will get the content.

Throws:

IOException

batchCoprocessorService

public <R extends com.google.protobuf.Message> Map<byte[],R> batchCoprocessorService(com.google.protobuf.Descriptors.MethodDescriptor methodDescriptor,
                                                                            com.google.protobuf.Message request,
                                                                            byte[] startKey,
                                                                            byte[] endKey,
                                                                            R responsePrototype)
                                                                          throws com.google.protobuf.ServiceException,
                                                                                 Throwable

Creates an instance of the given Service subclass for each table region spanning the range from the startKey row to endKey row (inclusive), all the invocations to the same region server will be batched into one call. The coprocessor service is invoked according to the service instance, method name and parameters.

Specified by:

batchCoprocessorService in interface HTableInterface

Type Parameters:

R - the response type for the coprocessor Service method

Parameters:

methodDescriptor - the descriptor for the protobuf service method to call.

request - the method call parameters

startKey - start region selection with region containing this row. If null, the selection will start with the first table region.

endKey - select regions up to and including the region containing this row. If null, selection will continue through the last table region.

responsePrototype - the proto type of the response of the method in Service.

Returns:

a map of result values keyed by region name

Throws:

com.google.protobuf.ServiceException

Throwable

batchCoprocessorService

public <R extends com.google.protobuf.Message> void batchCoprocessorService(com.google.protobuf.Descriptors.MethodDescriptor methodDescriptor,
                                                                   com.google.protobuf.Message request,
                                                                   byte[] startKey,
                                                                   byte[] endKey,
                                                                   R responsePrototype,
                                                                   Batch.Callback<R> callback)
                             throws com.google.protobuf.ServiceException,
                                    Throwable

Creates an instance of the given Service subclass for each table region spanning the range from the startKey row to endKey row (inclusive), all the invocations to the same region server will be batched into one call. The coprocessor service is invoked according to the service instance, method name and parameters.

The given Batch.Callback.update(byte[],byte[],Object) method will be called with the return value from each region's invocation.

Specified by:

batchCoprocessorService in interface HTableInterface

Type Parameters:

R - the response type for the coprocessor Service method

Parameters:

methodDescriptor - the descriptor for the protobuf service method to call.

request - the method call parameters

startKey - start region selection with region containing this row. If null, the selection will start with the first table region.

endKey - select regions up to and including the region containing this row. If null, selection will continue through the last table region.

responsePrototype - the proto type of the response of the method in Service.

callback - callback to invoke with the response for each region

Throws:

com.google.protobuf.ServiceException

Throwable