1 /** 2 * 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, software 14 * distributed under the License is distributed on an "AS IS" BASIS, 15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 * See the License for the specific language governing permissions and 17 * limitations under the License. 18 */ 19 package org.apache.hadoop.hbase.client; 20 21 import org.apache.hadoop.classification.InterfaceAudience; 22 import org.apache.hadoop.classification.InterfaceStability; 23 import org.apache.hadoop.conf.Configuration; 24 import org.apache.hadoop.hbase.Abortable; 25 import org.apache.hadoop.hbase.HRegionLocation; 26 import org.apache.hadoop.hbase.HTableDescriptor; 27 import org.apache.hadoop.hbase.MasterAdminProtocol; 28 import org.apache.hadoop.hbase.MasterMonitorProtocol; 29 import org.apache.hadoop.hbase.ServerName; 30 import org.apache.hadoop.hbase.catalog.CatalogTracker; 31 import org.apache.hadoop.hbase.client.coprocessor.Batch; 32 import org.apache.hadoop.hbase.exceptions.MasterNotRunningException; 33 import org.apache.hadoop.hbase.exceptions.ZooKeeperConnectionException; 34 import org.apache.hadoop.hbase.zookeeper.ZooKeeperWatcher; 35 36 import java.io.Closeable; 37 import java.io.IOException; 38 import java.util.List; 39 import java.util.concurrent.ExecutorService; 40 41 /** 42 * Cluster connection. Hosts a connection to the ZooKeeper ensemble and 43 * thereafter into the HBase cluster. Knows how to locate regions out on the cluster, 44 * keeps a cache of locations and then knows how to recalibrate after they move. 45 * {@link HConnectionManager} manages instances of this class. 46 * 47 * <p>HConnections are used by {@link HTable} mostly but also by 48 * {@link HBaseAdmin}, {@link CatalogTracker}, 49 * and {@link ZooKeeperWatcher}. HConnection instances can be shared. Sharing 50 * is usually what you want because rather than each HConnection instance 51 * having to do its own discovery of regions out on the cluster, instead, all 52 * clients get to share the one cache of locations. Sharing makes cleanup of 53 * HConnections awkward. See {@link HConnectionManager} for cleanup 54 * discussion. 55 * 56 * @see HConnectionManager 57 */ 58 @InterfaceAudience.Public 59 @InterfaceStability.Stable 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 /** @return - true if the master server is running */ 78 public boolean isMasterRunning() 79 throws MasterNotRunningException, ZooKeeperConnectionException; 80 81 /** 82 * A table that isTableEnabled == false and isTableDisabled == false 83 * is possible. This happens when a table has a lot of regions 84 * that must be processed. 85 * @param tableName table name 86 * @return true if the table is enabled, false otherwise 87 * @throws IOException if a remote or network exception occurs 88 */ 89 public boolean isTableEnabled(byte[] tableName) throws IOException; 90 91 /** 92 * @param tableName table name 93 * @return true if the table is disabled, false otherwise 94 * @throws IOException if a remote or network exception occurs 95 */ 96 public boolean isTableDisabled(byte[] tableName) throws IOException; 97 98 /** 99 * @param tableName table name 100 * @return true if all regions of the table are available, false otherwise 101 * @throws IOException if a remote or network exception occurs 102 */ 103 public boolean isTableAvailable(byte[] tableName) throws IOException; 104 105 /** 106 * Use this api to check if the table has been created with the specified number of 107 * splitkeys which was used while creating the given table. 108 * Note : If this api is used after a table's region gets splitted, the api may return 109 * false. 110 * @param tableName 111 * tableName 112 * @param splitKeys 113 * splitKeys used while creating table 114 * @throws IOException 115 * if a remote or network exception occurs 116 */ 117 public boolean isTableAvailable(byte[] tableName, byte[][] splitKeys) 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(final byte[] tableName) 195 throws IOException; 196 197 /** 198 * Gets the locations of all regions in the specified table, <i>tableName</i>. 199 * @param tableName table to get regions of 200 * @param useCache Should we use the cache to retrieve the region information. 201 * @param offlined True if we are to include offlined regions, false and we'll leave out offlined 202 * regions from returned list. 203 * @return list of region locations for all regions of table 204 * @throws IOException 205 */ 206 public List<HRegionLocation> locateRegions(final byte[] tableName, final boolean useCache, 207 final boolean offlined) throws IOException; 208 209 /** 210 * Returns a {@link MasterAdminProtocol} to the active master 211 */ 212 public MasterAdminProtocol getMasterAdmin() throws IOException; 213 214 /** 215 * Returns an {@link MasterMonitorProtocol} to the active master 216 */ 217 public MasterMonitorProtocol getMasterMonitor() throws IOException; 218 219 220 /** 221 * Establishes a connection to the region server at the specified address. 222 * @param hostname RegionServer hostname 223 * @param port RegionServer port 224 * @return proxy for HRegionServer 225 * @throws IOException if a remote or network exception occurs 226 * @deprecated - use @link {#getAdmin(final ServerName serverName)} which takes into account 227 * the startCode 228 */ 229 @Deprecated 230 public AdminProtocol getAdmin(final String hostname, final int port) 231 throws IOException; 232 233 234 /** 235 * Establishes a connection to the region server at the specified address. 236 * @param serverName 237 * @return proxy for HRegionServer 238 * @throws IOException if a remote or network exception occurs 239 */ 240 public AdminProtocol getAdmin(final ServerName serverName) 241 throws IOException; 242 243 /** 244 * Establishes a connection to the region server at the specified address, and return 245 * a region client protocol. 246 * 247 * @param hostname RegionServer hostname 248 * @param port RegionServer port 249 * @return ClientProtocol proxy for RegionServer 250 * @throws IOException if a remote or network exception occurs 251 * @deprecated - use @link {#getClient(final ServerName serverName)} which takes into account 252 * the startCode 253 */ 254 @Deprecated 255 public ClientProtocol getClient(final String hostname, final int port) 256 throws IOException; 257 258 259 /** 260 * Establishes a connection to the region server at the specified address, and return 261 * a region client protocol. 262 * 263 * @param serverName 264 * @return ClientProtocol proxy for RegionServer 265 * @throws IOException if a remote or network exception occurs 266 * 267 */ 268 public ClientProtocol getClient(final ServerName serverName) throws IOException; 269 270 /** 271 * Establishes a connection to the region server at the specified address. 272 * @param hostname RegionServer hostname 273 * @param port RegionServer port 274 * @param getMaster - do we check if master is alive 275 * @return proxy for HRegionServer 276 * @throws IOException if a remote or network exception occurs 277 * @deprecated use @link {#getAdmin(final ServerName serverName, boolean getMaster)} 278 * which takes into account the startCode. 279 */ 280 @Deprecated 281 public AdminProtocol getAdmin(final String hostname, final int port, boolean getMaster) 282 throws IOException; 283 284 /** 285 * Establishes a connection to the region server at the specified address. 286 * @param serverName 287 * @param getMaster - do we check if master is alive 288 * @return proxy for HRegionServer 289 * @throws IOException if a remote or network exception occurs 290 */ 291 public AdminProtocol getAdmin(final ServerName serverName, boolean getMaster) 292 throws IOException; 293 294 /** 295 * Find region location hosting passed row 296 * @param tableName table name 297 * @param row Row to find. 298 * @param reload If true do not use cache, otherwise bypass. 299 * @return Location of row. 300 * @throws IOException if a remote or network exception occurs 301 */ 302 HRegionLocation getRegionLocation(byte [] tableName, byte [] row, 303 boolean reload) 304 throws IOException; 305 306 /** 307 * Pass in a ServerCallable with your particular bit of logic defined and 308 * this method will manage the process of doing retries with timed waits 309 * and refinds of missing regions. 310 * 311 * @param <T> the type of the return value 312 * @param callable callable to run 313 * @return an object of type T 314 * @throws IOException if a remote or network exception occurs 315 * @throws RuntimeException other unspecified error 316 */ 317 @Deprecated 318 public <T> T getRegionServerWithRetries(ServerCallable<T> callable) 319 throws IOException, RuntimeException; 320 321 /** 322 * Pass in a ServerCallable with your particular bit of logic defined and 323 * this method will pass it to the defined region server. 324 * @param <T> the type of the return value 325 * @param callable callable to run 326 * @return an object of type T 327 * @throws IOException if a remote or network exception occurs 328 * @throws RuntimeException other unspecified error 329 */ 330 @Deprecated 331 public <T> T getRegionServerWithoutRetries(ServerCallable<T> callable) 332 throws IOException, RuntimeException; 333 334 /** 335 * Process a mixed batch of Get, Put and Delete actions. All actions for a 336 * RegionServer are forwarded in one RPC call. 337 * 338 * 339 * @param actions The collection of actions. 340 * @param tableName Name of the hbase table 341 * @param pool thread pool for parallel execution 342 * @param results An empty array, same size as list. If an exception is thrown, 343 * you can test here for partial results, and to determine which actions 344 * processed successfully. 345 * @throws IOException if there are problems talking to META. Per-item 346 * exceptions are stored in the results array. 347 * @deprecated since 0.96 - Use {@link HTableInterface#batch} instead 348 */ 349 @Deprecated 350 public void processBatch(List<? extends Row> actions, final byte[] tableName, 351 ExecutorService pool, Object[] results) 352 throws IOException, InterruptedException; 353 354 /** 355 * Parameterized batch processing, allowing varying return types for different 356 * {@link Row} implementations. 357 * @deprecated since 0.96 - Use {@link HTableInterface#batchCallback} instead 358 */ 359 @Deprecated 360 public <R> void processBatchCallback(List<? extends Row> list, 361 byte[] tableName, 362 ExecutorService pool, 363 Object[] results, 364 Batch.Callback<R> callback) throws IOException, InterruptedException; 365 366 /** 367 * Enable or disable region cache prefetch for the table. It will be 368 * applied for the given table's all HTable instances within this 369 * connection. By default, the cache prefetch is enabled. 370 * @param tableName name of table to configure. 371 * @param enable Set to true to enable region cache prefetch. 372 */ 373 public void setRegionCachePrefetch(final byte[] tableName, 374 final boolean enable); 375 376 /** 377 * Check whether region cache prefetch is enabled or not. 378 * @param tableName name of table to check 379 * @return true if table's region cache prefetch is enabled. Otherwise 380 * it is disabled. 381 */ 382 public boolean getRegionCachePrefetch(final byte[] tableName); 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 @Deprecated 391 public int getCurrentNrHRS() throws IOException; 392 393 /** 394 * @param tableNames List of table names 395 * @return HTD[] table metadata 396 * @throws IOException if a remote or network exception occurs 397 */ 398 public HTableDescriptor[] getHTableDescriptors(List<String> tableNames) 399 throws IOException; 400 401 /** 402 * @return true if this connection is closed 403 */ 404 public boolean isClosed(); 405 406 407 /** 408 * Clear any caches that pertain to server name <code>sn</code> 409 * @param sn A server name 410 */ 411 public void clearCaches(final ServerName sn); 412 413 /** 414 * This function allows HBaseAdminProtocol and potentially others to get a shared MasterMonitor 415 * connection. 416 * @return The shared instance. Never returns null. 417 * @throws MasterNotRunningException 418 */ 419 public MasterMonitorKeepAliveConnection getKeepAliveMasterMonitor() 420 throws MasterNotRunningException; 421 422 /** 423 * This function allows HBaseAdmin and potentially others to get a shared MasterAdminProtocol 424 * connection. 425 * @return The shared instance. Never returns null. 426 * @throws MasterNotRunningException 427 */ 428 public MasterAdminKeepAliveConnection getKeepAliveMasterAdmin() throws MasterNotRunningException; 429 430 /** 431 * @param serverName 432 * @return true if the server is known as dead, false otherwise. 433 */ 434 public boolean isDeadServer(ServerName serverName); 435 } 436