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