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