org.apache.hadoop.hbase.client
Interface HConnection

All Superinterfaces:
Abortable, Closeable
All Known Implementing Classes:
CoprocessorHConnection

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(String 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
 void deleteCachedRegionLocation(HRegionLocation location)
          Deletes cached locations for the specific region.
 org.apache.hadoop.conf.Configuration getConfiguration()
           
 int getCurrentNrHRS()
          Deprecated. This method will be changed from public to package protected.
 HRegionInterface getHRegionConnection(HServerAddress regionServer)
          Deprecated. Use getHRegionConnection(String, int)
 HRegionInterface getHRegionConnection(HServerAddress regionServer, boolean getMaster)
          Deprecated. Use getHRegionConnection(HServerAddress, boolean)
 HRegionInterface getHRegionConnection(String hostname, int port)
          Establishes a connection to the region server at the specified address.
 HRegionInterface getHRegionConnection(String hostname, int port, boolean getMaster)
          Establishes a connection to the region server at the specified address.
 HTableDescriptor getHTableDescriptor(byte[] tableName)
           
 HTableDescriptor[] getHTableDescriptors(List<String> tableNames)
           
 HMasterInterface getMaster()
          Deprecated. Removed because it was a mistake exposing master in this interface (master is an implementation detail). Master functions are available from HConnection or HBaseAdmin, without having to use directly the master. Deprecated in HBase 0.94
 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. Use HConnectionManager#withoutRetries(ServerCallable)
<T> T
getRegionServerWithRetries(ServerCallable<T> callable)
          Deprecated. Use HConnectionManager#withoutRetries(ServerCallable)
 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.
 String[] getTableNames()
           
 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 isMasterRunning()
           
 boolean isTableAvailable(byte[] tableName)
           
 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 prewarmRegionCache(byte[] tableName, Map<HRegionInfo,HServerAddress> regions)
          Load the region map and warm up the global region cache for the table.
 void processBatch(List<? extends Row> actions, byte[] tableName, ExecutorService pool, Object[] results)
          Process a mixed batch of Get, Put and Delete actions.
<R> void
processBatchCallback(List<? extends Row> list, byte[] tableName, ExecutorService pool, Object[] results, Batch.Callback<R> callback)
          Parameterized batch processing, allowing varying return types for different Row implementations.
<T extends CoprocessorProtocol,R>
void
processExecs(Class<T> protocol, List<byte[]> rows, byte[] tableName, ExecutorService pool, Batch.Call<T,R> call, Batch.Callback<R> callback)
          Executes the given Batch.Call callable for each row in the given list and invokes Batch.Callback.update(byte[], byte[], Object) for each result returned.
 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.

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

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

getMaster

@Deprecated
HMasterInterface getMaster()
                           throws MasterNotRunningException,
                                  ZooKeeperConnectionException
Deprecated. Removed because it was a mistake exposing master in this interface (master is an implementation detail). Master functions are available from HConnection or HBaseAdmin, without having to use directly the master. Deprecated in HBase 0.94

Returns:
proxy connection to master server for this instance
Throws:
MasterNotRunningException - if the master is not running
ZooKeeperConnectionException - if unable to connect to zookeeper

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

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.

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

getHRegionConnection

HRegionInterface getHRegionConnection(HServerAddress regionServer)
                                      throws IOException
Deprecated. Use getHRegionConnection(String, int)

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

Parameters:
regionServer - - the server to connect to
Returns:
proxy for HRegionServer
Throws:
IOException - if a remote or network exception occurs

getHRegionConnection

HRegionInterface getHRegionConnection(String hostname,
                                      int port)
                                      throws IOException
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

getHRegionConnection

HRegionInterface getHRegionConnection(HServerAddress regionServer,
                                      boolean getMaster)
                                      throws IOException
Deprecated. Use getHRegionConnection(HServerAddress, boolean)

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

Parameters:
regionServer - - the server to connect to
getMaster - - do we check if master is alive
Returns:
proxy for HRegionServer
Throws:
IOException - if a remote or network exception occurs

getHRegionConnection

HRegionInterface getHRegionConnection(String hostname,
                                      int port,
                                      boolean getMaster)
                                      throws IOException
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

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

<T> T getRegionServerWithRetries(ServerCallable<T> callable)
                             throws IOException,
                                    RuntimeException
Deprecated. Use HConnectionManager#withoutRetries(ServerCallable)

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

<T> T getRegionServerWithoutRetries(ServerCallable<T> callable)
                                throws IOException,
                                       RuntimeException
Deprecated. Use HConnectionManager#withoutRetries(ServerCallable)

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

void processBatch(List<? extends Row> actions,
                  byte[] tableName,
                  ExecutorService pool,
                  Object[] results)
                  throws IOException,
                         InterruptedException
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

<R> void processBatchCallback(List<? extends Row> list,
                              byte[] tableName,
                              ExecutorService pool,
                              Object[] results,
                              Batch.Callback<R> callback)
                          throws IOException,
                                 InterruptedException
Parameterized batch processing, allowing varying return types for different Row implementations.

Throws:
IOException
InterruptedException

processExecs

<T extends CoprocessorProtocol,R> void processExecs(Class<T> protocol,
                                                    List<byte[]> rows,
                                                    byte[] tableName,
                                                    ExecutorService pool,
                                                    Batch.Call<T,R> call,
                                                    Batch.Callback<R> callback)
                  throws IOException,
                         Throwable
Executes the given Batch.Call callable for each row in the given list and invokes Batch.Callback.update(byte[], byte[], Object) for each result returned.

Type Parameters:
T - the protocol interface type
R - the callable's return type
Parameters:
protocol - the protocol interface being called
rows - a list of row keys for which the callable should be invoked
tableName - table name for the coprocessor invoked
pool - ExecutorService used to submit the calls per row
call - instance on which to invoke Batch.Call.call(Object) for each row
callback - instance on which to invoke Batch.Callback.update(byte[], byte[], Object) for each result
Throws:
IOException
Throwable

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.

prewarmRegionCache

void prewarmRegionCache(byte[] tableName,
                        Map<HRegionInfo,HServerAddress> regions)
Load the region map and warm up the global region cache for the table.

Parameters:
tableName - name of the table to perform region cache prewarm.
regions - a region map.

getCurrentNrHRS

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

getTableNames

String[] getTableNames()
                       throws IOException
Returns:
string[] table names
Throws:
IOException - if a remote or network exception occurs

isClosed

boolean isClosed()
Returns:
true if this connection is closed

clearCaches

void clearCaches(String sn)
Clear any caches that pertain to server name sn

Parameters:
sn - A server name as hostname:port


Copyright © 2013 The Apache Software Foundation. All Rights Reserved.