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