View Javadoc

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 }