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