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.Closeable;
22 import java.io.IOException;
23 import java.util.List;
24 import java.util.concurrent.ExecutorService;
25
26 import org.apache.hadoop.classification.InterfaceAudience;
27 import org.apache.hadoop.classification.InterfaceStability;
28 import org.apache.hadoop.conf.Configuration;
29 import org.apache.hadoop.hbase.Abortable;
30 import org.apache.hadoop.hbase.TableName;
31 import org.apache.hadoop.hbase.HRegionLocation;
32 import org.apache.hadoop.hbase.HTableDescriptor;
33 import org.apache.hadoop.hbase.MasterNotRunningException;
34 import org.apache.hadoop.hbase.ServerName;
35 import org.apache.hadoop.hbase.ZooKeeperConnectionException;
36 import org.apache.hadoop.hbase.catalog.CatalogTracker;
37 import org.apache.hadoop.hbase.client.coprocessor.Batch;
38 import org.apache.hadoop.hbase.protobuf.generated.AdminProtos.AdminService;
39 import org.apache.hadoop.hbase.protobuf.generated.ClientProtos.ClientService;
40 import org.apache.hadoop.hbase.protobuf.generated.MasterAdminProtos.MasterAdminService;
41 import org.apache.hadoop.hbase.protobuf.generated.MasterMonitorProtos.MasterMonitorService;
42
43 /**
44 * A cluster connection. Knows how to find the master, locate regions out on the cluster,
45 * keeps a cache of locations and then knows how to recalibrate after they move.
46 * {@link HConnectionManager} manages instances of this class. This is NOT a connection to a
47 * particular server but to all servers in the cluster. An implementation takes care of individual
48 * connections at a lower level.
49 *
50 * <p>HConnections are used by {@link HTable} mostly but also by
51 * {@link HBaseAdmin}, and {@link CatalogTracker}. HConnection instances can be shared. Sharing
52 * is usually what you want because rather than each HConnection instance
53 * having to do its own discovery of regions out on the cluster, instead, all
54 * clients get to share the one cache of locations. {@link HConnectionManager} does the
55 * sharing for you if you go by it getting connections. Sharing makes cleanup of
56 * HConnections awkward. See {@link HConnectionManager} for cleanup discussion.
57 *
58 * @see HConnectionManager
59 */
60 @InterfaceAudience.Public
61 @InterfaceStability.Stable
62 public interface HConnection extends Abortable, Closeable {
63 /**
64 * Key for configuration in Configuration whose value is the class we implement making a
65 * new HConnection instance.
66 */
67 public static final String HBASE_CLIENT_CONNECTION_IMPL = "hbase.client.connection.impl";
68
69 /**
70 * @return Configuration instance being used by this HConnection instance.
71 */
72 Configuration getConfiguration();
73
74 /**
75 * Retrieve an HTableInterface implementation for access to a table.
76 * The returned HTableInterface is not thread safe, a new instance should
77 * be created for each using thread.
78 * This is a lightweight operation, pooling or caching of the returned HTableInterface
79 * is neither required nor desired.
80 * Note that the HConnection needs to be unmanaged
81 * (created with {@link HConnectionManager#createConnection(Configuration)}).
82 * @param tableName
83 * @return an HTable to use for interactions with this table
84 */
85 public HTableInterface getTable(String tableName) throws IOException;
86
87 /**
88 * Retrieve an HTableInterface implementation for access to a table.
89 * The returned HTableInterface is not thread safe, a new instance should
90 * be created for each using thread.
91 * This is a lightweight operation, pooling or caching of the returned HTableInterface
92 * is neither required nor desired.
93 * Note that the HConnection needs to be unmanaged
94 * (created with {@link HConnectionManager#createConnection(Configuration)}).
95 * @param tableName
96 * @return an HTable to use for interactions with this table
97 */
98 public HTableInterface getTable(byte[] tableName) throws IOException;
99
100 /**
101 * Retrieve an HTableInterface implementation for access to a table.
102 * The returned HTableInterface is not thread safe, a new instance should
103 * be created for each using thread.
104 * This is a lightweight operation, pooling or caching of the returned HTableInterface
105 * is neither required nor desired.
106 * Note that the HConnection needs to be unmanaged
107 * (created with {@link HConnectionManager#createConnection(Configuration)}).
108 * @param tableName
109 * @return an HTable to use for interactions with this table
110 */
111 public HTableInterface getTable(TableName tableName) throws IOException;
112
113 /**
114 * Retrieve an HTableInterface implementation for access to a table.
115 * The returned HTableInterface is not thread safe, a new instance should
116 * be created for each using thread.
117 * This is a lightweight operation, pooling or caching of the returned HTableInterface
118 * is neither required nor desired.
119 * Note that the HConnection needs to be unmanaged
120 * (created with {@link HConnectionManager#createConnection(Configuration)}).
121 * @param tableName
122 * @param pool The thread pool to use for batch operations, null to use a default pool.
123 * @return an HTable to use for interactions with this table
124 */
125 public HTableInterface getTable(String tableName, ExecutorService pool) throws IOException;
126
127 /**
128 * Retrieve an HTableInterface implementation for access to a table.
129 * The returned HTableInterface is not thread safe, a new instance should
130 * be created for each using thread.
131 * This is a lightweight operation, pooling or caching of the returned HTableInterface
132 * is neither required nor desired.
133 * Note that the HConnection needs to be unmanaged
134 * (created with {@link HConnectionManager#createConnection(Configuration)}).
135 * @param tableName
136 * @param pool The thread pool to use for batch operations, null to use a default pool.
137 * @return an HTable to use for interactions with this table
138 */
139 public HTableInterface getTable(byte[] tableName, ExecutorService pool) throws IOException;
140
141 /**
142 * Retrieve an HTableInterface implementation for access to a table.
143 * The returned HTableInterface is not thread safe, a new instance should
144 * be created for each using thread.
145 * This is a lightweight operation, pooling or caching of the returned HTableInterface
146 * is neither required nor desired.
147 * Note that the HConnection needs to be unmanaged
148 * (created with {@link HConnectionManager#createConnection(Configuration)}).
149 * @param tableName
150 * @param pool The thread pool to use for batch operations, null to use a default pool.
151 * @return an HTable to use for interactions with this table
152 */
153 public HTableInterface getTable(TableName tableName, ExecutorService pool) throws IOException;
154
155 /** @return - true if the master server is running */
156 boolean isMasterRunning()
157 throws MasterNotRunningException, ZooKeeperConnectionException;
158
159 /**
160 * A table that isTableEnabled == false and isTableDisabled == false
161 * is possible. This happens when a table has a lot of regions
162 * that must be processed.
163 * @param tableName table name
164 * @return true if the table is enabled, false otherwise
165 * @throws IOException if a remote or network exception occurs
166 */
167 boolean isTableEnabled(TableName tableName) throws IOException;
168
169 @Deprecated
170 boolean isTableEnabled(byte[] tableName) throws IOException;
171
172 /**
173 * @param tableName table name
174 * @return true if the table is disabled, false otherwise
175 * @throws IOException if a remote or network exception occurs
176 */
177 boolean isTableDisabled(TableName tableName) throws IOException;
178
179 @Deprecated
180 boolean isTableDisabled(byte[] tableName) throws IOException;
181
182 /**
183 * @param tableName table name
184 * @return true if all regions of the table are available, false otherwise
185 * @throws IOException if a remote or network exception occurs
186 */
187 boolean isTableAvailable(TableName tableName) throws IOException;
188
189 @Deprecated
190 boolean isTableAvailable(byte[] tableName) throws IOException;
191
192 /**
193 * Use this api to check if the table has been created with the specified number of
194 * splitkeys which was used while creating the given table.
195 * Note : If this api is used after a table's region gets splitted, the api may return
196 * false.
197 * @param tableName
198 * tableName
199 * @param splitKeys
200 * splitKeys used while creating table
201 * @throws IOException
202 * if a remote or network exception occurs
203 */
204 boolean isTableAvailable(TableName tableName, byte[][] splitKeys) throws
205 IOException;
206
207 @Deprecated
208 boolean isTableAvailable(byte[] tableName, byte[][] splitKeys) throws
209 IOException;
210
211 /**
212 * List all the userspace tables. In other words, scan the META table.
213 *
214 * If we wanted this to be really fast, we could implement a special
215 * catalog table that just contains table names and their descriptors.
216 * Right now, it only exists as part of the META table's region info.
217 *
218 * @return - returns an array of HTableDescriptors
219 * @throws IOException if a remote or network exception occurs
220 */
221 HTableDescriptor[] listTables() throws IOException;
222
223 // This is a bit ugly - We call this getTableNames in 0.94 and the
224 // successor function, returning TableName, listTableNames in later versions
225 // because Java polymorphism doesn't consider return value types
226
227 @Deprecated
228 String[] getTableNames() throws IOException;
229
230 TableName[] listTableNames() throws IOException;
231
232 /**
233 * @param tableName table name
234 * @return table metadata
235 * @throws IOException if a remote or network exception occurs
236 */
237 HTableDescriptor getHTableDescriptor(TableName tableName)
238 throws IOException;
239
240 @Deprecated
241 HTableDescriptor getHTableDescriptor(byte[] tableName)
242 throws IOException;
243
244 /**
245 * Find the location of the region of <i>tableName</i> that <i>row</i>
246 * lives in.
247 * @param tableName name of the table <i>row</i> is in
248 * @param row row key you're trying to find the region of
249 * @return HRegionLocation that describes where to find the region in
250 * question
251 * @throws IOException if a remote or network exception occurs
252 */
253 public HRegionLocation locateRegion(final TableName tableName,
254 final byte [] row) throws IOException;
255
256 @Deprecated
257 public HRegionLocation locateRegion(final byte[] tableName,
258 final byte [] row) throws IOException;
259
260 /**
261 * Allows flushing the region cache.
262 */
263 void clearRegionCache();
264
265 /**
266 * Allows flushing the region cache of all locations that pertain to
267 * <code>tableName</code>
268 * @param tableName Name of the table whose regions we are to remove from
269 * cache.
270 */
271 void clearRegionCache(final TableName tableName);
272
273 @Deprecated
274 void clearRegionCache(final byte[] tableName);
275
276 /**
277 * Deletes cached locations for the specific region.
278 * @param location The location object for the region, to be purged from cache.
279 */
280 void deleteCachedRegionLocation(final HRegionLocation location);
281
282 /**
283 * Find the location of the region of <i>tableName</i> that <i>row</i>
284 * lives in, ignoring any value that might be in the cache.
285 * @param tableName name of the table <i>row</i> is in
286 * @param row row key you're trying to find the region of
287 * @return HRegionLocation that describes where to find the region in
288 * question
289 * @throws IOException if a remote or network exception occurs
290 */
291 HRegionLocation relocateRegion(final TableName tableName,
292 final byte [] row) throws IOException;
293
294 @Deprecated
295 HRegionLocation relocateRegion(final byte[] tableName,
296 final byte [] row) throws IOException;
297
298 /**
299 * Update the location cache. This is used internally by HBase, in most cases it should not be
300 * used by the client application.
301 * @param tableName the table name
302 * @param rowkey the row
303 * @param exception the exception if any. Can be null.
304 * @param source the previous location
305 */
306 void updateCachedLocations(TableName tableName, byte[] rowkey,
307 Object exception, HRegionLocation source);
308
309 @Deprecated
310 void updateCachedLocations(byte[] tableName, byte[] rowkey,
311 Object exception, HRegionLocation source);
312
313 /**
314 * Gets the location of the region of <i>regionName</i>.
315 * @param regionName name of the region to locate
316 * @return HRegionLocation that describes where to find the region in
317 * question
318 * @throws IOException if a remote or network exception occurs
319 */
320 HRegionLocation locateRegion(final byte[] regionName)
321 throws IOException;
322
323 /**
324 * Gets the locations of all regions in the specified table, <i>tableName</i>.
325 * @param tableName table to get regions of
326 * @return list of region locations for all regions of table
327 * @throws IOException
328 */
329 List<HRegionLocation> locateRegions(final TableName tableName) throws IOException;
330
331 @Deprecated
332 List<HRegionLocation> locateRegions(final byte[] tableName) throws IOException;
333
334 /**
335 * Gets the locations of all regions in the specified table, <i>tableName</i>.
336 * @param tableName table to get regions of
337 * @param useCache Should we use the cache to retrieve the region information.
338 * @param offlined True if we are to include offlined regions, false and we'll leave out offlined
339 * regions from returned list.
340 * @return list of region locations for all regions of table
341 * @throws IOException
342 */
343 public List<HRegionLocation> locateRegions(final TableName tableName,
344 final boolean useCache,
345 final boolean offlined) throws IOException;
346
347 @Deprecated
348 public List<HRegionLocation> locateRegions(final byte[] tableName,
349 final boolean useCache,
350 final boolean offlined) throws IOException;
351
352 /**
353 * Returns a {@link MasterAdminKeepAliveConnection} to the active master
354 */
355 MasterAdminService.BlockingInterface getMasterAdmin() throws IOException;
356
357 /**
358 * Returns an {@link MasterMonitorKeepAliveConnection} to the active master
359 */
360 MasterMonitorService.BlockingInterface getMasterMonitor() throws IOException;
361
362 /**
363 * Establishes a connection to the region server at the specified address.
364 * @param serverName
365 * @return proxy for HRegionServer
366 * @throws IOException if a remote or network exception occurs
367 */
368 AdminService.BlockingInterface getAdmin(final ServerName serverName) throws IOException;
369
370 /**
371 * Establishes a connection to the region server at the specified address, and returns
372 * a region client protocol.
373 *
374 * @param serverName
375 * @return ClientProtocol proxy for RegionServer
376 * @throws IOException if a remote or network exception occurs
377 *
378 */
379 ClientService.BlockingInterface getClient(final ServerName serverName) throws IOException;
380
381 /**
382 * Establishes a connection to the region server at the specified address.
383 * @param serverName
384 * @param getMaster do we check if master is alive
385 * @return proxy for HRegionServer
386 * @throws IOException if a remote or network exception occurs
387 * @deprecated You can pass master flag but nothing special is done.
388 */
389 AdminService.BlockingInterface getAdmin(final ServerName serverName, boolean getMaster)
390 throws IOException;
391
392 /**
393 * Find region location hosting passed row
394 * @param tableName table name
395 * @param row Row to find.
396 * @param reload If true do not use cache, otherwise bypass.
397 * @return Location of row.
398 * @throws IOException if a remote or network exception occurs
399 */
400 HRegionLocation getRegionLocation(TableName tableName, byte [] row,
401 boolean reload)
402 throws IOException;
403
404 @Deprecated
405 HRegionLocation getRegionLocation(byte[] tableName, byte [] row,
406 boolean reload)
407 throws IOException;
408
409 /**
410 * Process a mixed batch of Get, Put and Delete actions. All actions for a
411 * RegionServer are forwarded in one RPC call.
412 *
413 *
414 * @param actions The collection of actions.
415 * @param tableName Name of the hbase table
416 * @param pool thread pool for parallel execution
417 * @param results An empty array, same size as list. If an exception is thrown,
418 * you can test here for partial results, and to determine which actions
419 * processed successfully.
420 * @throws IOException if there are problems talking to META. Per-item
421 * exceptions are stored in the results array.
422 * @deprecated since 0.96 - Use {@link HTableInterface#batch} instead
423 */
424 @Deprecated
425 void processBatch(List<? extends Row> actions, final TableName tableName,
426 ExecutorService pool, Object[] results) throws IOException, InterruptedException;
427
428 @Deprecated
429 void processBatch(List<? extends Row> actions, final byte[] tableName,
430 ExecutorService pool, Object[] results) throws IOException, InterruptedException;
431
432 /**
433 * Parameterized batch processing, allowing varying return types for different
434 * {@link Row} implementations.
435 * @deprecated since 0.96 - Use {@link HTableInterface#batchCallback} instead
436 */
437 @Deprecated
438 public <R> void processBatchCallback(List<? extends Row> list,
439 final TableName tableName,
440 ExecutorService pool,
441 Object[] results,
442 Batch.Callback<R> callback) throws IOException, InterruptedException;
443
444 @Deprecated
445 public <R> void processBatchCallback(List<? extends Row> list,
446 final byte[] tableName,
447 ExecutorService pool,
448 Object[] results,
449 Batch.Callback<R> callback) throws IOException, InterruptedException;
450
451 /**
452 * Enable or disable region cache prefetch for the table. It will be
453 * applied for the given table's all HTable instances within this
454 * connection. By default, the cache prefetch is enabled.
455 * @param tableName name of table to configure.
456 * @param enable Set to true to enable region cache prefetch.
457 */
458 public void setRegionCachePrefetch(final TableName tableName,
459 final boolean enable);
460
461 public void setRegionCachePrefetch(final byte[] tableName,
462 final boolean enable);
463
464 /**
465 * Check whether region cache prefetch is enabled or not.
466 * @param tableName name of table to check
467 * @return true if table's region cache prefetch is enabled. Otherwise
468 * it is disabled.
469 */
470 boolean getRegionCachePrefetch(final TableName tableName);
471
472 boolean getRegionCachePrefetch(final byte[] tableName);
473
474 /**
475 * @return the number of region servers that are currently running
476 * @throws IOException if a remote or network exception occurs
477 * @deprecated This method will be changed from public to package protected.
478 */
479 int getCurrentNrHRS() throws IOException;
480
481 /**
482 * @param tableNames List of table names
483 * @return HTD[] table metadata
484 * @throws IOException if a remote or network exception occurs
485 */
486 HTableDescriptor[] getHTableDescriptorsByTableName(List<TableName> tableNames) throws IOException;
487
488 @Deprecated
489 HTableDescriptor[] getHTableDescriptors(List<String> tableNames) throws
490 IOException;
491
492 /**
493 * @return true if this connection is closed
494 */
495 boolean isClosed();
496
497
498 /**
499 * Clear any caches that pertain to server name <code>sn</code>.
500 * @param sn A server name
501 */
502 void clearCaches(final ServerName sn);
503
504 /**
505 * This function allows HBaseAdmin and potentially others to get a shared MasterMonitor
506 * connection.
507 * @return The shared instance. Never returns null.
508 * @throws MasterNotRunningException
509 */
510 // TODO: Why is this in the public interface when the returned type is shutdown package access?
511 MasterMonitorKeepAliveConnection getKeepAliveMasterMonitorService()
512 throws MasterNotRunningException;
513
514 /**
515 * This function allows HBaseAdmin and potentially others to get a shared MasterAdminProtocol
516 * connection.
517 * @return The shared instance. Never returns null.
518 * @throws MasterNotRunningException
519 */
520 // TODO: Why is this in the public interface when the returned type is shutdown package access?
521 MasterAdminKeepAliveConnection getKeepAliveMasterAdminService() throws MasterNotRunningException;
522
523 /**
524 * @param serverName
525 * @return true if the server is known as dead, false otherwise.
526 */
527 boolean isDeadServer(ServerName serverName);
528 }