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 org.apache.hadoop.classification.InterfaceAudience;
22  import org.apache.hadoop.classification.InterfaceStability;
23  import org.apache.hadoop.conf.Configuration;
24  import org.apache.hadoop.hbase.Abortable;
25  import org.apache.hadoop.hbase.HRegionLocation;
26  import org.apache.hadoop.hbase.HTableDescriptor;
27  import org.apache.hadoop.hbase.MasterAdminProtocol;
28  import org.apache.hadoop.hbase.MasterMonitorProtocol;
29  import org.apache.hadoop.hbase.ServerName;
30  import org.apache.hadoop.hbase.catalog.CatalogTracker;
31  import org.apache.hadoop.hbase.client.coprocessor.Batch;
32  import org.apache.hadoop.hbase.exceptions.MasterNotRunningException;
33  import org.apache.hadoop.hbase.exceptions.ZooKeeperConnectionException;
34  import org.apache.hadoop.hbase.zookeeper.ZooKeeperWatcher;
35  
36  import java.io.Closeable;
37  import java.io.IOException;
38  import java.util.List;
39  import java.util.concurrent.ExecutorService;
40  
41  /**
42   * Cluster connection.  Hosts a connection to the ZooKeeper ensemble and
43   * thereafter into the HBase cluster.  Knows how to locate regions out on the cluster,
44   * keeps a cache of locations and then knows how to recalibrate after they move.
45   * {@link HConnectionManager} manages instances of this class.
46   *
47   * <p>HConnections are used by {@link HTable} mostly but also by
48   * {@link HBaseAdmin}, {@link CatalogTracker},
49   * and {@link ZooKeeperWatcher}.  HConnection instances can be shared.  Sharing
50   * is usually what you want because rather than each HConnection instance
51   * having to do its own discovery of regions out on the cluster, instead, all
52   * clients get to share the one cache of locations.  Sharing makes cleanup of
53   * HConnections awkward.  See {@link HConnectionManager} for cleanup
54   * discussion.
55   *
56   * @see HConnectionManager
57   */
58  @InterfaceAudience.Public
59  @InterfaceStability.Stable
60  public interface HConnection extends Abortable, Closeable {
61    /**
62     * @return Configuration instance being used by this HConnection instance.
63     */
64    public Configuration getConfiguration();
65  
66    /**
67     * Retrieve ZooKeeperWatcher used by this connection.
68     * @return ZooKeeperWatcher handle being used by the connection.
69     * @throws IOException if a remote or network exception occurs
70     * @deprecated Removed because it was a mistake exposing zookeeper in this
71     * interface (ZooKeeper is an implementation detail).
72     * Deprecated in HBase 0.94
73     */
74    @Deprecated
75    public ZooKeeperWatcher getZooKeeperWatcher() throws IOException;
76  
77    /** @return - true if the master server is running */
78    public boolean isMasterRunning()
79    throws MasterNotRunningException, ZooKeeperConnectionException;
80  
81    /**
82     * A table that isTableEnabled == false and isTableDisabled == false
83     * is possible. This happens when a table has a lot of regions
84     * that must be processed.
85     * @param tableName table name
86     * @return true if the table is enabled, false otherwise
87     * @throws IOException if a remote or network exception occurs
88     */
89    public boolean isTableEnabled(byte[] tableName) throws IOException;
90  
91    /**
92     * @param tableName table name
93     * @return true if the table is disabled, false otherwise
94     * @throws IOException if a remote or network exception occurs
95     */
96    public boolean isTableDisabled(byte[] tableName) throws IOException;
97  
98    /**
99     * @param tableName table name
100    * @return true if all regions of the table are available, false otherwise
101    * @throws IOException if a remote or network exception occurs
102    */
103   public boolean isTableAvailable(byte[] tableName) throws IOException;
104   
105   /**
106    * Use this api to check if the table has been created with the specified number of 
107    * splitkeys which was used while creating the given table.
108    * Note : If this api is used after a table's region gets splitted, the api may return
109    * false.
110    * @param tableName
111    *          tableName
112    * @param splitKeys
113    *          splitKeys used while creating table
114    * @throws IOException
115    *           if a remote or network exception occurs
116    */
117   public boolean isTableAvailable(byte[] tableName, byte[][] splitKeys) throws IOException;
118 
119   /**
120    * List all the userspace tables.  In other words, scan the META table.
121    *
122    * If we wanted this to be really fast, we could implement a special
123    * catalog table that just contains table names and their descriptors.
124    * Right now, it only exists as part of the META table's region info.
125    *
126    * @return - returns an array of HTableDescriptors
127    * @throws IOException if a remote or network exception occurs
128    */
129   public HTableDescriptor[] listTables() throws IOException;
130 
131   /**
132    * @param tableName table name
133    * @return table metadata
134    * @throws IOException if a remote or network exception occurs
135    */
136   public HTableDescriptor getHTableDescriptor(byte[] tableName)
137   throws IOException;
138 
139   /**
140    * Find the location of the region of <i>tableName</i> that <i>row</i>
141    * lives in.
142    * @param tableName name of the table <i>row</i> is in
143    * @param row row key you're trying to find the region of
144    * @return HRegionLocation that describes where to find the region in
145    * question
146    * @throws IOException if a remote or network exception occurs
147    */
148   public HRegionLocation locateRegion(final byte [] tableName,
149       final byte [] row)
150   throws IOException;
151 
152   /**
153    * Allows flushing the region cache.
154    */
155   public void clearRegionCache();
156 
157   /**
158    * Allows flushing the region cache of all locations that pertain to
159    * <code>tableName</code>
160    * @param tableName Name of the table whose regions we are to remove from
161    * cache.
162    */
163   public void clearRegionCache(final byte [] tableName);
164 
165   /**
166    * Find the location of the region of <i>tableName</i> that <i>row</i>
167    * lives in, ignoring any value that might be in the cache.
168    * @param tableName name of the table <i>row</i> is in
169    * @param row row key you're trying to find the region of
170    * @return HRegionLocation that describes where to find the region in
171    * question
172    * @throws IOException if a remote or network exception occurs
173    */
174   public HRegionLocation relocateRegion(final byte [] tableName,
175       final byte [] row)
176   throws IOException;
177 
178   /**
179    * Gets the location of the region of <i>regionName</i>.
180    * @param regionName name of the region to locate
181    * @return HRegionLocation that describes where to find the region in
182    * question
183    * @throws IOException if a remote or network exception occurs
184    */
185   public HRegionLocation locateRegion(final byte [] regionName)
186   throws IOException;
187 
188   /**
189    * Gets the locations of all regions in the specified table, <i>tableName</i>.
190    * @param tableName table to get regions of
191    * @return list of region locations for all regions of table
192    * @throws IOException
193    */
194   public List<HRegionLocation> locateRegions(final byte[] tableName)
195   throws IOException;
196   
197   /**
198    * Gets the locations of all regions in the specified table, <i>tableName</i>.
199    * @param tableName table to get regions of
200    * @param useCache Should we use the cache to retrieve the region information.
201    * @param offlined True if we are to include offlined regions, false and we'll leave out offlined
202    *          regions from returned list.
203    * @return list of region locations for all regions of table
204    * @throws IOException
205    */
206   public List<HRegionLocation> locateRegions(final byte[] tableName, final boolean useCache,
207       final boolean offlined) throws IOException;
208 
209   /**
210    * Returns a {@link MasterAdminProtocol} to the active master
211    */
212   public MasterAdminProtocol getMasterAdmin() throws IOException;
213 
214   /**
215    * Returns an {@link MasterMonitorProtocol} to the active master
216    */
217   public MasterMonitorProtocol getMasterMonitor() throws IOException;
218 
219 
220   /**
221    * Establishes a connection to the region server at the specified address.
222    * @param hostname RegionServer hostname
223    * @param port RegionServer port
224    * @return proxy for HRegionServer
225    * @throws IOException if a remote or network exception occurs
226    * @deprecated - use @link {#getAdmin(final ServerName serverName)} which takes into account
227    *  the startCode
228    */
229   @Deprecated
230   public AdminProtocol getAdmin(final String hostname, final int port)
231   throws IOException;
232 
233 
234   /**
235    * Establishes a connection to the region server at the specified address.
236    * @param serverName
237    * @return proxy for HRegionServer
238    * @throws IOException if a remote or network exception occurs
239    */
240   public AdminProtocol getAdmin(final ServerName serverName)
241       throws IOException;
242 
243   /**
244    * Establishes a connection to the region server at the specified address, and return
245    * a region client protocol.
246    *
247    * @param hostname RegionServer hostname
248    * @param port RegionServer port
249    * @return ClientProtocol proxy for RegionServer
250    * @throws IOException if a remote or network exception occurs
251    * @deprecated - use @link {#getClient(final ServerName serverName)} which takes into account
252    *  the startCode
253    */
254   @Deprecated
255   public ClientProtocol getClient(final String hostname, final int port)
256   throws IOException;
257 
258 
259   /**
260    * Establishes a connection to the region server at the specified address, and return
261    * a region client protocol.
262    *
263    * @param serverName
264    * @return ClientProtocol proxy for RegionServer
265    * @throws IOException if a remote or network exception occurs
266    *
267    */
268   public ClientProtocol getClient(final ServerName serverName) throws IOException;
269 
270   /**
271    * Establishes a connection to the region server at the specified address.
272    * @param hostname RegionServer hostname
273    * @param port RegionServer port
274    * @param getMaster - do we check if master is alive
275    * @return proxy for HRegionServer
276    * @throws IOException if a remote or network exception occurs
277    * @deprecated use @link {#getAdmin(final ServerName serverName, boolean getMaster)}
278    * which takes into account the startCode.
279    */
280   @Deprecated
281   public AdminProtocol getAdmin(final String hostname, final int port, boolean getMaster)
282   throws IOException;
283 
284   /**
285    * Establishes a connection to the region server at the specified address.
286    * @param serverName
287    * @param getMaster - do we check if master is alive
288    * @return proxy for HRegionServer
289    * @throws IOException if a remote or network exception occurs
290    */
291   public AdminProtocol getAdmin(final ServerName serverName, boolean getMaster)
292       throws IOException;
293 
294   /**
295    * Find region location hosting passed row
296    * @param tableName table name
297    * @param row Row to find.
298    * @param reload If true do not use cache, otherwise bypass.
299    * @return Location of row.
300    * @throws IOException if a remote or network exception occurs
301    */
302   HRegionLocation getRegionLocation(byte [] tableName, byte [] row,
303     boolean reload)
304   throws IOException;
305 
306   /**
307    * Pass in a ServerCallable with your particular bit of logic defined and
308    * this method will manage the process of doing retries with timed waits
309    * and refinds of missing regions.
310    *
311    * @param <T> the type of the return value
312    * @param callable callable to run
313    * @return an object of type T
314    * @throws IOException if a remote or network exception occurs
315    * @throws RuntimeException other unspecified error
316    */
317   @Deprecated
318   public <T> T getRegionServerWithRetries(ServerCallable<T> callable)
319   throws IOException, RuntimeException;
320 
321   /**
322    * Pass in a ServerCallable with your particular bit of logic defined and
323    * this method will pass it to the defined region server.
324    * @param <T> the type of the return value
325    * @param callable callable to run
326    * @return an object of type T
327    * @throws IOException if a remote or network exception occurs
328    * @throws RuntimeException other unspecified error
329    */
330   @Deprecated
331   public <T> T getRegionServerWithoutRetries(ServerCallable<T> callable)
332   throws IOException, RuntimeException;
333 
334   /**
335    * Process a mixed batch of Get, Put and Delete actions. All actions for a
336    * RegionServer are forwarded in one RPC call.
337    *
338    *
339    * @param actions The collection of actions.
340    * @param tableName Name of the hbase table
341    * @param pool thread pool for parallel execution
342    * @param results An empty array, same size as list. If an exception is thrown,
343    * you can test here for partial results, and to determine which actions
344    * processed successfully.
345    * @throws IOException if there are problems talking to META. Per-item
346    * exceptions are stored in the results array.
347    * @deprecated since 0.96 - Use {@link HTableInterface#batch} instead
348    */
349   @Deprecated
350   public void processBatch(List<? extends Row> actions, final byte[] tableName,
351       ExecutorService pool, Object[] results)
352       throws IOException, InterruptedException;
353 
354   /**
355    * Parameterized batch processing, allowing varying return types for different
356    * {@link Row} implementations.
357    * @deprecated since 0.96 - Use {@link HTableInterface#batchCallback} instead
358    */
359   @Deprecated
360   public <R> void processBatchCallback(List<? extends Row> list,
361       byte[] tableName,
362       ExecutorService pool,
363       Object[] results,
364       Batch.Callback<R> callback) throws IOException, InterruptedException;
365 
366   /**
367    * Enable or disable region cache prefetch for the table. It will be
368    * applied for the given table's all HTable instances within this
369    * connection. By default, the cache prefetch is enabled.
370    * @param tableName name of table to configure.
371    * @param enable Set to true to enable region cache prefetch.
372    */
373   public void setRegionCachePrefetch(final byte[] tableName,
374       final boolean enable);
375 
376   /**
377    * Check whether region cache prefetch is enabled or not.
378    * @param tableName name of table to check
379    * @return true if table's region cache prefetch is enabled. Otherwise
380    * it is disabled.
381    */
382   public boolean getRegionCachePrefetch(final byte[] tableName);
383 
384   /**
385    * Scan zookeeper to get the number of region servers
386    * @return the number of region servers that are currently running
387    * @throws IOException if a remote or network exception occurs
388    * @deprecated This method will be changed from public to package protected.
389    */
390   @Deprecated
391   public int getCurrentNrHRS() throws IOException;
392 
393   /**
394    * @param tableNames List of table names
395    * @return HTD[] table metadata
396    * @throws IOException if a remote or network exception occurs
397    */
398   public HTableDescriptor[] getHTableDescriptors(List<String> tableNames)
399   throws IOException;
400 
401   /**
402    * @return true if this connection is closed
403    */
404   public boolean isClosed();
405 
406 
407   /**
408    * Clear any caches that pertain to server name <code>sn</code>
409    * @param sn A server name
410    */
411   public void clearCaches(final ServerName sn);
412 
413   /**
414    * This function allows HBaseAdminProtocol and potentially others to get a shared MasterMonitor
415    * connection.
416    * @return The shared instance. Never returns null.
417    * @throws MasterNotRunningException
418    */
419   public MasterMonitorKeepAliveConnection getKeepAliveMasterMonitor()
420       throws MasterNotRunningException;
421 
422   /**
423    * This function allows HBaseAdmin and potentially others to get a shared MasterAdminProtocol
424    * connection.
425    * @return The shared instance. Never returns null.
426    * @throws MasterNotRunningException
427    */
428   public MasterAdminKeepAliveConnection getKeepAliveMasterAdmin() throws MasterNotRunningException;
429 
430   /**
431    * @param serverName
432    * @return true if the server is known as dead, false otherwise.
433    */
434   public boolean isDeadServer(ServerName serverName);
435 }
436