hbase-client/src/main/java/org/apache/hadoop/hbase/client/ClusterConnection.java

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