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