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