View Javadoc

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