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 ZooKeeperWatcher used by this connection. 68 * @return ZooKeeperWatcher handle being used by the connection. 69 * @throws IOException if a remote or network exception occurs 70 * @deprecated Removed because it was a mistake exposing zookeeper in this 71 * interface (ZooKeeper is an implementation detail). 72 * Deprecated in HBase 0.94 73 */ 74 @Deprecated 75 public ZooKeeperWatcher getZooKeeperWatcher() throws IOException; 76 77 /** 78 * @return proxy connection to master server for this instance 79 * @throws MasterNotRunningException if the master is not running 80 * @throws ZooKeeperConnectionException if unable to connect to zookeeper 81 * @deprecated Removed because it was a mistake exposing master in this 82 * interface (master is an implementation detail). Master functions are 83 * available from HConnection or HBaseAdmin, without having to use 84 * directly the master. 85 * Deprecated in HBase 0.94 86 */ 87 @Deprecated 88 public HMasterInterface getMaster() 89 throws MasterNotRunningException, ZooKeeperConnectionException; 90 91 /** @return - true if the master server is running */ 92 public boolean isMasterRunning() 93 throws MasterNotRunningException, ZooKeeperConnectionException; 94 95 /** 96 * A table that isTableEnabled == false and isTableDisabled == false 97 * is possible. This happens when a table has a lot of regions 98 * that must be processed. 99 * @param tableName table name 100 * @return true if the table is enabled, false otherwise 101 * @throws IOException if a remote or network exception occurs 102 */ 103 public boolean isTableEnabled(byte[] tableName) throws IOException; 104 105 /** 106 * @param tableName table name 107 * @return true if the table is disabled, false otherwise 108 * @throws IOException if a remote or network exception occurs 109 */ 110 public boolean isTableDisabled(byte[] tableName) throws IOException; 111 112 /** 113 * @param tableName table name 114 * @return true if all regions of the table are available, false otherwise 115 * @throws IOException if a remote or network exception occurs 116 */ 117 public boolean isTableAvailable(byte[] tableName) throws IOException; 118 119 /** 120 * List all the userspace tables. In other words, scan the META table. 121 * 122 * If we wanted this to be really fast, we could implement a special 123 * catalog table that just contains table names and their descriptors. 124 * Right now, it only exists as part of the META table's region info. 125 * 126 * @return - returns an array of HTableDescriptors 127 * @throws IOException if a remote or network exception occurs 128 */ 129 public HTableDescriptor[] listTables() throws IOException; 130 131 /** 132 * @param tableName table name 133 * @return table metadata 134 * @throws IOException if a remote or network exception occurs 135 */ 136 public HTableDescriptor getHTableDescriptor(byte[] tableName) 137 throws IOException; 138 139 /** 140 * Find the location of the region of <i>tableName</i> that <i>row</i> 141 * lives in. 142 * @param tableName name of the table <i>row</i> is in 143 * @param row row key you're trying to find the region of 144 * @return HRegionLocation that describes where to find the region in 145 * question 146 * @throws IOException if a remote or network exception occurs 147 */ 148 public HRegionLocation locateRegion(final byte [] tableName, 149 final byte [] row) 150 throws IOException; 151 152 /** 153 * Allows flushing the region cache. 154 */ 155 public void clearRegionCache(); 156 157 /** 158 * Allows flushing the region cache of all locations that pertain to 159 * <code>tableName</code> 160 * @param tableName Name of the table whose regions we are to remove from 161 * cache. 162 */ 163 public void clearRegionCache(final byte [] tableName); 164 165 /** 166 * Deletes cached locations for the specific region. 167 * @param location The location object for the region, to be purged from cache. 168 */ 169 public void deleteCachedRegionLocation(final HRegionLocation location); 170 171 /** 172 * Find the location of the region of <i>tableName</i> that <i>row</i> 173 * lives in, ignoring any value that might be in the cache. 174 * @param tableName name of the table <i>row</i> is in 175 * @param row row key you're trying to find the region of 176 * @return HRegionLocation that describes where to find the region in 177 * question 178 * @throws IOException if a remote or network exception occurs 179 */ 180 public HRegionLocation relocateRegion(final byte [] tableName, 181 final byte [] row) 182 throws IOException; 183 184 /** 185 * Gets the location of the region of <i>regionName</i>. 186 * @param regionName name of the region to locate 187 * @return HRegionLocation that describes where to find the region in 188 * question 189 * @throws IOException if a remote or network exception occurs 190 */ 191 public HRegionLocation locateRegion(final byte [] regionName) 192 throws IOException; 193 194 /** 195 * Gets the locations of all regions in the specified table, <i>tableName</i>. 196 * @param tableName table to get regions of 197 * @return list of region locations for all regions of table 198 * @throws IOException 199 */ 200 public List<HRegionLocation> locateRegions(final byte[] tableName) 201 throws IOException; 202 203 /** 204 * Gets the locations of all regions in the specified table, <i>tableName</i>. 205 * @param tableName table to get regions of 206 * @param useCache Should we use the cache to retrieve the region information. 207 * @param offlined True if we are to include offlined regions, false and we'll leave out offlined 208 * regions from returned list. 209 * @return list of region locations for all regions of table 210 * @throws IOException 211 */ 212 public List<HRegionLocation> locateRegions(final byte[] tableName, final boolean useCache, 213 final boolean offlined) throws IOException; 214 215 /** 216 * Establishes a connection to the region server at the specified address. 217 * @param regionServer - the server to connect to 218 * @return proxy for HRegionServer 219 * @throws IOException if a remote or network exception occurs 220 * @deprecated Use {@link #getHRegionConnection(String, int)} 221 */ 222 public HRegionInterface getHRegionConnection(HServerAddress regionServer) 223 throws IOException; 224 225 /** 226 * Establishes a connection to the region server at the specified address. 227 * @param hostname RegionServer hostname 228 * @param port RegionServer port 229 * @return proxy for HRegionServer 230 * @throws IOException if a remote or network exception occurs 231 * 232 */ 233 public HRegionInterface getHRegionConnection(final String hostname, final int port) 234 throws IOException; 235 236 /** 237 * Establishes a connection to the region server at the specified address. 238 * @param regionServer - the server to connect to 239 * @param getMaster - do we check if master is alive 240 * @return proxy for HRegionServer 241 * @throws IOException if a remote or network exception occurs 242 * @deprecated Use {@link #getHRegionConnection(HServerAddress, boolean)} 243 */ 244 public HRegionInterface getHRegionConnection(HServerAddress regionServer, 245 boolean getMaster) 246 throws IOException; 247 248 /** 249 * Establishes a connection to the region server at the specified address. 250 * @param hostname RegionServer hostname 251 * @param port RegionServer port 252 * @param getMaster - do we check if master is alive 253 * @return proxy for HRegionServer 254 * @throws IOException if a remote or network exception occurs 255 */ 256 public HRegionInterface getHRegionConnection(final String hostname, 257 final int port, boolean getMaster) 258 throws IOException; 259 260 /** 261 * Find region location hosting passed row 262 * @param tableName table name 263 * @param row Row to find. 264 * @param reload If true do not use cache, otherwise bypass. 265 * @return Location of row. 266 * @throws IOException if a remote or network exception occurs 267 */ 268 HRegionLocation getRegionLocation(byte [] tableName, byte [] row, 269 boolean reload) 270 throws IOException; 271 272 /** 273 * Pass in a ServerCallable with your particular bit of logic defined and 274 * this method will manage the process of doing retries with timed waits 275 * and refinds of missing regions. 276 * 277 * @param <T> the type of the return value 278 * @param callable callable to run 279 * @return an object of type T 280 * @throws IOException if a remote or network exception occurs 281 * @throws RuntimeException other unspecified error 282 * @deprecated Use {@link HConnectionManager#withoutRetries(ServerCallable)} 283 */ 284 public <T> T getRegionServerWithRetries(ServerCallable<T> callable) 285 throws IOException, RuntimeException; 286 287 /** 288 * Pass in a ServerCallable with your particular bit of logic defined and 289 * this method will pass it to the defined region server. 290 * @param <T> the type of the return value 291 * @param callable callable to run 292 * @return an object of type T 293 * @throws IOException if a remote or network exception occurs 294 * @throws RuntimeException other unspecified error 295 * @deprecated Use {@link HConnectionManager#withoutRetries(ServerCallable)} 296 */ 297 public <T> T getRegionServerWithoutRetries(ServerCallable<T> callable) 298 throws IOException, RuntimeException; 299 300 /** 301 * Process a mixed batch of Get, Put and Delete actions. All actions for a 302 * RegionServer are forwarded in one RPC call. 303 * 304 * 305 * @param actions The collection of actions. 306 * @param tableName Name of the hbase table 307 * @param pool thread pool for parallel execution 308 * @param results An empty array, same size as list. If an exception is thrown, 309 * you can test here for partial results, and to determine which actions 310 * processed successfully. 311 * @throws IOException if there are problems talking to META. Per-item 312 * exceptions are stored in the results array. 313 */ 314 public void processBatch(List<? extends Row> actions, final byte[] tableName, 315 ExecutorService pool, Object[] results) 316 throws IOException, InterruptedException; 317 318 /** 319 * Parameterized batch processing, allowing varying return types for different 320 * {@link Row} implementations. 321 */ 322 public <R> void processBatchCallback(List<? extends Row> list, 323 byte[] tableName, 324 ExecutorService pool, 325 Object[] results, 326 Batch.Callback<R> callback) throws IOException, InterruptedException; 327 328 329 /** 330 * Executes the given 331 * {@link org.apache.hadoop.hbase.client.coprocessor.Batch.Call} 332 * callable for each row in the given list and invokes 333 * {@link org.apache.hadoop.hbase.client.coprocessor.Batch.Callback#update(byte[], byte[], Object)} 334 * for each result returned. 335 * 336 * @param protocol the protocol interface being called 337 * @param rows a list of row keys for which the callable should be invoked 338 * @param tableName table name for the coprocessor invoked 339 * @param pool ExecutorService used to submit the calls per row 340 * @param call instance on which to invoke 341 * {@link org.apache.hadoop.hbase.client.coprocessor.Batch.Call#call(Object)} 342 * for each row 343 * @param callback instance on which to invoke 344 * {@link org.apache.hadoop.hbase.client.coprocessor.Batch.Callback#update(byte[], byte[], Object)} 345 * for each result 346 * @param <T> the protocol interface type 347 * @param <R> the callable's return type 348 * @throws IOException 349 */ 350 public <T extends CoprocessorProtocol,R> void processExecs( 351 final Class<T> protocol, 352 List<byte[]> rows, 353 final byte[] tableName, 354 ExecutorService pool, 355 final Batch.Call<T,R> call, 356 final Batch.Callback<R> callback) throws IOException, Throwable; 357 358 /** 359 * Enable or disable region cache prefetch for the table. It will be 360 * applied for the given table's all HTable instances within this 361 * connection. By default, the cache prefetch is enabled. 362 * @param tableName name of table to configure. 363 * @param enable Set to true to enable region cache prefetch. 364 */ 365 public void setRegionCachePrefetch(final byte[] tableName, 366 final boolean enable); 367 368 /** 369 * Check whether region cache prefetch is enabled or not. 370 * @param tableName name of table to check 371 * @return true if table's region cache prefetch is enabled. Otherwise 372 * it is disabled. 373 */ 374 public boolean getRegionCachePrefetch(final byte[] tableName); 375 376 /** 377 * Load the region map and warm up the global region cache for the table. 378 * @param tableName name of the table to perform region cache prewarm. 379 * @param regions a region map. 380 */ 381 public void prewarmRegionCache(final byte[] tableName, 382 final Map<HRegionInfo, HServerAddress> regions); 383 384 /** 385 * Scan zookeeper to get the number of region servers 386 * @return the number of region servers that are currently running 387 * @throws IOException if a remote or network exception occurs 388 * @deprecated This method will be changed from public to package protected. 389 */ 390 public int getCurrentNrHRS() throws IOException; 391 392 /** 393 * @param tableNames List of table names 394 * @return HTD[] table metadata 395 * @throws IOException if a remote or network exception occurs 396 */ 397 public HTableDescriptor[] getHTableDescriptors(List<String> tableNames) 398 throws IOException; 399 400 /** 401 * @return true if this connection is closed 402 */ 403 public boolean isClosed(); 404 405 /** 406 * Clear any caches that pertain to server name <code>sn</code> 407 * @param sn A server name as hostname:port 408 */ 409 public void clearCaches(final String sn); 410 }