org.apache.hadoop.hbase.client

Interface HConnection

All Superinterfaces:

Abortable, AutoCloseable, Closeable

All Known Subinterfaces:

StatisticsHConnection

All Known Implementing Classes:

HConnectionManager.HConnectionImplementation

@InterfaceAudience.Public
@InterfaceStability.Evolving
public interface HConnection
extends Abortable, Closeable

A cluster connection. Knows how to find the master, locate regions out on the cluster, keeps a cache of locations and then knows how to re-calibrate after they move. You need one of these to talk to your HBase cluster. HConnectionManager manages instances of this class. See it for how to get one of these.

This is NOT a connection to a particular server but to ALL servers in the cluster. Individual connections are managed at a lower level.

HConnections are used by HTable mostly but also by HBaseAdmin, and CatalogTracker. HConnection instances can be shared. Sharing is usually what you want because rather than each HConnection instance having to do its own discovery of regions out on the cluster, instead, all clients get to share the one cache of locations. HConnectionManager does the sharing for you if you go by it getting connections. Sharing makes cleanup of HConnections awkward. See HConnectionManager for cleanup discussion.

See Also:

HConnectionManager

Field Summary

Fields

Modifier and Type	Field and Description
static String	HBASE_CLIENT_CONNECTION_IMPL Key for configuration in Configuration whose value is the class we implement making a new HConnection instance.

Method Summary

Methods

