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.protobuf.generated.AdminProtos.AdminService;
34 import org.apache.hadoop.hbase.protobuf.generated.ClientProtos.ClientService;
35 import org.apache.hadoop.hbase.protobuf.generated.MasterProtos.MasterService;
36
37 /** Internal methods on HConnection that should not be used by user code. */
38 @InterfaceAudience.Private
39 // NOTE: Although this class is public, this class is meant to be used directly from internal
40 // classes and unit tests only.
41 public interface ClusterConnection extends HConnection {
42
43 /** @return - true if the master server is running
44 * @deprecated this has been deprecated without a replacement */
45 @Override
46 @Deprecated
47 boolean isMasterRunning()
48 throws MasterNotRunningException, ZooKeeperConnectionException;
49
50 /**
51 * Use this api to check if the table has been created with the specified number of
52 * splitkeys which was used while creating the given table.
53 * Note : If this api is used after a table's region gets splitted, the api may return
54 * false.
55 * @param tableName
56 * tableName
57 * @param splitKeys
58 * splitKeys used while creating table
59 * @throws IOException
60 * if a remote or network exception occurs
61 */
62 @Override
63 boolean isTableAvailable(TableName tableName, byte[][] splitKeys) throws
64 IOException;
65
66 /**
67 * Find the location of the region of <i>tableName</i> that <i>row</i>
68 * lives in.
69 * @param tableName name of the table <i>row</i> is in
70 * @param row row key you're trying to find the region of
71 * @return HRegionLocation that describes where to find the region in
72 * question
73 * @throws IOException if a remote or network exception occurs
74 */
75 @Override
76 public HRegionLocation locateRegion(final TableName tableName,
77 final byte [] row) throws IOException;
78
79 /**
80 * Allows flushing the region cache.
81 */
82 @Override
83 void clearRegionCache();
84
85 /**
86 * Allows flushing the region cache of all locations that pertain to
87 * <code>tableName</code>
88 * @param tableName Name of the table whose regions we are to remove from
89 * cache.
90 */
91 @Override
92 void clearRegionCache(final TableName tableName);
93
94 /**
95 * Deletes cached locations for the specific region.
96 * @param location The location object for the region, to be purged from cache.
97 */
98 @Override
99 void deleteCachedRegionLocation(final HRegionLocation location);
100
101 /**
102 * Find the location of the region of <i>tableName</i> that <i>row</i>
103 * lives in, ignoring any value that might be in the cache.
104 * @param tableName name of the table <i>row</i> is in
105 * @param row row key you're trying to find the region of
106 * @return HRegionLocation that describes where to find the region in
107 * question
108 * @throws IOException if a remote or network exception occurs
109 */
110 @Override
111 HRegionLocation relocateRegion(final TableName tableName,
112 final byte [] row) throws IOException;
113
114 /**
115 * Find the location of the region of <i>tableName</i> that <i>row</i>
116 * lives in, ignoring any value that might be in the cache.
117 * @param tableName name of the table <i>row</i> is in
118 * @param row row key you're trying to find the region of
119 * @param replicaId the replicaId of the region
120 * @return RegionLocations that describe where to find the region in
121 * question
122 * @throws IOException if a remote or network exception occurs
123 */
124 RegionLocations relocateRegion(final TableName tableName,
125 final byte [] row, int replicaId) throws IOException;
126
127 /**
128 * Update the location cache. This is used internally by HBase, in most cases it should not be
129 * used by the client application.
130 * @param tableName the table name
131 * @param regionName the region name
132 * @param rowkey the row
133 * @param exception the exception if any. Can be null.
134 * @param source the previous location
135 */
136 @Override
137 void updateCachedLocations(TableName tableName, byte[] regionName, byte[] rowkey,
138 Object exception, ServerName source);
139
140
141 /**
142 * Gets the location of the region of <i>regionName</i>.
143 * @param regionName name of the region to locate
144 * @return HRegionLocation that describes where to find the region in
145 * question
146 * @throws IOException if a remote or network exception occurs
147 */
148 @Override
149 HRegionLocation locateRegion(final byte[] regionName)
150 throws IOException;
151
152 /**
153 * Gets the locations of all regions in the specified table, <i>tableName</i>.
154 * @param tableName table to get regions of
155 * @return list of region locations for all regions of table
156 * @throws IOException
157 */
158 @Override
159 List<HRegionLocation> locateRegions(final TableName tableName) throws IOException;
160
161 /**
162 * Gets the locations of all regions in the specified table, <i>tableName</i>.
163 * @param tableName table to get regions of
164 * @param useCache Should we use the cache to retrieve the region information.
165 * @param offlined True if we are to include offlined regions, false and we'll leave out offlined
166 * regions from returned list.
167 * @return list of region locations for all regions of table
168 * @throws IOException
169 */
170 @Override
171 List<HRegionLocation> locateRegions(final TableName tableName,
172 final boolean useCache,
173 final boolean offlined) throws IOException;
174
175 /**
176 *
177 * @param tableName table to get regions of
178 * @param row the row
179 * @param useCache Should we use the cache to retrieve the region information.
180 * @param retry do we retry
181 * @return region locations for this row.
182 * @throws IOException
183 */
184 RegionLocations locateRegion(TableName tableName,
185 byte[] row, boolean useCache, boolean retry) throws IOException;
186
187 /**
188 *
189 * @param tableName table to get regions of
190 * @param row the row
191 * @param useCache Should we use the cache to retrieve the region information.
192 * @param retry do we retry
193 * @param replicaId the replicaId for the region
194 * @return region locations for this row.
195 * @throws IOException
196 */
197 RegionLocations locateRegion(TableName tableName,
198 byte[] row, boolean useCache, boolean retry, int replicaId) throws IOException;
199
200 /**
201 * Returns a {@link MasterKeepAliveConnection} to the active master
202 */
203 @Override
204 MasterService.BlockingInterface getMaster() throws IOException;
205
206
207 /**
208 * Establishes a connection to the region server at the specified address.
209 * @param serverName
210 * @return proxy for HRegionServer
211 * @throws IOException if a remote or network exception occurs
212 */
213 @Override
214 AdminService.BlockingInterface getAdmin(final ServerName serverName) throws IOException;
215
216 /**
217 * Establishes a connection to the region server at the specified address, and returns
218 * a region client protocol.
219 *
220 * @param serverName
221 * @return ClientProtocol proxy for RegionServer
222 * @throws IOException if a remote or network exception occurs
223 *
224 */
225 @Override
226 ClientService.BlockingInterface getClient(final ServerName serverName) throws IOException;
227
228 /**
229 * Find region location hosting passed row
230 * @param tableName table name
231 * @param row Row to find.
232 * @param reload If true do not use cache, otherwise bypass.
233 * @return Location of row.
234 * @throws IOException if a remote or network exception occurs
235 */
236 @Override
237 HRegionLocation getRegionLocation(TableName tableName, byte [] row,
238 boolean reload)
239 throws IOException;
240
241 /**
242 * Clear any caches that pertain to server name <code>sn</code>.
243 * @param sn A server name
244 */
245 @Override
246 void clearCaches(final ServerName sn);
247
248 /**
249 * This function allows HBaseAdmin and potentially others to get a shared MasterService
250 * connection.
251 * @return The shared instance. Never returns null.
252 * @throws MasterNotRunningException
253 */
254 @Override
255 @Deprecated
256 MasterKeepAliveConnection getKeepAliveMasterService()
257 throws MasterNotRunningException;
258
259 /**
260 * @param serverName
261 * @return true if the server is known as dead, false otherwise.
262 * @deprecated internal method, do not use thru HConnection */
263 @Override
264 @Deprecated
265 boolean isDeadServer(ServerName serverName);
266
267 /**
268 * @return Nonce generator for this HConnection; may be null if disabled in configuration.
269 */
270 @Override
271 public NonceGenerator getNonceGenerator();
272
273 /**
274 * @return Default AsyncProcess associated with this connection.
275 */
276 AsyncProcess getAsyncProcess();
277
278 /**
279 * Returns a new RpcRetryingCallerFactory from the given {@link Configuration}.
280 * This RpcRetryingCallerFactory lets the users create {@link RpcRetryingCaller}s which can be
281 * intercepted with the configured {@link RetryingCallerInterceptor}
282 * @param conf
283 * @return RpcRetryingCallerFactory
284 */
285 RpcRetryingCallerFactory getNewRpcRetryingCallerFactory(Configuration conf);
286
287 /**
288 *
289 * @return true if this is a managed connection.
290 */
291 boolean isManaged();
292
293 /**
294 * @return the current statistics tracker associated with this connection
295 */
296 ServerStatisticTracker getStatisticsTracker();
297
298 /**
299 * @return the configured client backoff policy
300 */
301 ClientBackoffPolicy getBackoffPolicy();
302
303 /**
304 * @return the MetricsConnection instance associated with this connection.
305 */
306 public MetricsConnection getConnectionMetrics();
307
308 /**
309 * @return true when this connection uses a {@link org.apache.hadoop.hbase.codec.Codec} and so
310 * supports cell blocks.
311 */
312 boolean hasCellBlockSupport();
313 }