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 }