Modifier and Type	Method and Description
void	clearCaches(ServerName sn) Clear any caches that pertain to server name sn.
void	clearRegionCache() Allows flushing the region cache.
void	clearRegionCache(byte[] tableName) Deprecated.
void	clearRegionCache(TableName tableName) Allows flushing the region cache of all locations that pertain to tableName
void	deleteCachedRegionLocation(HRegionLocation location) Deletes cached locations for the specific region.
AdminProtos.AdminService.BlockingInterface	getAdmin(ServerName serverName) Establishes a connection to the region server at the specified address.
AdminProtos.AdminService.BlockingInterface	getAdmin(ServerName serverName, boolean getMaster) Deprecated. You can pass master flag but nothing special is done.
ClientBackoffPolicy	getBackoffPolicy()
ClientProtos.ClientService.BlockingInterface	getClient(ServerName serverName) Establishes a connection to the region server at the specified address, and returns a region client protocol.
org.apache.hadoop.conf.Configuration	getConfiguration()
int	getCurrentNrHRS() Deprecated. This method will be changed from public to package protected.
HTableDescriptor	getHTableDescriptor(byte[] tableName) Deprecated.
HTableDescriptor	getHTableDescriptor(TableName tableName)
HTableDescriptor[]	getHTableDescriptors(List<String> tableNames) Deprecated.
HTableDescriptor[]	getHTableDescriptorsByTableName(List<TableName> tableNames)
org.apache.hadoop.hbase.client.MasterKeepAliveConnection	getKeepAliveMasterService() Deprecated. Since 0.96.0
MasterProtos.MasterService.BlockingInterface	getMaster() Returns a MasterKeepAliveConnection to the active master
NonceGenerator	getNonceGenerator()
boolean	getRegionCachePrefetch(byte[] tableName)
boolean	getRegionCachePrefetch(TableName tableName) Check whether region cache prefetch is enabled or not.
HRegionLocation	getRegionLocation(byte[] tableName, byte[] row, boolean reload) Deprecated.
HRegionLocation	getRegionLocation(TableName tableName, byte[] row, boolean reload) Find region location hosting passed row
ServerStatisticTracker	getStatisticsTracker()
HTableInterface	getTable(byte[] tableName) Retrieve an HTableInterface implementation for access to a table.
HTableInterface	getTable(byte[] tableName, ExecutorService pool) Retrieve an HTableInterface implementation for access to a table.
HTableInterface	getTable(String tableName) Retrieve an HTableInterface implementation for access to a table.
HTableInterface	getTable(String tableName, ExecutorService pool) Retrieve an HTableInterface implementation for access to a table.
HTableInterface	getTable(TableName tableName) Retrieve an HTableInterface implementation for access to a table.
HTableInterface	getTable(TableName tableName, ExecutorService pool) Retrieve an HTableInterface implementation for access to a table.
String[]	getTableNames() Deprecated.
boolean	isClosed()
boolean	isDeadServer(ServerName serverName)
boolean	isMasterRunning()
boolean	isTableAvailable(byte[] tableName) Deprecated.
boolean	isTableAvailable(byte[] tableName, byte[][] splitKeys) Deprecated.
boolean	isTableAvailable(TableName tableName)
boolean	isTableAvailable(TableName tableName, byte[][] splitKeys) Use this api to check if the table has been created with the specified number of splitkeys which was used while creating the given table.
boolean	isTableDisabled(byte[] tableName) Deprecated.
boolean	isTableDisabled(TableName tableName)
boolean	isTableEnabled(byte[] tableName) Deprecated.
boolean	isTableEnabled(TableName tableName) A table that isTableEnabled == false and isTableDisabled == false is possible.
TableName[]	listTableNames()
HTableDescriptor[]	listTables() List all the userspace tables.
HRegionLocation	locateRegion(byte[] regionName) Gets the location of the region of regionName.
HRegionLocation	locateRegion(byte[] tableName, byte[] row) Deprecated.
HRegionLocation	locateRegion(TableName tableName, byte[] row) Find the location of the region of tableName that row lives in.
List<HRegionLocation>	locateRegions(byte[] tableName) Deprecated.
List<HRegionLocation>	locateRegions(byte[] tableName, boolean useCache, boolean offlined) Deprecated.
List<HRegionLocation>	locateRegions(TableName tableName) Gets the locations of all regions in the specified table, tableName.
List<HRegionLocation>	locateRegions(TableName tableName, boolean useCache, boolean offlined) Gets the locations of all regions in the specified table, tableName.
void	processBatch(List<? extends Row> actions, byte[] tableName, ExecutorService pool, Object[] results) Deprecated.
void	processBatch(List<? extends Row> actions, TableName tableName, ExecutorService pool, Object[] results) Deprecated. since 0.96 - Use HTableInterface.batch(java.util.List<? extends org.apache.hadoop.hbase.client.Row>, java.lang.Object[]) instead
<R> void	processBatchCallback(List<? extends Row> list, byte[] tableName, ExecutorService pool, Object[] results, Batch.Callback<R> callback) Deprecated.
<R> void	processBatchCallback(List<? extends Row> list, TableName tableName, ExecutorService pool, Object[] results, Batch.Callback<R> callback) Deprecated. since 0.96 - Use HTableInterface.batchCallback(java.util.List<? extends org.apache.hadoop.hbase.client.Row>, java.lang.Object[], org.apache.hadoop.hbase.client.coprocessor.Batch.Callback<R>) instead
HRegionLocation	relocateRegion(byte[] tableName, byte[] row) Deprecated.
HRegionLocation	relocateRegion(TableName tableName, byte[] row) Find the location of the region of tableName that row lives in, ignoring any value that might be in the cache.
void	setRegionCachePrefetch(byte[] tableName, boolean enable)
void	setRegionCachePrefetch(TableName tableName, boolean enable) Enable or disable region cache prefetch for the table.
void	updateCachedLocations(byte[] tableName, byte[] rowkey, Object exception, HRegionLocation source) Deprecated.
void	updateCachedLocations(TableName tableName, byte[] rowkey, Object exception, HRegionLocation source) Update the location cache.

Methods inherited from interface org.apache.hadoop.hbase.Abortable

abort, isAborted

Methods inherited from interface java.io.Closeable

close

Field Detail

HBASE_CLIENT_CONNECTION_IMPL

static final String HBASE_CLIENT_CONNECTION_IMPL

