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 * Find the location of the region of <i>tableName</i> that <i>row</i> 167 * lives in, ignoring any value that might be in the cache. 168 * @param tableName name of the table <i>row</i> is in 169 * @param row row key you're trying to find the region of 170 * @return HRegionLocation that describes where to find the region in 171 * question 172 * @throws IOException if a remote or network exception occurs 173 */ 174 public HRegionLocation relocateRegion(final byte [] tableName, 175 final byte [] row) 176 throws IOException; 177 178 /** 179 * Gets the location of the region of <i>regionName</i>. 180 * @param regionName name of the region to locate 181 * @return HRegionLocation that describes where to find the region in 182 * question 183 * @throws IOException if a remote or network exception occurs 184 */ 185 public HRegionLocation locateRegion(final byte [] regionName) 186 throws IOException; 187 188 /** 189 * Gets the locations of all regions in the specified table, <i>tableName</i>. 190 * @param tableName table to get regions of 191 * @return list of region locations for all regions of table 192 * @throws IOException 193 */ 194 public List<HRegionLocation> locateRegions(byte[] tableName) 195 throws IOException; 196 197 /** 198 * Establishes a connection to the region server at the specified address. 199 * @param regionServer - the server to connect to 200 * @return proxy for HRegionServer 201 * @throws IOException if a remote or network exception occurs 202 * @deprecated Use {@link #getHRegionConnection(String, int)} 203 */ 204 public HRegionInterface getHRegionConnection(HServerAddress regionServer) 205 throws IOException; 206 207 /** 208 * Establishes a connection to the region server at the specified address. 209 * @param hostname RegionServer hostname 210 * @param port RegionServer port 211 * @return proxy for HRegionServer 212 * @throws IOException if a remote or network exception occurs 213 * 214 */ 215 public HRegionInterface getHRegionConnection(final String hostname, final int port) 216 throws IOException; 217 218 /** 219 * Establishes a connection to the region server at the specified address. 220 * @param regionServer - the server to connect to 221 * @param getMaster - do we check if master is alive 222 * @return proxy for HRegionServer 223 * @throws IOException if a remote or network exception occurs 224 * @deprecated Use {@link #getHRegionConnection(HServerAddress, boolean)} 225 */ 226 public HRegionInterface getHRegionConnection(HServerAddress regionServer, 227 boolean getMaster) 228 throws IOException; 229 230 /** 231 * Establishes a connection to the region server at the specified address. 232 * @param hostname RegionServer hostname 233 * @param port RegionServer port 234 * @param getMaster - do we check if master is alive 235 * @return proxy for HRegionServer 236 * @throws IOException if a remote or network exception occurs 237 */ 238 public HRegionInterface getHRegionConnection(final String hostname, 239 final int port, boolean getMaster) 240 throws IOException; 241 242 /** 243 * Find region location hosting passed row 244 * @param tableName table name 245 * @param row Row to find. 246 * @param reload If true do not use cache, otherwise bypass. 247 * @return Location of row. 248 * @throws IOException if a remote or network exception occurs 249 */ 250 HRegionLocation getRegionLocation(byte [] tableName, byte [] row, 251 boolean reload) 252 throws IOException; 253 254 /** 255 * Pass in a ServerCallable with your particular bit of logic defined and 256 * this method will manage the process of doing retries with timed waits 257 * and refinds of missing regions. 258 * 259 * @param <T> the type of the return value 260 * @param callable callable to run 261 * @return an object of type T 262 * @throws IOException if a remote or network exception occurs 263 * @throws RuntimeException other unspecified error 264 * @deprecated Use {@link HConnectionManager#withoutRetries(ServerCallable)} 265 */ 266 public <T> T getRegionServerWithRetries(ServerCallable<T> callable) 267 throws IOException, RuntimeException; 268 269 /** 270 * Pass in a ServerCallable with your particular bit of logic defined and 271 * this method will pass it to the defined region server. 272 * @param <T> the type of the return value 273 * @param callable callable to run 274 * @return an object of type T 275 * @throws IOException if a remote or network exception occurs 276 * @throws RuntimeException other unspecified error 277 * @deprecated Use {@link HConnectionManager#withoutRetries(ServerCallable)} 278 */ 279 public <T> T getRegionServerWithoutRetries(ServerCallable<T> callable) 280 throws IOException, RuntimeException; 281 282 /** 283 * Process a mixed batch of Get, Put and Delete actions. All actions for a 284 * RegionServer are forwarded in one RPC call. 285 * 286 * 287 * @param actions The collection of actions. 288 * @param tableName Name of the hbase table 289 * @param pool thread pool for parallel execution 290 * @param results An empty array, same size as list. If an exception is thrown, 291 * you can test here for partial results, and to determine which actions 292 * processed successfully. 293 * @throws IOException if there are problems talking to META. Per-item 294 * exceptions are stored in the results array. 295 */ 296 public void processBatch(List<? extends Row> actions, final byte[] tableName, 297 ExecutorService pool, Object[] results) 298 throws IOException, InterruptedException; 299 300 /** 301 * Parameterized batch processing, allowing varying return types for different 302 * {@link Row} implementations. 303 */ 304 public <R> void processBatchCallback(List<? extends Row> list, 305 byte[] tableName, 306 ExecutorService pool, 307 Object[] results, 308 Batch.Callback<R> callback) throws IOException, InterruptedException; 309 310 311 /** 312 * Executes the given 313 * {@link org.apache.hadoop.hbase.client.coprocessor.Batch.Call} 314 * callable for each row in the given list and invokes 315 * {@link org.apache.hadoop.hbase.client.coprocessor.Batch.Callback#update(byte[], byte[], Object)} 316 * for each result returned. 317 * 318 * @param protocol the protocol interface being called 319 * @param rows a list of row keys for which the callable should be invoked 320 * @param tableName table name for the coprocessor invoked 321 * @param pool ExecutorService used to submit the calls per row 322 * @param call instance on which to invoke 323 * {@link org.apache.hadoop.hbase.client.coprocessor.Batch.Call#call(Object)} 324 * for each row 325 * @param callback instance on which to invoke 326 * {@link org.apache.hadoop.hbase.client.coprocessor.Batch.Callback#update(byte[], byte[], Object)} 327 * for each result 328 * @param <T> the protocol interface type 329 * @param <R> the callable's return type 330 * @throws IOException 331 */ 332 public <T extends CoprocessorProtocol,R> void processExecs( 333 final Class<T> protocol, 334 List<byte[]> rows, 335 final byte[] tableName, 336 ExecutorService pool, 337 final Batch.Call<T,R> call, 338 final Batch.Callback<R> callback) throws IOException, Throwable; 339 340 /** 341 * Enable or disable region cache prefetch for the table. It will be 342 * applied for the given table's all HTable instances within this 343 * connection. By default, the cache prefetch is enabled. 344 * @param tableName name of table to configure. 345 * @param enable Set to true to enable region cache prefetch. 346 */ 347 public void setRegionCachePrefetch(final byte[] tableName, 348 final boolean enable); 349 350 /** 351 * Check whether region cache prefetch is enabled or not. 352 * @param tableName name of table to check 353 * @return true if table's region cache prefetch is enabled. Otherwise 354 * it is disabled. 355 */ 356 public boolean getRegionCachePrefetch(final byte[] tableName); 357 358 /** 359 * Load the region map and warm up the global region cache for the table. 360 * @param tableName name of the table to perform region cache prewarm. 361 * @param regions a region map. 362 */ 363 public void prewarmRegionCache(final byte[] tableName, 364 final Map<HRegionInfo, HServerAddress> regions); 365 366 /** 367 * Scan zookeeper to get the number of region servers 368 * @return the number of region servers that are currently running 369 * @throws IOException if a remote or network exception occurs 370 * @deprecated This method will be changed from public to package protected. 371 */ 372 public int getCurrentNrHRS() throws IOException; 373 374 /** 375 * @param tableNames List of table names 376 * @return HTD[] table metadata 377 * @throws IOException if a remote or network exception occurs 378 */ 379 public HTableDescriptor[] getHTableDescriptors(List<String> tableNames) 380 throws IOException; 381 382 /** 383 * @return true if this connection is closed 384 */ 385 public boolean isClosed(); 386 387 /** 388 * Clear any caches that pertain to server name <code>sn</code> 389 * @param sn A server name as hostname:port 390 */ 391 public void clearCaches(final String sn); 392 }