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