Key for configuration in Configuration whose value is the class we implement making a new HConnection instance.

See Also:

Constant Field Values

Method Detail

getConfiguration

org.apache.hadoop.conf.Configuration getConfiguration()

Returns:

Configuration instance being used by this HConnection instance.

getTable

HTableInterface getTable(String tableName)
                         throws IOException

Retrieve an HTableInterface implementation for access to a table. The returned HTableInterface is not thread safe, a new instance should be created for each using thread. This is a lightweight operation, pooling or caching of the returned HTableInterface is neither required nor desired. Note that the HConnection needs to be unmanaged (created with HConnectionManager.createConnection(Configuration)).

Parameters:

tableName -

Returns:

an HTable to use for interactions with this table

Throws:

IOException

getTable

HTableInterface getTable(byte[] tableName)
                         throws IOException

Retrieve an HTableInterface implementation for access to a table. The returned HTableInterface is not thread safe, a new instance should be created for each using thread. This is a lightweight operation, pooling or caching of the returned HTableInterface is neither required nor desired. Note that the HConnection needs to be unmanaged (created with HConnectionManager.createConnection(Configuration)).

Parameters:

tableName -

Returns:

an HTable to use for interactions with this table

Throws:

IOException

getTable

HTableInterface getTable(TableName tableName)
                         throws IOException

Retrieve an HTableInterface implementation for access to a table. The returned HTableInterface is not thread safe, a new instance should be created for each using thread. This is a lightweight operation, pooling or caching of the returned HTableInterface is neither required nor desired. Note that the HConnection needs to be unmanaged (created with HConnectionManager.createConnection(Configuration)).

Parameters:

tableName -

Returns:

an HTable to use for interactions with this table

Throws:

IOException

getTable

HTableInterface getTable(String tableName,
                       ExecutorService pool)
                         throws IOException

Retrieve an HTableInterface implementation for access to a table. The returned HTableInterface is not thread safe, a new instance should be created for each using thread. This is a lightweight operation, pooling or caching of the returned HTableInterface is neither required nor desired. Note that the HConnection needs to be unmanaged (created with HConnectionManager.createConnection(Configuration)).

Parameters:

tableName -

pool - The thread pool to use for batch operations, null to use a default pool.

Returns:

an HTable to use for interactions with this table

Throws:

IOException

getTable

HTableInterface getTable(byte[] tableName,
                       ExecutorService pool)
                         throws IOException

Retrieve an HTableInterface implementation for access to a table. The returned HTableInterface is not thread safe, a new instance should be created for each using thread. This is a lightweight operation, pooling or caching of the returned HTableInterface is neither required nor desired. Note that the HConnection needs to be unmanaged (created with HConnectionManager.createConnection(Configuration)).

Parameters:

tableName -

pool - The thread pool to use for batch operations, null to use a default pool.

Returns:

an HTable to use for interactions with this table

Throws:

IOException

getTable

HTableInterface getTable(TableName tableName,
                       ExecutorService pool)
                         throws IOException

Retrieve an HTableInterface implementation for access to a table. The returned HTableInterface is not thread safe, a new instance should be created for each using thread. This is a lightweight operation, pooling or caching of the returned HTableInterface is neither required nor desired. Note that the HConnection needs to be unmanaged (created with HConnectionManager.createConnection(Configuration)).

Parameters:

tableName -

pool - The thread pool to use for batch operations, null to use a default pool.

Returns:

an HTable to use for interactions with this table

Throws:

IOException

isMasterRunning

boolean isMasterRunning()
                        throws MasterNotRunningException,
                               ZooKeeperConnectionException

Returns:

- true if the master server is running

Throws:

MasterNotRunningException

ZooKeeperConnectionException

isTableEnabled

boolean isTableEnabled(TableName tableName)
                       throws IOException

A table that isTableEnabled == false and isTableDisabled == false is possible. This happens when a table has a lot of regions that must be processed.

Parameters:

