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