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