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