tableName - table name

Returns:

true if the table is enabled, false otherwise

Throws:

IOException - if a remote or network exception occurs

isTableEnabled

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

Deprecated.

Throws:

IOException

isTableDisabled

boolean isTableDisabled(TableName tableName)
                        throws IOException

Parameters:

tableName - table name

Returns:

true if the table is disabled, false otherwise

Throws:

IOException - if a remote or network exception occurs

isTableDisabled

@Deprecated
boolean isTableDisabled(byte[] tableName)
                        throws IOException

Deprecated.

Throws:

IOException

isTableAvailable

boolean isTableAvailable(TableName tableName)
                         throws IOException

Parameters:

tableName - table name

Returns:

true if all regions of the table are available, false otherwise

Throws:

IOException - if a remote or network exception occurs

isTableAvailable

@Deprecated
boolean isTableAvailable(byte[] tableName)
                         throws IOException

Deprecated.

Throws:

IOException

isTableAvailable

boolean isTableAvailable(TableName tableName,
                       byte[][] splitKeys)
                         throws IOException

Use this api to check if the table has been created with the specified number of splitkeys which was used while creating the given table. Note : If this api is used after a table's region gets splitted, the api may return false.

Parameters:

tableName - tableName

splitKeys - splitKeys used while creating table

Throws:

IOException - if a remote or network exception occurs

isTableAvailable

@Deprecated
boolean isTableAvailable(byte[] tableName,
                                  byte[][] splitKeys)
                         throws IOException

Deprecated.

Throws:

IOException

listTables

HTableDescriptor[] listTables()
                              throws IOException

List all the userspace tables. In other words, scan the hbase:meta table. If we wanted this to be really fast, we could implement a special catalog table that just contains table names and their descriptors. Right now, it only exists as part of the hbase:meta table's region info.

Returns:

- returns an array of HTableDescriptors

Throws:

IOException - if a remote or network exception occurs

getTableNames

@Deprecated
String[] getTableNames()
                       throws IOException

Deprecated.

Throws:

IOException

listTableNames

TableName[] listTableNames()
                           throws IOException

Throws:

IOException

getHTableDescriptor

HTableDescriptor getHTableDescriptor(TableName tableName)
                                     throws IOException

Parameters:

tableName - table name

Returns:

table metadata

Throws:

IOException - if a remote or network exception occurs

getHTableDescriptor

@Deprecated
HTableDescriptor getHTableDescriptor(byte[] tableName)
                                     throws IOException

Deprecated.

Throws:

IOException

locateRegion

HRegionLocation locateRegion(TableName tableName,
                           byte[] row)
                             throws IOException

Find the location of the region of tableName that row lives in.

Parameters:

tableName - name of the table row is in

row - row key you're trying to find the region of

Returns:

HRegionLocation that describes where to find the region in question

Throws:

IOException - if a remote or network exception occurs

locateRegion

@Deprecated
HRegionLocation locateRegion(byte[] tableName,
                                      byte[] row)
                             throws IOException

Deprecated.

Throws:

IOException

clearRegionCache

void clearRegionCache()

Allows flushing the region cache.

clearRegionCache

void clearRegionCache(TableName tableName)

Allows flushing the region cache of all locations that pertain to tableName

Parameters:

tableName - Name of the table whose regions we are to remove from cache.

clearRegionCache

@Deprecated
void clearRegionCache(byte[] tableName)

Deprecated.

deleteCachedRegionLocation

void deleteCachedRegionLocation(HRegionLocation location)

Deletes cached locations for the specific region.

Parameters:

location - The location object for the region, to be purged from cache.

relocateRegion

HRegionLocation relocateRegion(TableName tableName,
                             byte[] row)
                               throws IOException

Find the location of the region of tableName that row lives in, ignoring any value that might be in the cache.

Parameters:

tableName - name of the table row is in

row - row key you're trying to find the region of

Returns:

HRegionLocation that describes where to find the region in question

