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.IOException; 23 import java.util.List; 24 import java.util.Map; 25 import java.util.concurrent.ExecutorService; 26 27 import org.apache.hadoop.conf.Configuration; 28 import org.apache.hadoop.hbase.Abortable; 29 import org.apache.hadoop.hbase.HRegionInfo; 30 import org.apache.hadoop.hbase.HRegionLocation; 31 import org.apache.hadoop.hbase.HServerAddress; 32 import org.apache.hadoop.hbase.HTableDescriptor; 33 import org.apache.hadoop.hbase.MasterNotRunningException; 34 import org.apache.hadoop.hbase.ZooKeeperConnectionException; 35 import org.apache.hadoop.hbase.catalog.CatalogTracker; 36 import org.apache.hadoop.hbase.ipc.HMasterInterface; 37 import org.apache.hadoop.hbase.ipc.HRegionInterface; 38 import org.apache.hadoop.hbase.zookeeper.ZooKeeperWatcher; 39 40 /** 41 * Cluster connection. Hosts a connection to the ZooKeeper ensemble and 42 * thereafter into the HBase cluster. Knows how to locate regions out on the cluster, 43 * keeps a cache of locations and then knows how to recalibrate after they move. 44 * {@link HConnectionManager} manages instances of this class. 45 * 46 * <p>HConnections are used by {@link HTable} mostly but also by 47 * {@link HBaseAdmin}, {@link CatalogTracker}, 48 * and {@link ZooKeeperWatcher}. HConnection instances can be shared. Sharing 49 * is usually what you want because rather than each HConnection instance 50 * having to do its own discovery of regions out on the cluster, instead, all 51 * clients get to share the one cache of locations. Sharing makes cleanup of 52 * HConnections awkward. See {@link HConnectionManager} for cleanup 53 * discussion. 54 * 55 * @see HConnectionManager 56 */ 57 public interface HConnection extends Abortable { 58 /** 59 * @return Configuration instance being used by this HConnection instance. 60 */ 61 public Configuration getConfiguration(); 62 63 /** 64 * Retrieve ZooKeeperWatcher used by this connection. 65 * @return ZooKeeperWatcher handle being used by the connection. 66 * @throws IOException if a remote or network exception occurs 67 */ 68 public ZooKeeperWatcher getZooKeeperWatcher() throws IOException; 69 70 /** 71 * @return proxy connection to master server for this instance 72 * @throws MasterNotRunningException if the master is not running 73 * @throws ZooKeeperConnectionException if unable to connect to zookeeper 74 */ 75 public HMasterInterface getMaster() 76 throws MasterNotRunningException, ZooKeeperConnectionException; 77 78 /** @return - true if the master server is running */ 79 public boolean isMasterRunning() 80 throws MasterNotRunningException, ZooKeeperConnectionException; 81 82 /** 83 * A table that isTableEnabled == false and isTableDisabled == false 84 * is possible. This happens when a table has a lot of regions 85 * that must be processed. 86 * @param tableName table name 87 * @return true if the table is enabled, false otherwise 88 * @throws IOException if a remote or network exception occurs 89 */ 90 public boolean isTableEnabled(byte[] tableName) throws IOException; 91 92 /** 93 * @param tableName table name 94 * @return true if the table is disabled, false otherwise 95 * @throws IOException if a remote or network exception occurs 96 */ 97 public boolean isTableDisabled(byte[] tableName) throws IOException; 98 99 /** 100 * @param tableName table name 101 * @return true if all regions of the table are available, false otherwise 102 * @throws IOException if a remote or network exception occurs 103 */ 104 public boolean isTableAvailable(byte[] tableName) throws IOException; 105 106 /** 107 * List all the userspace tables. In other words, scan the META table. 108 * 109 * If we wanted this to be really fast, we could implement a special 110 * catalog table that just contains table names and their descriptors. 111 * Right now, it only exists as part of the META table's region info. 112 * 113 * @return - returns an array of HTableDescriptors 114 * @throws IOException if a remote or network exception occurs 115 */ 116 public HTableDescriptor[] listTables() throws IOException; 117 118 /** 119 * @param tableName table name 120 * @return table metadata 121 * @throws IOException if a remote or network exception occurs 122 */ 123 public HTableDescriptor getHTableDescriptor(byte[] tableName) 124 throws IOException; 125 126 /** 127 * Find the location of the region of <i>tableName</i> that <i>row</i> 128 * lives in. 129 * @param tableName name of the table <i>row</i> is in 130 * @param row row key you're trying to find the region of 131 * @return HRegionLocation that describes where to find the region in 132 * question 133 * @throws IOException if a remote or network exception occurs 134 */ 135 public HRegionLocation locateRegion(final byte [] tableName, 136 final byte [] row) 137 throws IOException; 138 139 /** 140 * Allows flushing the region cache. 141 */ 142 public void clearRegionCache(); 143 144 /** 145 * Allows flushing the region cache of all locations that pertain to 146 * <code>tableName</code> 147 * @param tableName Name of the table whose regions we are to remove from 148 * cache. 149 */ 150 public void clearRegionCache(final byte [] tableName); 151 152 /** 153 * Find the location of the region of <i>tableName</i> that <i>row</i> 154 * lives in, ignoring any value that might be in the cache. 155 * @param tableName name of the table <i>row</i> is in 156 * @param row row key you're trying to find the region of 157 * @return HRegionLocation that describes where to find the region in 158 * question 159 * @throws IOException if a remote or network exception occurs 160 */ 161 public HRegionLocation relocateRegion(final byte [] tableName, 162 final byte [] row) 163 throws IOException; 164 165 /** 166 * Gets the location of the region of <i>regionName</i>. 167 * @param regionName name of the region to locate 168 * @return HRegionLocation that describes where to find the region in 169 * question 170 * @throws IOException if a remote or network exception occurs 171 */ 172 public HRegionLocation locateRegion(final byte [] regionName) 173 throws IOException; 174 175 /** 176 * Gets the locations of all regions in the specified table, <i>tableName</i>. 177 * @param tableName table to get regions of 178 * @return list of region locations for all regions of table 179 * @throws IOException 180 */ 181 public List<HRegionLocation> locateRegions(byte[] tableName) 182 throws IOException; 183 184 /** 185 * Establishes a connection to the region server at the specified address. 186 * @param regionServer - the server to connect to 187 * @return proxy for HRegionServer 188 * @throws IOException if a remote or network exception occurs 189 */ 190 public HRegionInterface getHRegionConnection(HServerAddress regionServer) 191 throws IOException; 192 193 /** 194 * Establishes a connection to the region server at the specified address. 195 * @param regionServer - the server to connect to 196 * @param getMaster - do we check if master is alive 197 * @return proxy for HRegionServer 198 * @throws IOException if a remote or network exception occurs 199 */ 200 public HRegionInterface getHRegionConnection( 201 HServerAddress regionServer, boolean getMaster) 202 throws IOException; 203 204 /** 205 * Find region location hosting passed row 206 * @param tableName table name 207 * @param row Row to find. 208 * @param reload If true do not use cache, otherwise bypass. 209 * @return Location of row. 210 * @throws IOException if a remote or network exception occurs 211 */ 212 HRegionLocation getRegionLocation(byte [] tableName, byte [] row, 213 boolean reload) 214 throws IOException; 215 216 /** 217 * Pass in a ServerCallable with your particular bit of logic defined and 218 * this method will manage the process of doing retries with timed waits 219 * and refinds of missing regions. 220 * 221 * @param <T> the type of the return value 222 * @param callable callable to run 223 * @return an object of type T 224 * @throws IOException if a remote or network exception occurs 225 * @throws RuntimeException other unspecified error 226 */ 227 public <T> T getRegionServerWithRetries(ServerCallable<T> callable) 228 throws IOException, RuntimeException; 229 230 /** 231 * Pass in a ServerCallable with your particular bit of logic defined and 232 * this method will pass it to the defined region server. 233 * @param <T> the type of the return value 234 * @param callable callable to run 235 * @return an object of type T 236 * @throws IOException if a remote or network exception occurs 237 * @throws RuntimeException other unspecified error 238 */ 239 public <T> T getRegionServerWithoutRetries(ServerCallable<T> callable) 240 throws IOException, RuntimeException; 241 242 /** 243 * Process a mixed batch of Get, Put and Delete actions. All actions for a 244 * RegionServer are forwarded in one RPC call. 245 * 246 * 247 * @param actions The collection of actions. 248 * @param tableName Name of the hbase table 249 * @param pool thread pool for parallel execution 250 * @param results An empty array, same size as list. If an exception is thrown, 251 * you can test here for partial results, and to determine which actions 252 * processed successfully. 253 * @throws IOException if there are problems talking to META. Per-item 254 * exceptions are stored in the results array. 255 */ 256 public void processBatch(List<Row> actions, final byte[] tableName, 257 ExecutorService pool, Object[] results) 258 throws IOException, InterruptedException; 259 260 /** 261 * Process a batch of Puts. 262 * 263 * @param list The collection of actions. The list is mutated: all successful Puts 264 * are removed from the list. 265 * @param tableName Name of the hbase table 266 * @param pool Thread pool for parallel execution 267 * @throws IOException 268 * @deprecated Use HConnectionManager::processBatch instead. 269 */ 270 public void processBatchOfPuts(List<Put> list, 271 final byte[] tableName, ExecutorService pool) 272 throws IOException; 273 274 /** 275 * Enable or disable region cache prefetch for the table. It will be 276 * applied for the given table's all HTable instances within this 277 * connection. By default, the cache prefetch is enabled. 278 * @param tableName name of table to configure. 279 * @param enable Set to true to enable region cache prefetch. 280 */ 281 public void setRegionCachePrefetch(final byte[] tableName, 282 final boolean enable); 283 284 /** 285 * Check whether region cache prefetch is enabled or not. 286 * @param tableName name of table to check 287 * @return true if table's region cache prefetch is enabled. Otherwise 288 * it is disabled. 289 */ 290 public boolean getRegionCachePrefetch(final byte[] tableName); 291 292 /** 293 * Load the region map and warm up the global region cache for the table. 294 * @param tableName name of the table to perform region cache prewarm. 295 * @param regions a region map. 296 */ 297 public void prewarmRegionCache(final byte[] tableName, 298 final Map<HRegionInfo, HServerAddress> regions); 299 }