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 java.io.IOException; 22 import java.util.List; 23 24 import org.apache.hadoop.hbase.classification.InterfaceAudience; 25 import org.apache.hadoop.conf.Configuration; 26 import org.apache.hadoop.hbase.HRegionLocation; 27 import org.apache.hadoop.hbase.MasterNotRunningException; 28 import org.apache.hadoop.hbase.RegionLocations; 29 import org.apache.hadoop.hbase.ServerName; 30 import org.apache.hadoop.hbase.TableName; 31 import org.apache.hadoop.hbase.ZooKeeperConnectionException; 32 import org.apache.hadoop.hbase.classification.InterfaceAudience; 33 import org.apache.hadoop.hbase.client.backoff.ClientBackoffPolicy; 34 import org.apache.hadoop.hbase.ipc.RpcControllerFactory; 35 import org.apache.hadoop.hbase.protobuf.generated.AdminProtos.AdminService; 36 import org.apache.hadoop.hbase.protobuf.generated.ClientProtos.ClientService; 37 import org.apache.hadoop.hbase.protobuf.generated.MasterProtos.MasterService; 38 39 /** Internal methods on Connection that should not be used by user code. */ 40 @InterfaceAudience.Private 41 // NOTE: Although this class is public, this class is meant to be used directly from internal 42 // classes and unit tests only. 43 public interface ClusterConnection extends HConnection { 44 45 /** @return - true if the master server is running 46 * @deprecated this has been deprecated without a replacement */ 47 @Override 48 @Deprecated 49 boolean isMasterRunning() 50 throws MasterNotRunningException, ZooKeeperConnectionException; 51 52 /** 53 * Use this api to check if the table has been created with the specified number of 54 * splitkeys which was used while creating the given table. 55 * Note : If this api is used after a table's region gets splitted, the api may return 56 * false. 57 * @param tableName 58 * tableName 59 * @param splitKeys 60 * splitKeys used while creating table 61 * @throws IOException 62 * if a remote or network exception occurs 63 */ 64 @Override 65 boolean isTableAvailable(TableName tableName, byte[][] splitKeys) throws 66 IOException; 67 68 /** 69 * Find the location of the region of <i>tableName</i> that <i>row</i> 70 * lives in. 71 * @param tableName name of the table <i>row</i> is in 72 * @param row row key you're trying to find the region of 73 * @return HRegionLocation that describes where to find the region in 74 * question 75 * @throws IOException if a remote or network exception occurs 76 */ 77 @Override 78 public HRegionLocation locateRegion(final TableName tableName, 79 final byte [] row) throws IOException; 80 81 /** 82 * Allows flushing the region cache. 83 */ 84 @Override 85 void clearRegionCache(); 86 87 88 void cacheLocation(final TableName tableName, final RegionLocations location); 89 90 /** 91 * Allows flushing the region cache of all locations that pertain to 92 * <code>tableName</code> 93 * @param tableName Name of the table whose regions we are to remove from 94 * cache. 95 */ 96 @Override 97 void clearRegionCache(final TableName tableName); 98 99 /** 100 * Deletes cached locations for the specific region. 101 * @param location The location object for the region, to be purged from cache. 102 */ 103 @Override 104 void deleteCachedRegionLocation(final HRegionLocation location); 105 106 /** 107 * Find the location of the region of <i>tableName</i> that <i>row</i> 108 * lives in, ignoring any value that might be in the cache. 109 * @param tableName name of the table <i>row</i> is in 110 * @param row row key you're trying to find the region of 111 * @return HRegionLocation that describes where to find the region in 112 * question 113 * @throws IOException if a remote or network exception occurs 114 */ 115 @Override 116 HRegionLocation relocateRegion(final TableName tableName, 117 final byte [] row) throws IOException; 118 119 /** 120 * Find the location of the region of <i>tableName</i> that <i>row</i> 121 * lives in, ignoring any value that might be in the cache. 122 * @param tableName name of the table <i>row</i> is in 123 * @param row row key you're trying to find the region of 124 * @param replicaId the replicaId of the region 125 * @return RegionLocations that describe where to find the region in 126 * question 127 * @throws IOException if a remote or network exception occurs 128 */ 129 RegionLocations relocateRegion(final TableName tableName, 130 final byte [] row, int replicaId) throws IOException; 131 132 /** 133 * Update the location cache. This is used internally by HBase, in most cases it should not be 134 * used by the client application. 135 * @param tableName the table name 136 * @param regionName the region name 137 * @param rowkey the row 138 * @param exception the exception if any. Can be null. 139 * @param source the previous location 140 */ 141 @Override 142 void updateCachedLocations(TableName tableName, byte[] regionName, byte[] rowkey, 143 Object exception, ServerName source); 144 145 146 /** 147 * Gets the location of the region of <i>regionName</i>. 148 * @param regionName name of the region to locate 149 * @return HRegionLocation that describes where to find the region in 150 * question 151 * @throws IOException if a remote or network exception occurs 152 */ 153 @Override 154 HRegionLocation locateRegion(final byte[] regionName) 155 throws IOException; 156 157 /** 158 * Gets the locations of all regions in the specified table, <i>tableName</i>. 159 * @param tableName table to get regions of 160 * @return list of region locations for all regions of table 161 * @throws IOException 162 */ 163 @Override 164 List<HRegionLocation> locateRegions(final TableName tableName) throws IOException; 165 166 /** 167 * Gets the locations of all regions in the specified table, <i>tableName</i>. 168 * @param tableName table to get regions of 169 * @param useCache Should we use the cache to retrieve the region information. 170 * @param offlined True if we are to include offlined regions, false and we'll leave out offlined 171 * regions from returned list. 172 * @return list of region locations for all regions of table 173 * @throws IOException 174 */ 175 @Override 176 List<HRegionLocation> locateRegions(final TableName tableName, 177 final boolean useCache, 178 final boolean offlined) throws IOException; 179 180 /** 181 * 182 * @param tableName table to get regions of 183 * @param row the row 184 * @param useCache Should we use the cache to retrieve the region information. 185 * @param retry do we retry 186 * @return region locations for this row. 187 * @throws IOException 188 */ 189 RegionLocations locateRegion(TableName tableName, 190 byte[] row, boolean useCache, boolean retry) throws IOException; 191 192 /** 193 * 194 * @param tableName table to get regions of 195 * @param row the row 196 * @param useCache Should we use the cache to retrieve the region information. 197 * @param retry do we retry 198 * @param replicaId the replicaId for the region 199 * @return region locations for this row. 200 * @throws IOException 201 */ 202 RegionLocations locateRegion(TableName tableName, 203 byte[] row, boolean useCache, boolean retry, int replicaId) throws IOException; 204 205 /** 206 * Returns a {@link MasterKeepAliveConnection} to the active master 207 */ 208 @Override 209 MasterService.BlockingInterface getMaster() throws IOException; 210 211 212 /** 213 * Establishes a connection to the region server at the specified address. 214 * @param serverName 215 * @return proxy for HRegionServer 216 * @throws IOException if a remote or network exception occurs 217 */ 218 @Override 219 AdminService.BlockingInterface getAdmin(final ServerName serverName) throws IOException; 220 221 /** 222 * Establishes a connection to the region server at the specified address, and returns 223 * a region client protocol. 224 * 225 * @param serverName 226 * @return ClientProtocol proxy for RegionServer 227 * @throws IOException if a remote or network exception occurs 228 * 229 */ 230 @Override 231 ClientService.BlockingInterface getClient(final ServerName serverName) throws IOException; 232 233 /** 234 * Find region location hosting passed row 235 * @param tableName table name 236 * @param row Row to find. 237 * @param reload If true do not use cache, otherwise bypass. 238 * @return Location of row. 239 * @throws IOException if a remote or network exception occurs 240 */ 241 @Override 242 HRegionLocation getRegionLocation(TableName tableName, byte [] row, 243 boolean reload) 244 throws IOException; 245 246 /** 247 * Clear any caches that pertain to server name <code>sn</code>. 248 * @param sn A server name 249 */ 250 @Override 251 void clearCaches(final ServerName sn); 252 253 /** 254 * This function allows HBaseAdmin and potentially others to get a shared MasterService 255 * connection. 256 * @return The shared instance. Never returns null. 257 * @throws MasterNotRunningException 258 */ 259 @Override 260 @Deprecated 261 MasterKeepAliveConnection getKeepAliveMasterService() 262 throws MasterNotRunningException; 263 264 /** 265 * @param serverName 266 * @return true if the server is known as dead, false otherwise. 267 * @deprecated internal method, do not use thru HConnection */ 268 @Override 269 @Deprecated 270 boolean isDeadServer(ServerName serverName); 271 272 /** 273 * @return Nonce generator for this HConnection; may be null if disabled in configuration. 274 */ 275 @Override 276 public NonceGenerator getNonceGenerator(); 277 278 /** 279 * @return Default AsyncProcess associated with this connection. 280 */ 281 AsyncProcess getAsyncProcess(); 282 283 /** 284 * Returns a new RpcRetryingCallerFactory from the given {@link Configuration}. 285 * This RpcRetryingCallerFactory lets the users create {@link RpcRetryingCaller}s which can be 286 * intercepted with the configured {@link RetryingCallerInterceptor} 287 * @param conf 288 * @return RpcRetryingCallerFactory 289 */ 290 RpcRetryingCallerFactory getNewRpcRetryingCallerFactory(Configuration conf); 291 292 /** 293 * @return Connection's RpcRetryingCallerFactory instance 294 */ 295 RpcRetryingCallerFactory getRpcRetryingCallerFactory(); 296 297 /** 298 * @return Connection's RpcControllerFactory instance 299 */ 300 RpcControllerFactory getRpcControllerFactory(); 301 302 /** 303 * @return a ConnectionConfiguration object holding parsed configuration values 304 */ 305 ConnectionConfiguration getConnectionConfiguration(); 306 307 /** 308 * 309 * @return true if this is a managed connection. 310 */ 311 boolean isManaged(); 312 313 /** 314 * @return the current statistics tracker associated with this connection 315 */ 316 ServerStatisticTracker getStatisticsTracker(); 317 318 /** 319 * @return the configured client backoff policy 320 */ 321 ClientBackoffPolicy getBackoffPolicy(); 322 }