org.apache.hadoop.hbase.client
Interface HConnection

All Superinterfaces:

Abortable, Closeable

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

Cluster connection. Hosts a connection to the ZooKeeper ensemble and thereafter into the HBase cluster. Knows how to locate regions out on the cluster, keeps a cache of locations and then knows how to recalibrate after they move. HConnectionManager manages instances of this class.

HConnections are used by HTable mostly but also by HBaseAdmin, CatalogTracker, and ZooKeeperWatcher. 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. Sharing makes cleanup of HConnections awkward. See HConnectionManager for cleanup discussion.

See Also:

HConnectionManager

Method Summary

void	clearCaches(ServerName sn) Clear any caches that pertain to server name sn
void	clearRegionCache() Allows flushing the region cache.
void	clearRegionCache(byte[] tableName) Allows flushing the region cache of all locations that pertain to tableName
AdminProtocol	getAdmin(ServerName serverName) Establishes a connection to the region server at the specified address.
AdminProtocol	getAdmin(ServerName serverName, boolean getMaster) Establishes a connection to the region server at the specified address.
AdminProtocol	getAdmin(String hostname, int port) Deprecated. - use @link {#getAdmin(final ServerName serverName)} which takes into account the startCode
AdminProtocol	getAdmin(String hostname, int port, boolean getMaster) Deprecated. use @link {#getAdmin(final ServerName serverName, boolean getMaster)} which takes into account the startCode.
ClientProtocol	getClient(ServerName serverName) Establishes a connection to the region server at the specified address, and return a region client protocol.
ClientProtocol	getClient(String hostname, int port) Deprecated. - use @link {#getClient(final ServerName serverName)} which takes into account the startCode
org.apache.hadoop.conf.Configuration	getConfiguration()
int	getCurrentNrHRS() Deprecated. This method will be changed from public to package protected.
HTableDescriptor	getHTableDescriptor(byte[] tableName)
HTableDescriptor[]	getHTableDescriptors(List<String> tableNames)
org.apache.hadoop.hbase.client.MasterAdminKeepAliveConnection	getKeepAliveMasterAdmin() This function allows HBaseAdmin and potentially others to get a shared MasterAdminProtocol connection.
org.apache.hadoop.hbase.client.MasterMonitorKeepAliveConnection	getKeepAliveMasterMonitor() This function allows HBaseAdminProtocol and potentially others to get a shared MasterMonitor connection.
MasterAdminProtocol	getMasterAdmin() Returns a MasterAdminProtocol to the active master
MasterMonitorProtocol	getMasterMonitor() Returns an MasterMonitorProtocol to the active master
boolean	getRegionCachePrefetch(byte[] tableName) Check whether region cache prefetch is enabled or not.
HRegionLocation	getRegionLocation(byte[] tableName, byte[] row, boolean reload) Find region location hosting passed row
<T> T	getRegionServerWithoutRetries(ServerCallable<T> callable) Deprecated.
<T> T	getRegionServerWithRetries(ServerCallable<T> callable) Deprecated.
ZooKeeperWatcher	getZooKeeperWatcher() Deprecated. Removed because it was a mistake exposing zookeeper in this interface (ZooKeeper is an implementation detail). Deprecated in HBase 0.94
boolean	isClosed()
boolean	isDeadServer(ServerName serverName)
boolean	isMasterRunning()
boolean	isTableAvailable(byte[] tableName)
boolean	isTableAvailable(byte[] 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)
boolean	isTableEnabled(byte[] tableName) A table that isTableEnabled == false and isTableDisabled == false is possible.
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) Find the location of the region of tableName that row lives in.
List<HRegionLocation>	locateRegions(byte[] tableName) Gets the locations of all regions in the specified table, tableName.
List<HRegionLocation>	locateRegions(byte[] 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. since 0.96 - Use HTableInterface.batch(java.util.List, java.lang.Object[]) instead
<R> void	processBatchCallback(List<? extends Row> list, byte[] tableName, ExecutorService pool, Object[] results, Batch.Callback<R> callback) Deprecated. since 0.96 - Use HTableInterface.batchCallback(java.util.List, java.lang.Object[], org.apache.hadoop.hbase.client.coprocessor.Batch.Callback) instead
HRegionLocation	relocateRegion(byte[] 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) Enable or disable region cache prefetch for the table.

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

abort, isAborted

Methods inherited from interface java.io.Closeable

close

Method Detail

getConfiguration

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

Returns:

Configuration instance being used by this HConnection instance.

getZooKeeperWatcher

@Deprecated
ZooKeeperWatcher getZooKeeperWatcher()
                                     throws IOException

Deprecated. Removed because it was a mistake exposing zookeeper in this interface (ZooKeeper is an implementation detail). Deprecated in HBase 0.94

Retrieve ZooKeeperWatcher used by this connection.

Returns:

ZooKeeperWatcher handle being used by the connection.

Throws:

IOException - if a remote or network exception occurs

isMasterRunning

boolean isMasterRunning()
                        throws MasterNotRunningException,
                               ZooKeeperConnectionException

Returns:

- true if the master server is running

Throws:

MasterNotRunningException

ZooKeeperConnectionException

isTableEnabled

boolean isTableEnabled(byte[] 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

isTableDisabled

boolean isTableDisabled(byte[] 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

isTableAvailable

boolean isTableAvailable(byte[] 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

boolean isTableAvailable(byte[] 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

listTables

HTableDescriptor[] listTables()
                              throws IOException

List all the userspace tables. In other words, scan the 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 META table's region info.

Returns:

- returns an array of HTableDescriptors

Throws:

IOException - if a remote or network exception occurs

getHTableDescriptor

HTableDescriptor getHTableDescriptor(byte[] tableName)
                                     throws IOException

Parameters:

tableName - table name

Returns:

table metadata

Throws:

IOException - if a remote or network exception occurs

locateRegion

HRegionLocation locateRegion(byte[] 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

clearRegionCache

void clearRegionCache()

Allows flushing the region cache.

clearRegionCache

void clearRegionCache(byte[] 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.

relocateRegion

HRegionLocation relocateRegion(byte[] 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

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(byte[] 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

List<HRegionLocation> locateRegions(byte[] 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

getMasterAdmin

MasterAdminProtocol getMasterAdmin()
                                   throws IOException

Returns a MasterAdminProtocol to the active master

Throws:

IOException

getMasterMonitor

MasterMonitorProtocol getMasterMonitor()
                                       throws IOException

Returns an MasterMonitorProtocol to the active master

Throws:

IOException

getAdmin

@Deprecated
AdminProtocol getAdmin(String hostname,
                                  int port)
                       throws IOException

Deprecated. - use @link {#getAdmin(final ServerName serverName)} which takes into account the startCode

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

Parameters:

hostname - RegionServer hostname

port - RegionServer port

Returns:

proxy for HRegionServer

Throws:

IOException - if a remote or network exception occurs

getAdmin

AdminProtocol 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

@Deprecated
ClientProtocol getClient(String hostname,
                                    int port)
                         throws IOException

Deprecated. - use @link {#getClient(final ServerName serverName)} which takes into account the startCode

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

Parameters:

hostname - RegionServer hostname

port - RegionServer port

Returns:

ClientProtocol proxy for RegionServer

Throws:

IOException - if a remote or network exception occurs

getClient

ClientProtocol getClient(ServerName serverName)
                         throws IOException

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

Parameters:

serverName -

Returns:

ClientProtocol proxy for RegionServer

Throws:

IOException - if a remote or network exception occurs

getAdmin

@Deprecated
AdminProtocol getAdmin(String hostname,
                                  int port,
                                  boolean getMaster)
                       throws IOException

Deprecated. use @link {#getAdmin(final ServerName serverName, boolean getMaster)} which takes into account the startCode.

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

Parameters:

hostname - RegionServer hostname

port - RegionServer port

getMaster - - do we check if master is alive

Returns:

proxy for HRegionServer

Throws:

IOException - if a remote or network exception occurs

getAdmin

AdminProtocol getAdmin(ServerName serverName,
                       boolean getMaster)
                       throws IOException

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(byte[] 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

getRegionServerWithRetries

@Deprecated
<T> T getRegionServerWithRetries(ServerCallable<T> callable)
                             throws IOException,
                                    RuntimeException

Deprecated.

Pass in a ServerCallable with your particular bit of logic defined and this method will manage the process of doing retries with timed waits and refinds of missing regions.

Type Parameters:

T - the type of the return value

Parameters:

callable - callable to run

Returns:

an object of type T

Throws:

IOException - if a remote or network exception occurs

RuntimeException - other unspecified error

getRegionServerWithoutRetries

@Deprecated
<T> T getRegionServerWithoutRetries(ServerCallable<T> callable)
                                throws IOException,
                                       RuntimeException

Deprecated.

Pass in a ServerCallable with your particular bit of logic defined and this method will pass it to the defined region server.

Type Parameters:

T - the type of the return value

Parameters:

callable - callable to run

Returns:

an object of type T

Throws:

IOException - if a remote or network exception occurs

RuntimeException - other unspecified error

processBatch

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

Deprecated. since 0.96 - Use HTableInterface.batch(java.util.List, 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

processBatchCallback

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

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

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

Throws:

IOException

InterruptedException

setRegionCachePrefetch

void setRegionCachePrefetch(byte[] 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.

getRegionCachePrefetch

boolean getRegionCachePrefetch(byte[] 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.

getCurrentNrHRS

@Deprecated
int getCurrentNrHRS()
                    throws IOException

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

Scan zookeeper to get the number of region servers

Returns:

the number of region servers that are currently running

Throws:

IOException - if a remote or network exception occurs

getHTableDescriptors

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

Parameters:

tableNames - List of table names

Returns:

HTD[] table metadata

Throws:

IOException - if a remote or network exception occurs

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

getKeepAliveMasterMonitor

org.apache.hadoop.hbase.client.MasterMonitorKeepAliveConnection getKeepAliveMasterMonitor()
                                                                                          throws MasterNotRunningException

This function allows HBaseAdminProtocol and potentially others to get a shared MasterMonitor connection.

Returns:

The shared instance. Never returns null.

Throws:

MasterNotRunningException

getKeepAliveMasterAdmin

org.apache.hadoop.hbase.client.MasterAdminKeepAliveConnection getKeepAliveMasterAdmin()
                                                                                      throws MasterNotRunningException

This function allows HBaseAdmin and potentially others to get a shared MasterAdminProtocol 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.