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