View Javadoc

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 }