Throws:

IOException - if a remote or network exception occurs

relocateRegion

@Deprecated
HRegionLocation relocateRegion(byte[] tableName,
                                        byte[] row)
                               throws IOException

Deprecated.

Throws:

IOException

updateCachedLocations

void updateCachedLocations(TableName tableName,
                         byte[] rowkey,
                         Object exception,
                         HRegionLocation source)

Update the location cache. This is used internally by HBase, in most cases it should not be used by the client application.

Parameters:

tableName - the table name

rowkey - the row

exception - the exception if any. Can be null.

source - the previous location

updateCachedLocations

@Deprecated
void updateCachedLocations(byte[] tableName,
                                    byte[] rowkey,
                                    Object exception,
                                    HRegionLocation source)

Deprecated.

locateRegion

HRegionLocation locateRegion(byte[] regionName)
                             throws IOException

Gets the location of the region of regionName.

Parameters:

regionName - name of the region to locate

Returns:

HRegionLocation that describes where to find the region in question

Throws:

IOException - if a remote or network exception occurs

locateRegions

List<HRegionLocation> locateRegions(TableName tableName)
                                    throws IOException

Gets the locations of all regions in the specified table, tableName.

Parameters:

tableName - table to get regions of

Returns:

list of region locations for all regions of table

Throws:

IOException

locateRegions

@Deprecated
List<HRegionLocation> locateRegions(byte[] tableName)
                                    throws IOException

Deprecated.

Throws:

IOException

locateRegions

List<HRegionLocation> locateRegions(TableName tableName,
                                  boolean useCache,
                                  boolean offlined)
                                    throws IOException

Gets the locations of all regions in the specified table, tableName.

Parameters:

tableName - table to get regions of

useCache - Should we use the cache to retrieve the region information.

offlined - True if we are to include offlined regions, false and we'll leave out offlined regions from returned list.

Returns:

list of region locations for all regions of table

Throws:

IOException

locateRegions

@Deprecated
List<HRegionLocation> locateRegions(byte[] tableName,
                                             boolean useCache,
                                             boolean offlined)
                                    throws IOException

Deprecated.

Throws:

IOException

getMaster

MasterProtos.MasterService.BlockingInterface getMaster()
                                                       throws IOException

Returns a MasterKeepAliveConnection to the active master

Throws:

IOException

getAdmin

AdminProtos.AdminService.BlockingInterface getAdmin(ServerName serverName)
                                                    throws IOException

Establishes a connection to the region server at the specified address.

Parameters:

serverName -

Returns:

proxy for HRegionServer

Throws:

IOException - if a remote or network exception occurs

getClient

ClientProtos.ClientService.BlockingInterface getClient(ServerName serverName)
                                                       throws IOException

Establishes a connection to the region server at the specified address, and returns a region client protocol.

Parameters:

serverName -

Returns:

ClientProtocol proxy for RegionServer

Throws:

IOException - if a remote or network exception occurs

getAdmin

AdminProtos.AdminService.BlockingInterface getAdmin(ServerName serverName,
                                                  boolean getMaster)
                                                    throws IOException

Deprecated. You can pass master flag but nothing special is done.

Establishes a connection to the region server at the specified address.

Parameters:

serverName -

getMaster - do we check if master is alive

Returns:

proxy for HRegionServer

Throws:

IOException - if a remote or network exception occurs

getRegionLocation

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

Find region location hosting passed row

Parameters:

tableName - table name

row - Row to find.

reload - If true do not use cache, otherwise bypass.

Returns:

Location of row.

Throws:

IOException - if a remote or network exception occurs

getRegionLocation

@Deprecated
HRegionLocation getRegionLocation(byte[] tableName,
                                           byte[] row,
                                           boolean reload)
                                  throws IOException

Deprecated.

Throws:

IOException

processBatch

