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