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   @Deprecated
202   boolean isTableEnabled(byte[] tableName) throws IOException;
203 
204   /**
205    * @param tableName table name
206    * @return true if the table is disabled, false otherwise
207    * @throws IOException if a remote or network exception occurs
208    */
209   boolean isTableDisabled(TableName tableName) throws IOException;
210 
211   @Deprecated
212   boolean isTableDisabled(byte[] tableName) throws IOException;
213 
214   /**
215    * Retrieve TableState, represent current table state.
216    * @param tableName table state for
217    * @return state of the table
218    */
219   public TableState getTableState(TableName tableName)  throws IOException;
220 
221   /**
222    * @param tableName table name
223    * @return true if all regions of the table are available, false otherwise
224    * @throws IOException if a remote or network exception occurs
225    */
226   boolean isTableAvailable(TableName tableName) throws IOException;
227 
228   @Deprecated
229   boolean isTableAvailable(byte[] tableName) throws IOException;
230 
231   /**
232    * Use this api to check if the table has been created with the specified number of
233    * splitkeys which was used while creating the given table.
234    * Note : If this api is used after a table's region gets splitted, the api may return
235    * false.
236    * @param tableName
237    *          tableName
238    * @param splitKeys
239    *          splitKeys used while creating table
240    * @throws IOException
241    *           if a remote or network exception occurs
242    * @deprecated internal method, do not use thru HConnection */
243   @Deprecated
244   boolean isTableAvailable(TableName tableName, byte[][] splitKeys) throws
245       IOException;
246 
247   @Deprecated
248   boolean isTableAvailable(byte[] tableName, byte[][] splitKeys) throws
249       IOException;
250 
251   /**
252    * List all the userspace tables.  In other words, scan the hbase:meta table.
253    *
254    * @return - returns an array of HTableDescriptors
255    * @throws IOException if a remote or network exception occurs
256    * @deprecated Use {@link Admin#listTables()} instead.
257    */
258   @Deprecated
259   HTableDescriptor[] listTables() throws IOException;
260 
261   // This is a bit ugly - We call this getTableNames in 0.94 and the
262   // successor function, returning TableName, listTableNames in later versions
263   // because Java polymorphism doesn't consider return value types
264 
265   /**
266    * @deprecated Use {@link Admin#listTableNames()} instead.
267    */
268   @Deprecated
269   String[] getTableNames() throws IOException;
270 
271   /**
272    * @deprecated Use {@link Admin#listTables()} instead.
273    */
274   @Deprecated
275   TableName[] listTableNames() throws IOException;
276 
277   /**
278    * @param tableName table name
279    * @return table metadata
280    * @throws IOException if a remote or network exception occurs
281    */
282   @Deprecated
283   HTableDescriptor getHTableDescriptor(TableName tableName)
284   throws IOException;
285 
286   @Deprecated
287   HTableDescriptor getHTableDescriptor(byte[] tableName)
288   throws IOException;
289 
290   /**
291    * Find the location of the region of <i>tableName</i> that <i>row</i>
292    * lives in.
293    * @param tableName name of the table <i>row</i> is in
294    * @param row row key you're trying to find the region of
295    * @return HRegionLocation that describes where to find the region in
296    * question
297    * @throws IOException if a remote or network exception occurs
298    * @deprecated internal method, do not use thru HConnection
299    */
300   @Deprecated
301   public HRegionLocation locateRegion(final TableName tableName,
302       final byte [] row) throws IOException;
303 
304   @Deprecated
305   public HRegionLocation locateRegion(final byte[] tableName,
306       final byte [] row) throws IOException;
307 
308   /**
309    * Allows flushing the region cache.
310    * @deprecated internal method, do not use thru HConnection */
311   @Deprecated
312   void clearRegionCache();
313 
314   /**
315    * Allows flushing the region cache of all locations that pertain to
316    * <code>tableName</code>
317    * @param tableName Name of the table whose regions we are to remove from
318    * cache.
319    * @deprecated internal method, do not use thru HConnection */
320   @Deprecated
321   void clearRegionCache(final TableName tableName);
322 
323   @Deprecated
324   void clearRegionCache(final byte[] tableName);
325 
326   /**
327    * Deletes cached locations for the specific region.
328    * @param location The location object for the region, to be purged from cache.
329    * @deprecated internal method, do not use thru HConnection */
330   @Deprecated
331   void deleteCachedRegionLocation(final HRegionLocation location);
332 
333   /**
334    * Find the location of the region of <i>tableName</i> that <i>row</i>
335    * lives in, ignoring any value that might be in the cache.
336    * @param tableName name of the table <i>row</i> is in
337    * @param row row key you're trying to find the region of
338    * @return HRegionLocation that describes where to find the region in
339    * question
340    * @throws IOException if a remote or network exception occurs
341    * @deprecated internal method, do not use thru HConnection */
342   @Deprecated
343   HRegionLocation relocateRegion(final TableName tableName,
344       final byte [] row) throws IOException;
345 
346   @Deprecated
347   HRegionLocation relocateRegion(final byte[] tableName,
348       final byte [] row) throws IOException;
349 
350   @Deprecated
351   void updateCachedLocations(TableName tableName, byte[] rowkey,
352                                     Object exception, HRegionLocation source);
353 
354   /**
355    * Update the location cache. This is used internally by HBase, in most cases it should not be
356    *  used by the client application.
357    * @param tableName the table name
358    * @param regionName the regionName
359    * @param rowkey the row
360    * @param exception the exception if any. Can be null.
361    * @param source the previous location
362    * @deprecated internal method, do not use thru HConnection
363    */
364   @Deprecated
365   void updateCachedLocations(TableName tableName, byte[] regionName, byte[] rowkey,
366                                     Object exception, ServerName source);
367 
368   @Deprecated
369   void updateCachedLocations(byte[] tableName, byte[] rowkey,
370                                     Object exception, HRegionLocation source);
371 
372   /**
373    * Gets the location of the region of <i>regionName</i>.
374    * @param regionName name of the region to locate
375    * @return HRegionLocation that describes where to find the region in
376    * question
377    * @throws IOException if a remote or network exception occurs
378    * @deprecated internal method, do not use thru HConnection */
379   @Deprecated
380   HRegionLocation locateRegion(final byte[] regionName)
381   throws IOException;
382 
383   /**
384    * Gets the locations of all regions in the specified table, <i>tableName</i>.
385    * @param tableName table to get regions of
386    * @return list of region locations for all regions of table
387    * @throws IOException
388    * @deprecated internal method, do not use thru HConnection */
389   @Deprecated
390   List<HRegionLocation> locateRegions(final TableName tableName) throws IOException;
391 
392   @Deprecated
393   List<HRegionLocation> locateRegions(final byte[] tableName) throws IOException;
394 
395   /**
396    * Gets the locations of all regions in the specified table, <i>tableName</i>.
397    * @param tableName table to get regions of
398    * @param useCache Should we use the cache to retrieve the region information.
399    * @param offlined True if we are to include offlined regions, false and we'll leave out offlined
400    *          regions from returned list.
401    * @return list of region locations for all regions of table
402    * @throws IOException
403    * @deprecated internal method, do not use thru HConnection
404    */
405   @Deprecated
406   public List<HRegionLocation> locateRegions(final TableName tableName,
407       final boolean useCache,
408       final boolean offlined) throws IOException;
409 
410   @Deprecated
411   public List<HRegionLocation> locateRegions(final byte[] tableName,
412       final boolean useCache,
413       final boolean offlined) throws IOException;
414 
415   /**
416    * Returns a {@link MasterKeepAliveConnection} to the active master
417    * @deprecated internal method, do not use thru HConnection */
418   @Deprecated
419   MasterService.BlockingInterface getMaster() throws IOException;
420 
421 
422   /**
423    * Establishes a connection to the region server at the specified address.
424    * @param serverName
425    * @return proxy for HRegionServer
426    * @throws IOException if a remote or network exception occurs
427    * @deprecated internal method, do not use thru HConnection */
428   @Deprecated
429   AdminService.BlockingInterface getAdmin(final ServerName serverName) throws IOException;
430 
431   /**
432    * Establishes a connection to the region server at the specified address, and returns
433    * a region client protocol.
434    *
435    * @param serverName
436    * @return ClientProtocol proxy for RegionServer
437    * @throws IOException if a remote or network exception occurs
438    * @deprecated internal method, do not use thru HConnection */
439   @Deprecated
440   ClientService.BlockingInterface getClient(final ServerName serverName) throws IOException;
441 
442   /**
443    * Establishes a connection to the region server at the specified address.
444    * @param serverName
445    * @param getMaster do we check if master is alive
446    * @return proxy for HRegionServer
447    * @throws IOException if a remote or network exception occurs
448    * @deprecated You can pass master flag but nothing special is done.
449    */
450   @Deprecated
451   AdminService.BlockingInterface getAdmin(final ServerName serverName, boolean getMaster)
452       throws IOException;
453 
454   /**
455    * Find region location hosting passed row
456    * @param tableName table name
457    * @param row Row to find.
458    * @param reload If true do not use cache, otherwise bypass.
459    * @return Location of row.
460    * @throws IOException if a remote or network exception occurs
461    * @deprecated internal method, do not use thru HConnection */
462   @Deprecated
463   HRegionLocation getRegionLocation(TableName tableName, byte [] row,
464     boolean reload)
465   throws IOException;
466 
467   @Deprecated
468   HRegionLocation getRegionLocation(byte[] tableName, byte [] row,
469     boolean reload)
470   throws IOException;
471 
472   /**
473    * Process a mixed batch of Get, Put and Delete actions. All actions for a
474    * RegionServer are forwarded in one RPC call.
475    *
476    *
477    * @param actions The collection of actions.
478    * @param tableName Name of the hbase table
479    * @param pool thread pool for parallel execution
480    * @param results An empty array, same size as list. If an exception is thrown,
481    * you can test here for partial results, and to determine which actions
482    * processed successfully.
483    * @throws IOException if there are problems talking to META. Per-item
484    * exceptions are stored in the results array.
485    * @deprecated since 0.96 - Use {@link HTableInterface#batch} instead
486    */
487   @Deprecated
488   void processBatch(List<? extends Row> actions, final TableName tableName,
489       ExecutorService pool, Object[] results) throws IOException, InterruptedException;
490 
491   @Deprecated
492   void processBatch(List<? extends Row> actions, final byte[] tableName,
493       ExecutorService pool, Object[] results) throws IOException, InterruptedException;
494 
495   /**
496    * Parameterized batch processing, allowing varying return types for different
497    * {@link Row} implementations.
498    * @deprecated since 0.96 - Use {@link HTableInterface#batchCallback} instead
499    */
500   @Deprecated
501   public <R> void processBatchCallback(List<? extends Row> list,
502       final TableName tableName,
503       ExecutorService pool,
504       Object[] results,
505       Batch.Callback<R> callback) throws IOException, InterruptedException;
506 
507   @Deprecated
508   public <R> void processBatchCallback(List<? extends Row> list,
509       final byte[] tableName,
510       ExecutorService pool,
511       Object[] results,
512       Batch.Callback<R> callback) throws IOException, InterruptedException;
513 
514   /**
515    * @deprecated does nothing since since 0.99
516    **/
517   @Deprecated
518   public void setRegionCachePrefetch(final TableName tableName,
519       final boolean enable);
520 
521   /**
522    * @deprecated does nothing since 0.99
523    **/
524   @Deprecated
525   public void setRegionCachePrefetch(final byte[] tableName,
526       final boolean enable);
527 
528   /**
529    * @deprecated always return false since 0.99
530    **/
531   @Deprecated
532   boolean getRegionCachePrefetch(final TableName tableName);
533 
534   /**
535    * @deprecated always return false since 0.99
536    **/
537   @Deprecated
538   boolean getRegionCachePrefetch(final byte[] tableName);
539 
540   /**
541    * @return the number of region servers that are currently running
542    * @throws IOException if a remote or network exception occurs
543    * @deprecated This method will be changed from public to package protected.
544    */
545   @Deprecated
546   int getCurrentNrHRS() throws IOException;
547 
548   /**
549    * @param tableNames List of table names
550    * @return HTD[] table metadata
551    * @throws IOException if a remote or network exception occurs
552    * @deprecated Use {@link Admin#getTableDescriptor(TableName)} instead.
553    */
554   @Deprecated
555   HTableDescriptor[] getHTableDescriptorsByTableName(List<TableName> tableNames) throws IOException;
556 
557   @Deprecated
558   HTableDescriptor[] getHTableDescriptors(List<String> tableNames) throws
559       IOException;
560 
561   /**
562    * @return true if this connection is closed
563    */
564   @Override
565   boolean isClosed();
566 
567 
568   /**
569    * Clear any caches that pertain to server name <code>sn</code>.
570    * @param sn A server name
571    * @deprecated internal method, do not use thru HConnection */
572   @Deprecated
573   void clearCaches(final ServerName sn);
574 
575   /**
576    * This function allows HBaseAdmin and potentially others to get a shared MasterService
577    * connection.
578    * @return The shared instance. Never returns null.
579    * @throws MasterNotRunningException
580    * @deprecated Since 0.96.0
581    */
582   // TODO: Why is this in the public interface when the returned type is shutdown package access?
583   @Deprecated
584   MasterKeepAliveConnection getKeepAliveMasterService()
585   throws MasterNotRunningException;
586 
587   /**
588    * @param serverName
589    * @return true if the server is known as dead, false otherwise.
590    * @deprecated internal method, do not use thru HConnection */
591   @Deprecated
592   boolean isDeadServer(ServerName serverName);
593 
594   /**
595    * @return Nonce generator for this HConnection; may be null if disabled in configuration.
596    * @deprecated internal method, do not use thru HConnection */
597   @Deprecated
598   public NonceGenerator getNonceGenerator();
599 }