@Deprecated
void processBatch(List<? extends Row> actions,
                           TableName tableName,
                           ExecutorService pool,
                           Object[] results)
                  throws IOException,
                         InterruptedException

Deprecated. since 0.96 - Use HTableInterface.batch(java.util.List<? extends org.apache.hadoop.hbase.client.Row>, java.lang.Object[]) instead

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

Parameters:

actions - The collection of actions.

tableName - Name of the hbase table

pool - thread pool for parallel execution

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

@Deprecated
void processBatch(List<? extends Row> actions,
                           byte[] tableName,
                           ExecutorService pool,
                           Object[] results)
                  throws IOException,
                         InterruptedException

Deprecated.

Throws:

IOException

InterruptedException

processBatchCallback

@Deprecated
<R> void processBatchCallback(List<? extends Row> list,
                                       TableName tableName,
                                       ExecutorService pool,
                                       Object[] results,
                                       Batch.Callback<R> callback)
                          throws IOException,
                                 InterruptedException

Deprecated. since 0.96 - Use HTableInterface.batchCallback(java.util.List<? extends org.apache.hadoop.hbase.client.Row>, java.lang.Object[], org.apache.hadoop.hbase.client.coprocessor.Batch.Callback<R>) instead

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

Throws:

IOException

InterruptedException

processBatchCallback

@Deprecated
<R> void processBatchCallback(List<? extends Row> list,
                                       byte[] tableName,
                                       ExecutorService pool,
                                       Object[] results,
                                       Batch.Callback<R> callback)
                          throws IOException,
                                 InterruptedException

Deprecated.

Throws:

IOException

InterruptedException

setRegionCachePrefetch

void setRegionCachePrefetch(TableName tableName,
                          boolean enable)

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

Parameters:

tableName - name of table to configure.

enable - Set to true to enable region cache prefetch.

setRegionCachePrefetch

void setRegionCachePrefetch(byte[] tableName,
                          boolean enable)

getRegionCachePrefetch

boolean getRegionCachePrefetch(TableName tableName)

Check whether region cache prefetch is enabled or not.

Parameters:

tableName - name of table to check

Returns:

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

getRegionCachePrefetch

boolean getRegionCachePrefetch(byte[] tableName)

getCurrentNrHRS

int getCurrentNrHRS()
                    throws IOException

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

Returns:

the number of region servers that are currently running

Throws:

IOException - if a remote or network exception occurs

getHTableDescriptorsByTableName

HTableDescriptor[] getHTableDescriptorsByTableName(List<TableName> tableNames)
                                                   throws IOException

Parameters:

tableNames - List of table names

Returns:

HTD[] table metadata

Throws:

IOException - if a remote or network exception occurs

getHTableDescriptors

@Deprecated
HTableDescriptor[] getHTableDescriptors(List<String> tableNames)
                                        throws IOException

Deprecated.

Throws:

IOException

isClosed

boolean isClosed()

Returns:

true if this connection is closed

clearCaches

void clearCaches(ServerName sn)

Clear any caches that pertain to server name sn.

Parameters:

sn - A server name

getKeepAliveMasterService

@Deprecated
org.apache.hadoop.hbase.client.MasterKeepAliveConnection getKeepAliveMasterService()
                                                                                   throws MasterNotRunningException

Deprecated. Since 0.96.0

This function allows HBaseAdmin and potentially others to get a shared MasterService connection.

Returns:

The shared instance. Never returns null.

Throws:

MasterNotRunningException

isDeadServer

boolean isDeadServer(ServerName serverName)

Parameters:

serverName -

Returns:

true if the server is known as dead, false otherwise.

getNonceGenerator

NonceGenerator getNonceGenerator()

Returns:

Nonce generator for this HConnection; may be null if disabled in configuration.

getStatisticsTracker

ServerStatisticTracker getStatisticsTracker()

Returns:

the current statistics tracker associated with this connection

getBackoffPolicy

ClientBackoffPolicy getBackoffPolicy()

Returns:

the configured client backoff policy