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