View Javadoc

1   /**
2    * Copyright 2010 The Apache Software Foundation
3    *
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *     http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing, software
15   * distributed under the License is distributed on an "AS IS" BASIS,
16   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17   * See the License for the specific language governing permissions and
18   * limitations under the License.
19   */
20  package org.apache.hadoop.hbase.client;
21  
22  import java.io.Closeable;
23  import java.io.IOException;
24  import java.util.List;
25  import java.util.Map;
26  import java.util.concurrent.ExecutorService;
27  
28  import org.apache.hadoop.conf.Configuration;
29  import org.apache.hadoop.hbase.Abortable;
30  import org.apache.hadoop.hbase.HRegionInfo;
31  import org.apache.hadoop.hbase.HRegionLocation;
32  import org.apache.hadoop.hbase.HServerAddress;
33  import org.apache.hadoop.hbase.HTableDescriptor;
34  import org.apache.hadoop.hbase.MasterNotRunningException;
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.ipc.CoprocessorProtocol;
39  import org.apache.hadoop.hbase.ipc.HMasterInterface;
40  import org.apache.hadoop.hbase.ipc.HRegionInterface;
41  import org.apache.hadoop.hbase.zookeeper.ZooKeeperWatcher;
42  
43  /**
44   * Cluster connection.  Hosts a connection to the ZooKeeper ensemble and
45   * thereafter into the HBase cluster.  Knows how to locate regions out on the cluster,
46   * keeps a cache of locations and then knows how to recalibrate after they move.
47   * {@link HConnectionManager} manages instances of this class.
48   *
49   * <p>HConnections are used by {@link HTable} mostly but also by
50   * {@link HBaseAdmin}, {@link CatalogTracker},
51   * and {@link ZooKeeperWatcher}.  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.  Sharing makes cleanup of
55   * HConnections awkward.  See {@link HConnectionManager} for cleanup
56   * discussion.
57   *
58   * @see HConnectionManager
59   */
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    /**
78     * @return proxy connection to master server for this instance
79     * @throws MasterNotRunningException if the master is not running
80     * @throws ZooKeeperConnectionException if unable to connect to zookeeper
81     * @deprecated Removed because it was a mistake exposing master in this
82     * interface (master is an implementation detail). Master functions are
83     * available from HConnection or HBaseAdmin, without having to use
84     * directly the master.
85     * Deprecated in HBase 0.94
86     */
87    @Deprecated
88    public HMasterInterface getMaster()
89    throws MasterNotRunningException, ZooKeeperConnectionException;
90  
91    /** @return - true if the master server is running */
92    public boolean isMasterRunning()
93    throws MasterNotRunningException, ZooKeeperConnectionException;
94  
95    /**
96     * A table that isTableEnabled == false and isTableDisabled == false
97     * is possible. This happens when a table has a lot of regions
98     * that must be processed.
99     * @param tableName table name
100    * @return true if the table is enabled, false otherwise
101    * @throws IOException if a remote or network exception occurs
102    */
103   public boolean isTableEnabled(byte[] tableName) throws IOException;
104 
105   /**
106    * @param tableName table name
107    * @return true if the table is disabled, false otherwise
108    * @throws IOException if a remote or network exception occurs
109    */
110   public boolean isTableDisabled(byte[] tableName) throws IOException;
111 
112   /**
113    * @param tableName table name
114    * @return true if all regions of the table are available, false otherwise
115    * @throws IOException if a remote or network exception occurs
116    */
117   public boolean isTableAvailable(byte[] tableName) 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    * Deletes cached locations for the specific region.
167    * @param location The location object for the region, to be purged from cache.
168    */
169   public void deleteCachedRegionLocation(final HRegionLocation location);
170 
171   /**
172    * Find the location of the region of <i>tableName</i> that <i>row</i>
173    * lives in, ignoring any value that might be in the cache.
174    * @param tableName name of the table <i>row</i> is in
175    * @param row row key you're trying to find the region of
176    * @return HRegionLocation that describes where to find the region in
177    * question
178    * @throws IOException if a remote or network exception occurs
179    */
180   public HRegionLocation relocateRegion(final byte [] tableName,
181       final byte [] row)
182   throws IOException;
183 
184   /**
185    * Gets the location of the region of <i>regionName</i>.
186    * @param regionName name of the region to locate
187    * @return HRegionLocation that describes where to find the region in
188    * question
189    * @throws IOException if a remote or network exception occurs
190    */
191   public HRegionLocation locateRegion(final byte [] regionName)
192   throws IOException;
193 
194   /**
195    * Gets the locations of all regions in the specified table, <i>tableName</i>.
196    * @param tableName table to get regions of
197    * @return list of region locations for all regions of table
198    * @throws IOException
199    */
200   public List<HRegionLocation> locateRegions(final byte[] tableName)
201       throws IOException;
202 
203   /**
204    * Gets the locations of all regions in the specified table, <i>tableName</i>.
205    * @param tableName table to get regions of
206    * @param useCache Should we use the cache to retrieve the region information.
207    * @param offlined True if we are to include offlined regions, false and we'll leave out offlined
208    *          regions from returned list.
209    * @return list of region locations for all regions of table
210    * @throws IOException
211    */
212   public List<HRegionLocation> locateRegions(final byte[] tableName, final boolean useCache,
213       final boolean offlined) throws IOException;
214 
215   /**
216    * Establishes a connection to the region server at the specified address.
217    * @param regionServer - the server to connect to
218    * @return proxy for HRegionServer
219    * @throws IOException if a remote or network exception occurs
220    * @deprecated Use {@link #getHRegionConnection(String, int)}
221    */
222   public HRegionInterface getHRegionConnection(HServerAddress regionServer)
223   throws IOException;
224 
225   /**
226    * Establishes a connection to the region server at the specified address.
227    * @param hostname RegionServer hostname
228    * @param port RegionServer port
229    * @return proxy for HRegionServer
230    * @throws IOException if a remote or network exception occurs
231    *
232    */
233   public HRegionInterface getHRegionConnection(final String hostname, final int port)
234   throws IOException;
235 
236   /**
237    * Establishes a connection to the region server at the specified address.
238    * @param regionServer - the server to connect to
239    * @param getMaster - do we check if master is alive
240    * @return proxy for HRegionServer
241    * @throws IOException if a remote or network exception occurs
242    * @deprecated Use {@link #getHRegionConnection(HServerAddress, boolean)}
243    */
244   public HRegionInterface getHRegionConnection(HServerAddress regionServer,
245      boolean getMaster)
246   throws IOException;
247 
248   /**
249    * Establishes a connection to the region server at the specified address.
250    * @param hostname RegionServer hostname
251    * @param port RegionServer port
252    * @param getMaster - do we check if master is alive
253    * @return proxy for HRegionServer
254    * @throws IOException if a remote or network exception occurs
255    */
256   public HRegionInterface getHRegionConnection(final String hostname,
257      final int port, boolean getMaster)
258   throws IOException;
259 
260   /**
261    * Find region location hosting passed row
262    * @param tableName table name
263    * @param row Row to find.
264    * @param reload If true do not use cache, otherwise bypass.
265    * @return Location of row.
266    * @throws IOException if a remote or network exception occurs
267    */
268   HRegionLocation getRegionLocation(byte [] tableName, byte [] row,
269     boolean reload)
270   throws IOException;
271 
272   /**
273    * Pass in a ServerCallable with your particular bit of logic defined and
274    * this method will manage the process of doing retries with timed waits
275    * and refinds of missing regions.
276    *
277    * @param <T> the type of the return value
278    * @param callable callable to run
279    * @return an object of type T
280    * @throws IOException if a remote or network exception occurs
281    * @throws RuntimeException other unspecified error
282    * @deprecated Use {@link HConnectionManager#withoutRetries(ServerCallable)}
283    */
284   public <T> T getRegionServerWithRetries(ServerCallable<T> callable)
285   throws IOException, RuntimeException;
286 
287   /**
288    * Pass in a ServerCallable with your particular bit of logic defined and
289    * this method will pass it to the defined region server.
290    * @param <T> the type of the return value
291    * @param callable callable to run
292    * @return an object of type T
293    * @throws IOException if a remote or network exception occurs
294    * @throws RuntimeException other unspecified error
295    * @deprecated Use {@link HConnectionManager#withoutRetries(ServerCallable)}
296    */
297   public <T> T getRegionServerWithoutRetries(ServerCallable<T> callable)
298   throws IOException, RuntimeException;
299 
300   /**
301    * Process a mixed batch of Get, Put and Delete actions. All actions for a
302    * RegionServer are forwarded in one RPC call.
303    *
304    *
305    * @param actions The collection of actions.
306    * @param tableName Name of the hbase table
307    * @param pool thread pool for parallel execution
308    * @param results An empty array, same size as list. If an exception is thrown,
309    * you can test here for partial results, and to determine which actions
310    * processed successfully.
311    * @throws IOException if there are problems talking to META. Per-item
312    * exceptions are stored in the results array.
313    */
314   public void processBatch(List<? extends Row> actions, final byte[] tableName,
315       ExecutorService pool, Object[] results)
316       throws IOException, InterruptedException;
317 
318   /**
319    * Parameterized batch processing, allowing varying return types for different
320    * {@link Row} implementations.
321    */
322   public <R> void processBatchCallback(List<? extends Row> list,
323       byte[] tableName,
324       ExecutorService pool,
325       Object[] results,
326       Batch.Callback<R> callback) throws IOException, InterruptedException;
327 
328 
329   /**
330    * Executes the given
331    * {@link org.apache.hadoop.hbase.client.coprocessor.Batch.Call}
332    * callable for each row in the given list and invokes
333    * {@link org.apache.hadoop.hbase.client.coprocessor.Batch.Callback#update(byte[], byte[], Object)}
334    * for each result returned.
335    *
336    * @param protocol the protocol interface being called
337    * @param rows a list of row keys for which the callable should be invoked
338    * @param tableName table name for the coprocessor invoked
339    * @param pool ExecutorService used to submit the calls per row
340    * @param call instance on which to invoke
341    * {@link org.apache.hadoop.hbase.client.coprocessor.Batch.Call#call(Object)}
342    * for each row
343    * @param callback instance on which to invoke
344    * {@link org.apache.hadoop.hbase.client.coprocessor.Batch.Callback#update(byte[], byte[], Object)}
345    * for each result
346    * @param <T> the protocol interface type
347    * @param <R> the callable's return type
348    * @throws IOException
349    */
350   public <T extends CoprocessorProtocol,R> void processExecs(
351       final Class<T> protocol,
352       List<byte[]> rows,
353       final byte[] tableName,
354       ExecutorService pool,
355       final Batch.Call<T,R> call,
356       final Batch.Callback<R> callback) throws IOException, Throwable;
357 
358   /**
359    * Enable or disable region cache prefetch for the table. It will be
360    * applied for the given table's all HTable instances within this
361    * connection. By default, the cache prefetch is enabled.
362    * @param tableName name of table to configure.
363    * @param enable Set to true to enable region cache prefetch.
364    */
365   public void setRegionCachePrefetch(final byte[] tableName,
366       final boolean enable);
367 
368   /**
369    * Check whether region cache prefetch is enabled or not.
370    * @param tableName name of table to check
371    * @return true if table's region cache prefetch is enabled. Otherwise
372    * it is disabled.
373    */
374   public boolean getRegionCachePrefetch(final byte[] tableName);
375 
376   /**
377    * Load the region map and warm up the global region cache for the table.
378    * @param tableName name of the table to perform region cache prewarm.
379    * @param regions a region map.
380    */
381   public void prewarmRegionCache(final byte[] tableName,
382       final Map<HRegionInfo, HServerAddress> regions);
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   public int getCurrentNrHRS() throws IOException;
391 
392   /**
393    * @param tableNames List of table names
394    * @return HTD[] table metadata
395    * @throws IOException if a remote or network exception occurs
396    */
397   public HTableDescriptor[] getHTableDescriptors(List<String> tableNames)
398   throws IOException;
399 
400   /**
401    * @return true if this connection is closed
402    */
403   public boolean isClosed();
404 
405   /**
406    * Clear any caches that pertain to server name <code>sn</code>
407    * @param sn A server name as hostname:port
408    */
409   public void clearCaches(final String sn);
410 }