org.apache.hadoop.hbase.client
Class HConnectionManager

java.lang.Object
  org.apache.hadoop.hbase.client.HConnectionManager

@InterfaceAudience.Public
@InterfaceStability.Evolving
public class HConnectionManager
extends Object

A non-instantiable class that manages HConnections. This class has a static Map of HConnection instances keyed by Configuration; all invocations of getConnection(Configuration) that pass the same Configuration instance will be returned the same HConnection instance (Adding properties to a Configuration instance does not change its object identity). Sharing HConnection instances is usually what you want; all clients of the HConnection instances share the HConnections' cache of Region locations rather than each having to discover for itself the location of meta, etc. It makes sense for the likes of the pool of HTables class HTablePool, for instance (If concerned that a single HConnection is insufficient for sharing amongst clients in say an heavily-multithreaded environment, in practise its not proven to be an issue. Besides, HConnection is implemented atop Hadoop RPC and as of this writing, Hadoop RPC does a connection per cluster-member, exclusively).

But sharing connections makes clean up of HConnection instances a little awkward. Currently, clients cleanup by calling deleteConnection(Configuration). This will shutdown the zookeeper connection the HConnection was using and clean up all HConnection resources as well as stopping proxies to servers out on the cluster. Not running the cleanup will not end the world; it'll just stall the closeup some and spew some zookeeper connection failed messages into the log. Running the cleanup on a HConnection that is subsequently used by another will cause breakage so be careful running cleanup.

To create a HConnection that is not shared by others, you can create a new Configuration instance, pass this new instance to getConnection(Configuration), and then when done, close it up by doing something like the following:

 Configuration newConfig = new Configuration(originalConf);
 HConnection connection = HConnectionManager.getConnection(newConfig);
 // Use the connection to your hearts' delight and then when done...
 HConnectionManager.deleteConnection(newConfig, true);
 
 

Cleanup used to be done inside in a shutdown hook. On startup we'd register a shutdown hook that called deleteAllConnections() on its way out but the order in which shutdown hooks run is not defined so were problematic for clients of HConnection that wanted to register their own shutdown hooks so we removed ours though this shifts the onus for cleanup to the client.

Nested Class Summary

static class	HConnectionManager.HConnectable<T> This class makes it convenient for one to execute a command in the context of a HConnection instance based on the given Configuration.
static class	HConnectionManager.HConnectionKey Denotes a unique key to a HConnection instance.

Field Summary

static String	CLIENT_PROTOCOL_CLASS Parameter name for what client protocol to use.
static String	DEFAULT_ADMIN_PROTOCOL_CLASS Default admin protocol class name.
static String	DEFAULT_CLIENT_PROTOCOL_CLASS Default client protocol class name.
static int	MAX_CACHED_HBASE_INSTANCES
static String	REGION_PROTOCOL_CLASS Parameter name for what admin protocol to use.

Constructor Summary

protected

HConnectionManager()

Method Summary

static HConnection	createConnection(org.apache.hadoop.conf.Configuration conf) Create a new HConnection instance using the passed conf instance.
static void	deleteAllConnections() Delete information for all connections.
static void	deleteConnection(org.apache.hadoop.conf.Configuration conf) Delete connection information for the instance specified by configuration.
static void	deleteStaleConnection(HConnection connection) Delete stale connection information for the instance specified by configuration.
static <T> T	execute(HConnectionManager.HConnectable<T> connectable) This convenience method invokes the given HConnectionManager.HConnectable.connect(org.apache.hadoop.hbase.client.HConnection) implementation using a HConnection instance that lasts just for the duration of that invocation.
static HConnection	getConnection(org.apache.hadoop.conf.Configuration conf) Get the connection that goes with the passed conf configuration instance.
static void	setServerSideHConnectionRetries(org.apache.hadoop.conf.Configuration c, org.apache.commons.logging.Log log) Set the number of retries to use serverside when trying to communicate with another server over HConnection.

Methods inherited from class java.lang.Object

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

Field Detail

MAX_CACHED_HBASE_INSTANCES

public static final int MAX_CACHED_HBASE_INSTANCES

CLIENT_PROTOCOL_CLASS

public static final String CLIENT_PROTOCOL_CLASS

Parameter name for what client protocol to use.

See Also:

Constant Field Values

DEFAULT_CLIENT_PROTOCOL_CLASS

public static final String DEFAULT_CLIENT_PROTOCOL_CLASS

Default client protocol class name.

REGION_PROTOCOL_CLASS

public static final String REGION_PROTOCOL_CLASS

Parameter name for what admin protocol to use.

See Also:

Constant Field Values

DEFAULT_ADMIN_PROTOCOL_CLASS

public static final String DEFAULT_ADMIN_PROTOCOL_CLASS

Default admin protocol class name.

Constructor Detail

HConnectionManager

protected HConnectionManager()

Method Detail

getConnection

public static HConnection getConnection(org.apache.hadoop.conf.Configuration conf)
                                 throws IOException

Get the connection that goes with the passed conf configuration instance. If no current connection exists, method creates a new connection for the passed conf instance.

Parameters:

conf - configuration

Returns:

HConnection object for conf

Throws:

ZooKeeperConnectionException

IOException

createConnection

public static HConnection createConnection(org.apache.hadoop.conf.Configuration conf)
                                    throws IOException

Create a new HConnection instance using the passed conf instance. Note: This bypasses the usual HConnection life cycle management! Use this with caution, the caller is responsible for closing the created connection.

Parameters:

conf - configuration

Returns:

HConnection object for conf

Throws:

ZooKeeperConnectionException

IOException

deleteConnection

public static void deleteConnection(org.apache.hadoop.conf.Configuration conf)

Delete connection information for the instance specified by configuration. If there are no more references to it, this will then close connection to the zookeeper ensemble and let go of all resources.

Parameters:

conf - configuration whose identity is used to find HConnection instance.

deleteStaleConnection

public static void deleteStaleConnection(HConnection connection)

Delete stale connection information for the instance specified by configuration. This will then close connection to the zookeeper ensemble and let go of all resources.

Parameters:

connection -

deleteAllConnections

public static void deleteAllConnections()

Delete information for all connections.

execute

public static <T> T execute(HConnectionManager.HConnectable<T> connectable)
                 throws IOException

This convenience method invokes the given HConnectionManager.HConnectable.connect(org.apache.hadoop.hbase.client.HConnection) implementation using a HConnection instance that lasts just for the duration of that invocation.

Type Parameters:

T - the return type of the connect method

Parameters:

connectable - the HConnectionManager.HConnectable instance

Returns:

the value returned by the connect method

Throws:

IOException

setServerSideHConnectionRetries

public static void setServerSideHConnectionRetries(org.apache.hadoop.conf.Configuration c,
                                                   org.apache.commons.logging.Log log)

Set the number of retries to use serverside when trying to communicate with another server over HConnection. Used updating catalog tables, etc. Call this method before we create any Connections.

Parameters:

c - The Configuration instance to set the retries into.

log - Used to log what we set in here.