1 /** 2 * Copyright 2010 The Apache Software Foundation 3 * 4 * Licensed to the Apache Software Foundation (ASF) under one 5 * or more contributor license agreements. See the NOTICE file 6 * distributed with this work for additional information 7 * regarding copyright ownership. The ASF licenses this file 8 * to you under the Apache License, Version 2.0 (the 9 * "License"); you may not use this file except in compliance 10 * with the License. You may obtain a copy of the License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 14 * Unless required by applicable law or agreed to in writing, software 15 * distributed under the License is distributed on an "AS IS" BASIS, 16 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 17 * See the License for the specific language governing permissions and 18 * limitations under the License. 19 */ 20 package org.apache.hadoop.hbase.client; 21 22 import java.io.Closeable; 23 import java.io.IOException; 24 import java.util.List; 25 import java.util.Map; 26 import java.util.concurrent.ExecutorService; 27 28 import org.apache.hadoop.conf.Configuration; 29 import org.apache.hadoop.hbase.Abortable; 30 import org.apache.hadoop.hbase.HRegionInfo; 31 import org.apache.hadoop.hbase.HRegionLocation; 32 import org.apache.hadoop.hbase.HServerAddress; 33 import org.apache.hadoop.hbase.HTableDescriptor; 34 import org.apache.hadoop.hbase.MasterNotRunningException; 35 import org.apache.hadoop.hbase.ZooKeeperConnectionException; 36 import org.apache.hadoop.hbase.catalog.CatalogTracker; 37 import org.apache.hadoop.hbase.client.coprocessor.Batch; 38 import org.apache.hadoop.hbase.ipc.CoprocessorProtocol; 39 import org.apache.hadoop.hbase.ipc.HMasterInterface; 40 import org.apache.hadoop.hbase.ipc.HRegionInterface; 41 import org.apache.hadoop.hbase.zookeeper.ZooKeeperWatcher; 42 43 /** 44 * Cluster connection. Hosts a connection to the ZooKeeper ensemble and 45 * thereafter into the HBase cluster. Knows how to locate regions out on the cluster, 46 * keeps a cache of locations and then knows how to recalibrate after they move. 47 * {@link HConnectionManager} manages instances of this class. 48 * 49 * <p>HConnections are used by {@link HTable} mostly but also by 50 * {@link HBaseAdmin}, {@link CatalogTracker}, 51 * and {@link ZooKeeperWatcher}. HConnection instances can be shared. Sharing 52 * is usually what you want because rather than each HConnection instance 53 * having to do its own discovery of regions out on the cluster, instead, all 54 * clients get to share the one cache of locations. Sharing makes cleanup of 55 * HConnections awkward. See {@link HConnectionManager} for cleanup 56 * discussion. 57 * 58 * @see HConnectionManager 59 */ 60 public interface HConnection extends Abortable, Closeable { 61 /** 62 * @return Configuration instance being used by this HConnection instance. 63 */ 64 public Configuration getConfiguration(); 65 66 /** 67 * Retrieve an HTableInterface implementation for access to a table. 68 * The returned HTableInterface is not thread safe, a new instance should 69 * be created for each using thread. 70 * This is a lightweight operation, pooling or caching of the returned HTableInterface 71 * is neither required nor desired. 72 * Note that the HConnection needs to be unmanaged 73 * (created with {@link HConnectionManager#createConnection(Configuration)}). 74 * @param tableName 75 * @return an HTable to use for interactions with this table 76 */ 77 public HTableInterface getTable(String tableName) throws IOException; 78 79 /** 80 * Retrieve an HTableInterface implementation for access to a table. 81 * The returned HTableInterface is not thread safe, a new instance should 82 * be created for each using thread. 83 * This is a lightweight operation, pooling or caching of the returned HTableInterface 84 * is neither required nor desired. 85 * Note that the HConnection needs to be unmanaged 86 * (created with {@link HConnectionManager#createConnection(Configuration)}). 87 * @param tableName 88 * @return an HTable to use for interactions with this table 89 */ 90 public HTableInterface getTable(byte[] tableName) throws IOException; 91 92 /** 93 * Retrieve an HTableInterface implementation for access to a table. 94 * The returned HTableInterface is not thread safe, a new instance should 95 * be created for each using thread. 96 * This is a lightweight operation, pooling or caching of the returned HTableInterface 97 * is neither required nor desired. 98 * Note that the HConnection needs to be unmanaged 99 * (created with {@link HConnectionManager#createConnection(Configuration)}). 100 * @param tableName 101 * @param pool The thread pool to use for batch operations, null to use a default pool. 102 * @return an HTable to use for interactions with this table 103 */ 104 public HTableInterface getTable(String tableName, ExecutorService pool) throws IOException; 105 106 /** 107 * Retrieve an HTableInterface implementation for access to a table. 108 * The returned HTableInterface is not thread safe, a new instance should 109 * be created for each using thread. 110 * This is a lightweight operation, pooling or caching of the returned HTableInterface 111 * is neither required nor desired. 112 * Note that the HConnection needs to be unmanaged 113 * (created with {@link HConnectionManager#createConnection(Configuration)}). 114 * @param tableName 115 * @param pool The thread pool to use for batch operations, null to use a default pool. 116 * @return an HTable to use for interactions with this table 117 */ 118 public HTableInterface getTable(byte[] tableName, ExecutorService pool) throws IOException; 119 120 /** 121 * Retrieve ZooKeeperWatcher used by this connection. 122 * @return ZooKeeperWatcher handle being used by the connection. 123 * @throws IOException if a remote or network exception occurs 124 * @deprecated Removed because it was a mistake exposing zookeeper in this 125 * interface (ZooKeeper is an implementation detail). 126 * Deprecated in HBase 0.94 127 */ 128 @Deprecated 129 public ZooKeeperWatcher getZooKeeperWatcher() throws IOException; 130 131 /** 132 * @return proxy connection to master server for this instance 133 * @throws MasterNotRunningException if the master is not running 134 * @throws ZooKeeperConnectionException if unable to connect to zookeeper 135 * @deprecated Removed because it was a mistake exposing master in this 136 * interface (master is an implementation detail). Master functions are 137 * available from HConnection or HBaseAdmin, without having to use 138 * directly the master. 139 * Deprecated in HBase 0.94 140 */ 141 @Deprecated 142 public HMasterInterface getMaster() 143 throws MasterNotRunningException, ZooKeeperConnectionException; 144 145 /** @return - true if the master server is running */ 146 public boolean isMasterRunning() 147 throws MasterNotRunningException, ZooKeeperConnectionException; 148 149 /** 150 * A table that isTableEnabled == false and isTableDisabled == false 151 * is possible. This happens when a table has a lot of regions 152 * that must be processed. 153 * @param tableName table name 154 * @return true if the table is enabled, false otherwise 155 * @throws IOException if a remote or network exception occurs 156 */ 157 public boolean isTableEnabled(byte[] tableName) throws IOException; 158 159 /** 160 * @param tableName table name 161 * @return true if the table is disabled, false otherwise 162 * @throws IOException if a remote or network exception occurs 163 */ 164 public boolean isTableDisabled(byte[] tableName) throws IOException; 165 166 /** 167 * @param tableName table name 168 * @return true if all regions of the table are available, false otherwise 169 * @throws IOException if a remote or network exception occurs 170 */ 171 public boolean isTableAvailable(byte[] tableName) throws IOException; 172 173 /** 174 * List all the userspace tables. In other words, scan the META table. 175 * 176 * If we wanted this to be really fast, we could implement a special 177 * catalog table that just contains table names and their descriptors. 178 * Right now, it only exists as part of the META table's region info. 179 * 180 * @return - returns an array of HTableDescriptors 181 * @throws IOException if a remote or network exception occurs 182 */ 183 public HTableDescriptor[] listTables() throws IOException; 184 185 /** 186 * @param tableName table name 187 * @return table metadata 188 * @throws IOException if a remote or network exception occurs 189 */ 190 public HTableDescriptor getHTableDescriptor(byte[] tableName) 191 throws IOException; 192 193 /** 194 * Find the location of the region of <i>tableName</i> that <i>row</i> 195 * lives in. 196 * @param tableName name of the table <i>row</i> is in 197 * @param row row key you're trying to find the region of 198 * @return HRegionLocation that describes where to find the region in 199 * question 200 * @throws IOException if a remote or network exception occurs 201 */ 202 public HRegionLocation locateRegion(final byte [] tableName, 203 final byte [] row) 204 throws IOException; 205 206 /** 207 * Allows flushing the region cache. 208 */ 209 public void clearRegionCache(); 210 211 /** 212 * Allows flushing the region cache of all locations that pertain to 213 * <code>tableName</code> 214 * @param tableName Name of the table whose regions we are to remove from 215 * cache. 216 */ 217 public void clearRegionCache(final byte [] tableName); 218 219 /** 220 * Deletes cached locations for the specific region. 221 * @param location The location object for the region, to be purged from cache. 222 */ 223 public void deleteCachedRegionLocation(final HRegionLocation location); 224 225 /** 226 * Find the location of the region of <i>tableName</i> that <i>row</i> 227 * lives in, ignoring any value that might be in the cache. 228 * @param tableName name of the table <i>row</i> is in 229 * @param row row key you're trying to find the region of 230 * @return HRegionLocation that describes where to find the region in 231 * question 232 * @throws IOException if a remote or network exception occurs 233 */ 234 public HRegionLocation relocateRegion(final byte [] tableName, 235 final byte [] row) 236 throws IOException; 237 238 /** 239 * Gets the location of the region of <i>regionName</i>. 240 * @param regionName name of the region to locate 241 * @return HRegionLocation that describes where to find the region in 242 * question 243 * @throws IOException if a remote or network exception occurs 244 */ 245 public HRegionLocation locateRegion(final byte [] regionName) 246 throws IOException; 247 248 /** 249 * Gets the locations of all regions in the specified table, <i>tableName</i>. 250 * @param tableName table to get regions of 251 * @return list of region locations for all regions of table 252 * @throws IOException 253 */ 254 public List<HRegionLocation> locateRegions(final byte[] tableName) 255 throws IOException; 256 257 /** 258 * Gets the locations of all regions in the specified table, <i>tableName</i>. 259 * @param tableName table to get regions of 260 * @param useCache Should we use the cache to retrieve the region information. 261 * @param offlined True if we are to include offlined regions, false and we'll leave out offlined 262 * regions from returned list. 263 * @return list of region locations for all regions of table 264 * @throws IOException 265 */ 266 public List<HRegionLocation> locateRegions(final byte[] tableName, final boolean useCache, 267 final boolean offlined) throws IOException; 268 269 /** 270 * Establishes a connection to the region server at the specified address. 271 * @param regionServer - the server to connect to 272 * @return proxy for HRegionServer 273 * @throws IOException if a remote or network exception occurs 274 * @deprecated Use {@link #getHRegionConnection(String, int)} 275 */ 276 public HRegionInterface getHRegionConnection(HServerAddress regionServer) 277 throws IOException; 278 279 /** 280 * Establishes a connection to the region server at the specified address. 281 * @param hostname RegionServer hostname 282 * @param port RegionServer port 283 * @return proxy for HRegionServer 284 * @throws IOException if a remote or network exception occurs 285 * 286 */ 287 public HRegionInterface getHRegionConnection(final String hostname, final int port) 288 throws IOException; 289 290 /** 291 * Establishes a connection to the region server at the specified address. 292 * @param regionServer - the server to connect to 293 * @param getMaster - do we check if master is alive 294 * @return proxy for HRegionServer 295 * @throws IOException if a remote or network exception occurs 296 * @deprecated Use {@link #getHRegionConnection(HServerAddress, boolean)} 297 */ 298 public HRegionInterface getHRegionConnection(HServerAddress regionServer, 299 boolean getMaster) 300 throws IOException; 301 302 /** 303 * Establishes a connection to the region server at the specified address. 304 * @param hostname RegionServer hostname 305 * @param port RegionServer port 306 * @param getMaster - do we check if master is alive 307 * @return proxy for HRegionServer 308 * @throws IOException if a remote or network exception occurs 309 */ 310 public HRegionInterface getHRegionConnection(final String hostname, 311 final int port, boolean getMaster) 312 throws IOException; 313 314 /** 315 * Find region location hosting passed row 316 * @param tableName table name 317 * @param row Row to find. 318 * @param reload If true do not use cache, otherwise bypass. 319 * @return Location of row. 320 * @throws IOException if a remote or network exception occurs 321 */ 322 HRegionLocation getRegionLocation(byte [] tableName, byte [] row, 323 boolean reload) 324 throws IOException; 325 326 /** 327 * Pass in a ServerCallable with your particular bit of logic defined and 328 * this method will manage the process of doing retries with timed waits 329 * and refinds of missing regions. 330 * 331 * @param <T> the type of the return value 332 * @param callable callable to run 333 * @return an object of type T 334 * @throws IOException if a remote or network exception occurs 335 * @throws RuntimeException other unspecified error 336 * @deprecated Use {@link HConnectionManager#withoutRetries(ServerCallable)} 337 */ 338 public <T> T getRegionServerWithRetries(ServerCallable<T> callable) 339 throws IOException, RuntimeException; 340 341 /** 342 * Pass in a ServerCallable with your particular bit of logic defined and 343 * this method will pass it to the defined region server. 344 * @param <T> the type of the return value 345 * @param callable callable to run 346 * @return an object of type T 347 * @throws IOException if a remote or network exception occurs 348 * @throws RuntimeException other unspecified error 349 * @deprecated Use {@link HConnectionManager#withoutRetries(ServerCallable)} 350 */ 351 public <T> T getRegionServerWithoutRetries(ServerCallable<T> callable) 352 throws IOException, RuntimeException; 353 354 /** 355 * Process a mixed batch of Get, Put and Delete actions. All actions for a 356 * RegionServer are forwarded in one RPC call. 357 * 358 * 359 * @param actions The collection of actions. 360 * @param tableName Name of the hbase table 361 * @param pool thread pool for parallel execution 362 * @param results An empty array, same size as list. If an exception is thrown, 363 * you can test here for partial results, and to determine which actions 364 * processed successfully. 365 * @throws IOException if there are problems talking to META. Per-item 366 * exceptions are stored in the results array. 367 */ 368 public void processBatch(List<? extends Row> actions, final byte[] tableName, 369 ExecutorService pool, Object[] results) 370 throws IOException, InterruptedException; 371 372 /** 373 * Parameterized batch processing, allowing varying return types for different 374 * {@link Row} implementations. 375 */ 376 public <R> void processBatchCallback(List<? extends Row> list, 377 byte[] tableName, 378 ExecutorService pool, 379 Object[] results, 380 Batch.Callback<R> callback) throws IOException, InterruptedException; 381 382 383 /** 384 * Executes the given 385 * {@link org.apache.hadoop.hbase.client.coprocessor.Batch.Call} 386 * callable for each row in the given list and invokes 387 * {@link org.apache.hadoop.hbase.client.coprocessor.Batch.Callback#update(byte[], byte[], Object)} 388 * for each result returned. 389 * 390 * @param protocol the protocol interface being called 391 * @param rows a list of row keys for which the callable should be invoked 392 * @param tableName table name for the coprocessor invoked 393 * @param pool ExecutorService used to submit the calls per row 394 * @param call instance on which to invoke 395 * {@link org.apache.hadoop.hbase.client.coprocessor.Batch.Call#call(Object)} 396 * for each row 397 * @param callback instance on which to invoke 398 * {@link org.apache.hadoop.hbase.client.coprocessor.Batch.Callback#update(byte[], byte[], Object)} 399 * for each result 400 * @param <T> the protocol interface type 401 * @param <R> the callable's return type 402 * @throws IOException 403 */ 404 public <T extends CoprocessorProtocol,R> void processExecs( 405 final Class<T> protocol, 406 List<byte[]> rows, 407 final byte[] tableName, 408 ExecutorService pool, 409 final Batch.Call<T,R> call, 410 final Batch.Callback<R> callback) throws IOException, Throwable; 411 412 /** 413 * Enable or disable region cache prefetch for the table. It will be 414 * applied for the given table's all HTable instances within this 415 * connection. By default, the cache prefetch is enabled. 416 * @param tableName name of table to configure. 417 * @param enable Set to true to enable region cache prefetch. 418 */ 419 public void setRegionCachePrefetch(final byte[] tableName, 420 final boolean enable); 421 422 /** 423 * Check whether region cache prefetch is enabled or not. 424 * @param tableName name of table to check 425 * @return true if table's region cache prefetch is enabled. Otherwise 426 * it is disabled. 427 */ 428 public boolean getRegionCachePrefetch(final byte[] tableName); 429 430 /** 431 * Load the region map and warm up the global region cache for the table. 432 * @param tableName name of the table to perform region cache prewarm. 433 * @param regions a region map. 434 */ 435 public void prewarmRegionCache(final byte[] tableName, 436 final Map<HRegionInfo, HServerAddress> regions); 437 438 /** 439 * Scan zookeeper to get the number of region servers 440 * @return the number of region servers that are currently running 441 * @throws IOException if a remote or network exception occurs 442 * @deprecated This method will be changed from public to package protected. 443 */ 444 public int getCurrentNrHRS() throws IOException; 445 446 /** 447 * @param tableNames List of table names 448 * @return HTD[] table metadata 449 * @throws IOException if a remote or network exception occurs 450 */ 451 public HTableDescriptor[] getHTableDescriptors(List<String> tableNames) 452 throws IOException; 453 454 /** 455 * @return true if this connection is closed 456 */ 457 public boolean isClosed(); 458 459 /** 460 * Clear any caches that pertain to server name <code>sn</code> 461 * @param sn A server name as hostname:port 462 */ 463 public void clearCaches(final String sn); 464 }