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.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    void cacheLocation(final TableName tableName, final RegionLocations location);
88  
89    /**
90     * Allows flushing the region cache of all locations that pertain to
91     * <code>tableName</code>
92     * @param tableName Name of the table whose regions we are to remove from
93     * cache.
94     */
95    @Override
96    void clearRegionCache(final TableName tableName);
97  
98    /**
99     * Deletes cached locations for the specific region.
100    * @param location The location object for the region, to be purged from cache.
101    */
102   @Override
103   void deleteCachedRegionLocation(final HRegionLocation location);
104 
105   /**
106    * Find the location of the region of <i>tableName</i> that <i>row</i>
107    * lives in, ignoring any value that might be in the cache.
108    * @param tableName name of the table <i>row</i> is in
109    * @param row row key you're trying to find the region of
110    * @return HRegionLocation that describes where to find the region in
111    * question
112    * @throws IOException if a remote or network exception occurs
113    */
114   @Override
115   HRegionLocation relocateRegion(final TableName tableName,
116       final byte [] row) throws IOException;
117 
118   /**
119    * Find the location of the region of <i>tableName</i> that <i>row</i>
120    * lives in, ignoring any value that might be in the cache.
121    * @param tableName name of the table <i>row</i> is in
122    * @param row row key you're trying to find the region of
123    * @param replicaId the replicaId of the region
124    * @return RegionLocations that describe where to find the region in
125    * question
126    * @throws IOException if a remote or network exception occurs
127    */
128   RegionLocations relocateRegion(final TableName tableName,
129       final byte [] row, int replicaId) throws IOException;
130 
131   /**
132    * Update the location cache. This is used internally by HBase, in most cases it should not be
133    *  used by the client application.
134    * @param tableName the table name
135    * @param regionName the region name
136    * @param rowkey the row
137    * @param exception the exception if any. Can be null.
138    * @param source the previous location
139    */
140   @Override
141   void updateCachedLocations(TableName tableName, byte[] regionName, byte[] rowkey,
142                                     Object exception, ServerName source);
143 
144 
145   /**
146    * Gets the location of the region of <i>regionName</i>.
147    * @param regionName name of the region to locate
148    * @return HRegionLocation that describes where to find the region in
149    * question
150    * @throws IOException if a remote or network exception occurs
151    */
152   @Override
153   HRegionLocation locateRegion(final byte[] regionName)
154   throws IOException;
155 
156   /**
157    * Gets the locations of all regions in the specified table, <i>tableName</i>.
158    * @param tableName table to get regions of
159    * @return list of region locations for all regions of table
160    * @throws IOException
161    */
162   @Override
163   List<HRegionLocation> locateRegions(final TableName tableName) throws IOException;
164 
165   /**
166    * Gets the locations of all regions in the specified table, <i>tableName</i>.
167    * @param tableName table to get regions of
168    * @param useCache Should we use the cache to retrieve the region information.
169    * @param offlined True if we are to include offlined regions, false and we'll leave out offlined
170    *          regions from returned list.
171    * @return list of region locations for all regions of table
172    * @throws IOException
173    */
174   @Override
175   List<HRegionLocation> locateRegions(final TableName tableName,
176       final boolean useCache,
177       final boolean offlined) throws IOException;
178 
179   /**
180    *
181    * @param tableName table to get regions of
182    * @param row the row
183    * @param useCache Should we use the cache to retrieve the region information.
184    * @param retry do we retry
185    * @return region locations for this row.
186    * @throws IOException
187    */
188   RegionLocations locateRegion(TableName tableName,
189                                byte[] row, boolean useCache, boolean retry) throws IOException;
190 
191   /**
192   *
193   * @param tableName table to get regions of
194   * @param row the row
195   * @param useCache Should we use the cache to retrieve the region information.
196   * @param retry do we retry
197   * @param replicaId the replicaId for the region
198   * @return region locations for this row.
199   * @throws IOException
200   */
201  RegionLocations locateRegion(TableName tableName,
202                               byte[] row, boolean useCache, boolean retry, int replicaId) throws IOException;
203 
204   /**
205    * Returns a {@link MasterKeepAliveConnection} to the active master
206    */
207   @Override
208   MasterService.BlockingInterface getMaster() throws IOException;
209 
210 
211   /**
212    * Establishes a connection to the region server at the specified address.
213    * @param serverName
214    * @return proxy for HRegionServer
215    * @throws IOException if a remote or network exception occurs
216    */
217   @Override
218   AdminService.BlockingInterface getAdmin(final ServerName serverName) throws IOException;
219 
220   /**
221    * Establishes a connection to the region server at the specified address, and returns
222    * a region client protocol.
223    *
224    * @param serverName
225    * @return ClientProtocol proxy for RegionServer
226    * @throws IOException if a remote or network exception occurs
227    *
228    */
229   @Override
230   ClientService.BlockingInterface getClient(final ServerName serverName) throws IOException;
231 
232   /**
233    * Find region location hosting passed row
234    * @param tableName table name
235    * @param row Row to find.
236    * @param reload If true do not use cache, otherwise bypass.
237    * @return Location of row.
238    * @throws IOException if a remote or network exception occurs
239    */
240   @Override
241   HRegionLocation getRegionLocation(TableName tableName, byte [] row,
242     boolean reload)
243   throws IOException;
244 
245   /**
246    * Clear any caches that pertain to server name <code>sn</code>.
247    * @param sn A server name
248    */
249   @Override
250   void clearCaches(final ServerName sn);
251 
252   /**
253    * This function allows HBaseAdmin and potentially others to get a shared MasterService
254    * connection.
255    * @return The shared instance. Never returns null.
256    * @throws MasterNotRunningException
257    */
258   @Override
259   @Deprecated
260   MasterKeepAliveConnection getKeepAliveMasterService()
261   throws MasterNotRunningException;
262 
263   /**
264    * @param serverName
265    * @return true if the server is known as dead, false otherwise.
266    * @deprecated internal method, do not use thru HConnection */
267   @Override
268   @Deprecated
269   boolean isDeadServer(ServerName serverName);
270 
271   /**
272    * @return Nonce generator for this HConnection; may be null if disabled in configuration.
273    */
274   @Override
275   public 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
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    * 
308    * @return true if this is a managed connection.
309    */
310   boolean isManaged();
311 
312   /**
313    * @return the current statistics tracker associated with this connection
314    */
315   ServerStatisticTracker getStatisticsTracker();
316 
317   /**
318    * @return the configured client backoff policy
319    */
320   ClientBackoffPolicy getBackoffPolicy();
321 
322   /**
323    * @return the MetricsConnection instance associated with this connection.
324    */
325   public MetricsConnection getConnectionMetrics();
326 
327   /**
328    * @return true when this connection uses a {@link org.apache.hadoop.hbase.codec.Codec} and so
329    *         supports cell blocks.
330    */
331   boolean hasCellBlockSupport();
332 }