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 }