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