001/**
002 *
003
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  You may obtain a copy of the License at
011 *
012 *     http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing, software
015 * distributed under the License is distributed on an "AS IS" BASIS,
016 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017 * See the License for the specific language governing permissions and
018 * limitations under the License.
019 */
020package org.apache.hadoop.hbase.client;
021
022import java.io.IOException;
023import java.util.List;
024import org.apache.hadoop.conf.Configuration;
025import org.apache.hadoop.hbase.HRegionLocation;
026import org.apache.hadoop.hbase.MasterNotRunningException;
027import org.apache.hadoop.hbase.RegionLocations;
028import org.apache.hadoop.hbase.ServerName;
029import org.apache.hadoop.hbase.TableName;
030import org.apache.hadoop.hbase.ZooKeeperConnectionException;
031import org.apache.hadoop.hbase.client.backoff.ClientBackoffPolicy;
032import org.apache.hadoop.hbase.ipc.RpcControllerFactory;
033import org.apache.yetus.audience.InterfaceAudience;
034
035import org.apache.hadoop.hbase.shaded.protobuf.generated.AdminProtos.AdminService;
036import org.apache.hadoop.hbase.shaded.protobuf.generated.ClientProtos.ClientService;
037
038/** Internal methods on Connection that should not be used by user code. */
039@InterfaceAudience.Private
040// NOTE: Although this class is public, this class is meant to be used directly from internal
041// classes and unit tests only.
042public interface ClusterConnection extends Connection {
043
044  /**
045   * Key for configuration in Configuration whose value is the class we implement making a
046   * new Connection instance.
047   */
048  String HBASE_CLIENT_CONNECTION_IMPL = "hbase.client.connection.impl";
049
050  /**
051   * @return - true if the master server is running
052   * @deprecated this has been deprecated without a replacement
053   */
054  @Deprecated
055  boolean isMasterRunning()
056      throws MasterNotRunningException, ZooKeeperConnectionException;
057
058  /**
059   * Use this api to check if the table has been created with the specified number of
060   * splitkeys which was used while creating the given table.
061   * Note : If this api is used after a table's region gets splitted, the api may return
062   * false.
063   * @param tableName
064   *          tableName
065   * @param splitKeys
066   *          splitKeys used while creating table
067   * @throws IOException
068   *           if a remote or network exception occurs
069   */
070  boolean isTableAvailable(TableName tableName, byte[][] splitKeys) throws
071      IOException;
072
073  /**
074   * A table that isTableEnabled == false and isTableDisabled == false
075   * is possible. This happens when a table has a lot of regions
076   * that must be processed.
077   * @param tableName table name
078   * @return true if the table is enabled, false otherwise
079   * @throws IOException if a remote or network exception occurs
080   */
081  boolean isTableEnabled(TableName tableName) throws IOException;
082
083  /**
084   * @param tableName table name
085   * @return true if the table is disabled, false otherwise
086   * @throws IOException if a remote or network exception occurs
087   */
088  boolean isTableDisabled(TableName tableName) throws IOException;
089
090  /**
091   * Retrieve TableState, represent current table state.
092   * @param tableName table state for
093   * @return state of the table
094   */
095  TableState getTableState(TableName tableName)  throws IOException;
096
097  /**
098   * Find the location of the region of <i>tableName</i> that <i>row</i>
099   * lives in.
100   * @param tableName name of the table <i>row</i> is in
101   * @param row row key you're trying to find the region of
102   * @return HRegionLocation that describes where to find the region in
103   *   question
104   * @throws IOException if a remote or network exception occurs
105   */
106  HRegionLocation locateRegion(final TableName tableName,
107      final byte [] row) throws IOException;
108
109  /**
110   * @deprecated {@link #clearRegionLocationCache()} instead.
111   */
112  @Deprecated
113  default void clearRegionCache() {
114    clearRegionLocationCache();
115  }
116
117  void cacheLocation(final TableName tableName, final RegionLocations location);
118
119  /**
120   * Allows flushing the region cache of all locations that pertain to
121   * <code>tableName</code>
122   * @param tableName Name of the table whose regions we are to remove from
123   *   cache.
124   */
125  void clearRegionCache(final TableName tableName);
126
127  /**
128   * Deletes cached locations for the specific region.
129   * @param location The location object for the region, to be purged from cache.
130   */
131  void deleteCachedRegionLocation(final HRegionLocation location);
132
133  /**
134   * Find the location of the region of <i>tableName</i> that <i>row</i>
135   * lives in, ignoring any value that might be in the cache.
136   * @param tableName name of the table <i>row</i> is in
137   * @param row row key you're trying to find the region of
138   * @return HRegionLocation that describes where to find the region in
139   *   question
140   * @throws IOException if a remote or network exception occurs
141   */
142  HRegionLocation relocateRegion(final TableName tableName,
143      final byte [] row) throws IOException;
144
145  /**
146   * Find the location of the region of <i>tableName</i> that <i>row</i>
147   * lives in, ignoring any value that might be in the cache.
148   * @param tableName name of the table <i>row</i> is in
149   * @param row row key you're trying to find the region of
150   * @param replicaId the replicaId of the region
151   * @return RegionLocations that describe where to find the region in
152   *   question
153   * @throws IOException if a remote or network exception occurs
154   */
155  RegionLocations relocateRegion(final TableName tableName,
156      final byte [] row, int replicaId) throws IOException;
157
158  /**
159   * Update the location cache. This is used internally by HBase, in most cases it should not be
160   *  used by the client application.
161   * @param tableName the table name
162   * @param regionName the region name
163   * @param rowkey the row
164   * @param exception the exception if any. Can be null.
165   * @param source the previous location
166   */
167  void updateCachedLocations(TableName tableName, byte[] regionName, byte[] rowkey,
168                                    Object exception, ServerName source);
169
170  /**
171   * Gets the location of the region of <i>regionName</i>.
172   * @param regionName name of the region to locate
173   * @return HRegionLocation that describes where to find the region in
174   *   question
175   * @throws IOException if a remote or network exception occurs
176   */
177  HRegionLocation locateRegion(final byte[] regionName)
178  throws IOException;
179
180  /**
181   * Gets the locations of all regions in the specified table, <i>tableName</i>.
182   * @param tableName table to get regions of
183   * @return list of region locations for all regions of table
184   * @throws IOException if IO failure occurs
185   */
186  List<HRegionLocation> locateRegions(final TableName tableName) 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   * @param useCache Should we use the cache to retrieve the region information.
192   * @param offlined True if we are to include offlined regions, false and we'll leave out offlined
193   *          regions from returned list.
194   * @return list of region locations for all regions of table
195   * @throws IOException if IO failure occurs
196   */
197  List<HRegionLocation> locateRegions(final TableName tableName,
198      final boolean useCache,
199      final boolean offlined) throws IOException;
200
201  /**
202   *
203   * @param tableName table to get regions of
204   * @param row the row
205   * @param useCache Should we use the cache to retrieve the region information.
206   * @param retry do we retry
207   * @return region locations for this row.
208   * @throws IOException if IO failure occurs
209   */
210  RegionLocations locateRegion(TableName tableName,
211                               byte[] row, boolean useCache, boolean retry) throws IOException;
212
213 /**
214  *
215  * @param tableName table to get regions of
216  * @param row the row
217  * @param useCache Should we use the cache to retrieve the region information.
218  * @param retry do we retry
219  * @param replicaId the replicaId for the region
220  * @return region locations for this row.
221  * @throws IOException if IO failure occurs
222  */
223  RegionLocations locateRegion(TableName tableName, byte[] row, boolean useCache, boolean retry,
224     int replicaId) throws IOException;
225
226  /**
227   * Returns a {@link MasterKeepAliveConnection} to the active master
228   */
229  MasterKeepAliveConnection getMaster() throws IOException;
230
231  /**
232   * Get the admin service for master.
233   */
234  AdminService.BlockingInterface getAdminForMaster() throws IOException;
235
236  /**
237   * Establishes a connection to the region server at the specified address.
238   * @param serverName the region server to connect to
239   * @return proxy for HRegionServer
240   * @throws IOException if a remote or network exception occurs
241   */
242  AdminService.BlockingInterface getAdmin(final ServerName serverName) throws IOException;
243
244  /**
245   * Establishes a connection to the region server at the specified address, and returns
246   * a region client protocol.
247   *
248   * @param serverName the region server to connect to
249   * @return ClientProtocol proxy for RegionServer
250   * @throws IOException if a remote or network exception occurs
251   *
252   */
253  ClientService.BlockingInterface getClient(final ServerName serverName) throws IOException;
254
255  /**
256   * Find region location hosting passed row
257   * @param tableName table name
258   * @param row Row to find.
259   * @param reload If true do not use cache, otherwise bypass.
260   * @return Location of row.
261   * @throws IOException if a remote or network exception occurs
262   */
263  HRegionLocation getRegionLocation(TableName tableName, byte[] row, boolean reload)
264      throws IOException;
265
266  /**
267   * Clear any caches that pertain to server name <code>sn</code>.
268   * @param sn A server name
269   */
270  void clearCaches(final ServerName sn);
271
272  /**
273   * @return Nonce generator for this ClusterConnection; may be null if disabled in configuration.
274   */
275  NonceGenerator getNonceGenerator();
276
277  /**
278   * @return Default AsyncProcess associated with this connection.
279   */
280  AsyncProcess getAsyncProcess();
281
282  /**
283   * Returns a new RpcRetryingCallerFactory from the given {@link Configuration}.
284   * This RpcRetryingCallerFactory lets the users create {@link RpcRetryingCaller}s which can be
285   * intercepted with the configured {@link RetryingCallerInterceptor}
286   * @param conf configuration
287   * @return RpcRetryingCallerFactory
288   */
289  RpcRetryingCallerFactory getNewRpcRetryingCallerFactory(Configuration conf);
290
291  /**
292   * @return Connection's RpcRetryingCallerFactory instance
293   */
294  RpcRetryingCallerFactory getRpcRetryingCallerFactory();
295
296  /**
297   * @return Connection's RpcControllerFactory instance
298   */
299  RpcControllerFactory getRpcControllerFactory();
300
301  /**
302   * @return a ConnectionConfiguration object holding parsed configuration values
303   */
304  ConnectionConfiguration getConnectionConfiguration();
305
306  /**
307   * @return the current statistics tracker associated with this connection
308   */
309  ServerStatisticTracker getStatisticsTracker();
310
311  /**
312   * @return the configured client backoff policy
313   */
314  ClientBackoffPolicy getBackoffPolicy();
315
316  /**
317   * @return the MetricsConnection instance associated with this connection.
318   */
319  MetricsConnection getConnectionMetrics();
320
321  /**
322   * @return true when this connection uses a {@link org.apache.hadoop.hbase.codec.Codec} and so
323   *         supports cell blocks.
324   */
325  boolean hasCellBlockSupport();
326}