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 an HTableInterface implementation for access to a table.
68     * The returned HTableInterface is not thread safe, a new instance should
69     * be created for each using thread.
70     * This is a lightweight operation, pooling or caching of the returned HTableInterface
71     * is neither required nor desired.
72     * Note that the HConnection needs to be unmanaged
73     * (created with {@link HConnectionManager#createConnection(Configuration)}).
74     * @param tableName
75     * @return an HTable to use for interactions with this table
76     */
77    public HTableInterface getTable(String tableName) throws IOException;
78  
79    /**
80     * Retrieve an HTableInterface implementation for access to a table.
81     * The returned HTableInterface is not thread safe, a new instance should
82     * be created for each using thread.
83     * This is a lightweight operation, pooling or caching of the returned HTableInterface
84     * is neither required nor desired.
85     * Note that the HConnection needs to be unmanaged
86     * (created with {@link HConnectionManager#createConnection(Configuration)}).
87     * @param tableName
88     * @return an HTable to use for interactions with this table
89     */
90    public HTableInterface getTable(byte[] tableName) throws IOException;
91  
92    /**
93     * Retrieve an HTableInterface implementation for access to a table.
94     * The returned HTableInterface is not thread safe, a new instance should
95     * be created for each using thread.
96     * This is a lightweight operation, pooling or caching of the returned HTableInterface
97     * is neither required nor desired.
98     * Note that the HConnection needs to be unmanaged
99     * (created with {@link HConnectionManager#createConnection(Configuration)}).
100    * @param tableName
101    * @param pool The thread pool to use for batch operations, null to use a default pool.
102    * @return an HTable to use for interactions with this table
103    */
104   public HTableInterface getTable(String tableName, ExecutorService pool)  throws IOException;
105 
106   /**
107    * Retrieve an HTableInterface implementation for access to a table.
108    * The returned HTableInterface is not thread safe, a new instance should
109    * be created for each using thread.
110    * This is a lightweight operation, pooling or caching of the returned HTableInterface
111    * is neither required nor desired.
112    * Note that the HConnection needs to be unmanaged
113    * (created with {@link HConnectionManager#createConnection(Configuration)}).
114    * @param tableName
115    * @param pool The thread pool to use for batch operations, null to use a default pool.
116    * @return an HTable to use for interactions with this table
117    */
118   public HTableInterface getTable(byte[] tableName, ExecutorService pool)  throws IOException;
119 
120   /**
121    * Retrieve ZooKeeperWatcher used by this connection.
122    * @return ZooKeeperWatcher handle being used by the connection.
123    * @throws IOException if a remote or network exception occurs
124    * @deprecated Removed because it was a mistake exposing zookeeper in this
125    * interface (ZooKeeper is an implementation detail).
126    * Deprecated in HBase 0.94
127    */
128   @Deprecated
129   public ZooKeeperWatcher getZooKeeperWatcher() throws IOException;
130 
131   /**
132    * @return proxy connection to master server for this instance
133    * @throws MasterNotRunningException if the master is not running
134    * @throws ZooKeeperConnectionException if unable to connect to zookeeper
135    * @deprecated Removed because it was a mistake exposing master in this
136    * interface (master is an implementation detail). Master functions are
137    * available from HConnection or HBaseAdmin, without having to use
138    * directly the master.
139    * Deprecated in HBase 0.94
140    */
141   @Deprecated
142   public HMasterInterface getMaster()
143   throws MasterNotRunningException, ZooKeeperConnectionException;
144 
145   /** @return - true if the master server is running */
146   public boolean isMasterRunning()
147   throws MasterNotRunningException, ZooKeeperConnectionException;
148 
149   /**
150    * A table that isTableEnabled == false and isTableDisabled == false
151    * is possible. This happens when a table has a lot of regions
152    * that must be processed.
153    * @param tableName table name
154    * @return true if the table is enabled, false otherwise
155    * @throws IOException if a remote or network exception occurs
156    */
157   public boolean isTableEnabled(byte[] tableName) throws IOException;
158 
159   /**
160    * @param tableName table name
161    * @return true if the table is disabled, false otherwise
162    * @throws IOException if a remote or network exception occurs
163    */
164   public boolean isTableDisabled(byte[] tableName) throws IOException;
165 
166   /**
167    * @param tableName table name
168    * @return true if all regions of the table are available, false otherwise
169    * @throws IOException if a remote or network exception occurs
170    */
171   public boolean isTableAvailable(byte[] tableName) throws IOException;
172 
173   /**
174    * List all the userspace tables.  In other words, scan the META table.
175    *
176    * If we wanted this to be really fast, we could implement a special
177    * catalog table that just contains table names and their descriptors.
178    * Right now, it only exists as part of the META table's region info.
179    *
180    * @return - returns an array of HTableDescriptors
181    * @throws IOException if a remote or network exception occurs
182    */
183   public HTableDescriptor[] listTables() throws IOException;
184 
185   /**
186    * @param tableName table name
187    * @return table metadata
188    * @throws IOException if a remote or network exception occurs
189    */
190   public HTableDescriptor getHTableDescriptor(byte[] tableName)
191   throws IOException;
192 
193   /**
194    * Find the location of the region of <i>tableName</i> that <i>row</i>
195    * lives in.
196    * @param tableName name of the table <i>row</i> is in
197    * @param row row key you're trying to find the region of
198    * @return HRegionLocation that describes where to find the region in
199    * question
200    * @throws IOException if a remote or network exception occurs
201    */
202   public HRegionLocation locateRegion(final byte [] tableName,
203       final byte [] row)
204   throws IOException;
205 
206   /**
207    * Allows flushing the region cache.
208    */
209   public void clearRegionCache();
210 
211   /**
212    * Allows flushing the region cache of all locations that pertain to
213    * <code>tableName</code>
214    * @param tableName Name of the table whose regions we are to remove from
215    * cache.
216    */
217   public void clearRegionCache(final byte [] tableName);
218 
219   /**
220    * Deletes cached locations for the specific region.
221    * @param location The location object for the region, to be purged from cache.
222    */
223   public void deleteCachedRegionLocation(final HRegionLocation location);
224 
225   /**
226    * Find the location of the region of <i>tableName</i> that <i>row</i>
227    * lives in, ignoring any value that might be in the cache.
228    * @param tableName name of the table <i>row</i> is in
229    * @param row row key you're trying to find the region of
230    * @return HRegionLocation that describes where to find the region in
231    * question
232    * @throws IOException if a remote or network exception occurs
233    */
234   public HRegionLocation relocateRegion(final byte [] tableName,
235       final byte [] row)
236   throws IOException;
237 
238   /**
239    * Gets the location of the region of <i>regionName</i>.
240    * @param regionName name of the region to locate
241    * @return HRegionLocation that describes where to find the region in
242    * question
243    * @throws IOException if a remote or network exception occurs
244    */
245   public HRegionLocation locateRegion(final byte [] regionName)
246   throws IOException;
247 
248   /**
249    * Gets the locations of all regions in the specified table, <i>tableName</i>.
250    * @param tableName table to get regions of
251    * @return list of region locations for all regions of table
252    * @throws IOException
253    */
254   public List<HRegionLocation> locateRegions(final byte[] tableName)
255       throws IOException;
256 
257   /**
258    * Gets the locations of all regions in the specified table, <i>tableName</i>.
259    * @param tableName table to get regions of
260    * @param useCache Should we use the cache to retrieve the region information.
261    * @param offlined True if we are to include offlined regions, false and we'll leave out offlined
262    *          regions from returned list.
263    * @return list of region locations for all regions of table
264    * @throws IOException
265    */
266   public List<HRegionLocation> locateRegions(final byte[] tableName, final boolean useCache,
267       final boolean offlined) throws IOException;
268 
269   /**
270    * Establishes a connection to the region server at the specified address.
271    * @param regionServer - the server to connect to
272    * @return proxy for HRegionServer
273    * @throws IOException if a remote or network exception occurs
274    * @deprecated Use {@link #getHRegionConnection(String, int)}
275    */
276   public HRegionInterface getHRegionConnection(HServerAddress regionServer)
277   throws IOException;
278 
279   /**
280    * Establishes a connection to the region server at the specified address.
281    * @param hostname RegionServer hostname
282    * @param port RegionServer port
283    * @return proxy for HRegionServer
284    * @throws IOException if a remote or network exception occurs
285    *
286    */
287   public HRegionInterface getHRegionConnection(final String hostname, final int port)
288   throws IOException;
289 
290   /**
291    * Establishes a connection to the region server at the specified address.
292    * @param regionServer - the server to connect to
293    * @param getMaster - do we check if master is alive
294    * @return proxy for HRegionServer
295    * @throws IOException if a remote or network exception occurs
296    * @deprecated Use {@link #getHRegionConnection(HServerAddress, boolean)}
297    */
298   public HRegionInterface getHRegionConnection(HServerAddress regionServer,
299      boolean getMaster)
300   throws IOException;
301 
302   /**
303    * Establishes a connection to the region server at the specified address.
304    * @param hostname RegionServer hostname
305    * @param port RegionServer port
306    * @param getMaster - do we check if master is alive
307    * @return proxy for HRegionServer
308    * @throws IOException if a remote or network exception occurs
309    */
310   public HRegionInterface getHRegionConnection(final String hostname,
311      final int port, boolean getMaster)
312   throws IOException;
313 
314   /**
315    * Find region location hosting passed row
316    * @param tableName table name
317    * @param row Row to find.
318    * @param reload If true do not use cache, otherwise bypass.
319    * @return Location of row.
320    * @throws IOException if a remote or network exception occurs
321    */
322   HRegionLocation getRegionLocation(byte [] tableName, byte [] row,
323     boolean reload)
324   throws IOException;
325 
326   /**
327    * Pass in a ServerCallable with your particular bit of logic defined and
328    * this method will manage the process of doing retries with timed waits
329    * and refinds of missing regions.
330    *
331    * @param <T> the type of the return value
332    * @param callable callable to run
333    * @return an object of type T
334    * @throws IOException if a remote or network exception occurs
335    * @throws RuntimeException other unspecified error
336    * @deprecated Use {@link HConnectionManager#withoutRetries(ServerCallable)}
337    */
338   public <T> T getRegionServerWithRetries(ServerCallable<T> callable)
339   throws IOException, RuntimeException;
340 
341   /**
342    * Pass in a ServerCallable with your particular bit of logic defined and
343    * this method will pass it to the defined region server.
344    * @param <T> the type of the return value
345    * @param callable callable to run
346    * @return an object of type T
347    * @throws IOException if a remote or network exception occurs
348    * @throws RuntimeException other unspecified error
349    * @deprecated Use {@link HConnectionManager#withoutRetries(ServerCallable)}
350    */
351   public <T> T getRegionServerWithoutRetries(ServerCallable<T> callable)
352   throws IOException, RuntimeException;
353 
354   /**
355    * Process a mixed batch of Get, Put and Delete actions. All actions for a
356    * RegionServer are forwarded in one RPC call.
357    *
358    *
359    * @param actions The collection of actions.
360    * @param tableName Name of the hbase table
361    * @param pool thread pool for parallel execution
362    * @param results An empty array, same size as list. If an exception is thrown,
363    * you can test here for partial results, and to determine which actions
364    * processed successfully.
365    * @throws IOException if there are problems talking to META. Per-item
366    * exceptions are stored in the results array.
367    */
368   public void processBatch(List<? extends Row> actions, final byte[] tableName,
369       ExecutorService pool, Object[] results)
370       throws IOException, InterruptedException;
371 
372   /**
373    * Parameterized batch processing, allowing varying return types for different
374    * {@link Row} implementations.
375    */
376   public <R> void processBatchCallback(List<? extends Row> list,
377       byte[] tableName,
378       ExecutorService pool,
379       Object[] results,
380       Batch.Callback<R> callback) throws IOException, InterruptedException;
381 
382 
383   /**
384    * Executes the given
385    * {@link org.apache.hadoop.hbase.client.coprocessor.Batch.Call}
386    * callable for each row in the given list and invokes
387    * {@link org.apache.hadoop.hbase.client.coprocessor.Batch.Callback#update(byte[], byte[], Object)}
388    * for each result returned.
389    *
390    * @param protocol the protocol interface being called
391    * @param rows a list of row keys for which the callable should be invoked
392    * @param tableName table name for the coprocessor invoked
393    * @param pool ExecutorService used to submit the calls per row
394    * @param call instance on which to invoke
395    * {@link org.apache.hadoop.hbase.client.coprocessor.Batch.Call#call(Object)}
396    * for each row
397    * @param callback instance on which to invoke
398    * {@link org.apache.hadoop.hbase.client.coprocessor.Batch.Callback#update(byte[], byte[], Object)}
399    * for each result
400    * @param <T> the protocol interface type
401    * @param <R> the callable's return type
402    * @throws IOException
403    */
404   public <T extends CoprocessorProtocol,R> void processExecs(
405       final Class<T> protocol,
406       List<byte[]> rows,
407       final byte[] tableName,
408       ExecutorService pool,
409       final Batch.Call<T,R> call,
410       final Batch.Callback<R> callback) throws IOException, Throwable;
411 
412   /**
413    * Enable or disable region cache prefetch for the table. It will be
414    * applied for the given table's all HTable instances within this
415    * connection. By default, the cache prefetch is enabled.
416    * @param tableName name of table to configure.
417    * @param enable Set to true to enable region cache prefetch.
418    */
419   public void setRegionCachePrefetch(final byte[] tableName,
420       final boolean enable);
421 
422   /**
423    * Check whether region cache prefetch is enabled or not.
424    * @param tableName name of table to check
425    * @return true if table's region cache prefetch is enabled. Otherwise
426    * it is disabled.
427    */
428   public boolean getRegionCachePrefetch(final byte[] tableName);
429 
430   /**
431    * Load the region map and warm up the global region cache for the table.
432    * @param tableName name of the table to perform region cache prewarm.
433    * @param regions a region map.
434    */
435   public void prewarmRegionCache(final byte[] tableName,
436       final Map<HRegionInfo, HServerAddress> regions);
437 
438   /**
439    * Scan zookeeper to get the number of region servers
440    * @return the number of region servers that are currently running
441    * @throws IOException if a remote or network exception occurs
442    * @deprecated This method will be changed from public to package protected.
443    */
444   public int getCurrentNrHRS() throws IOException;
445 
446   /**
447    * @param tableNames List of table names
448    * @return HTD[] table metadata
449    * @throws IOException if a remote or network exception occurs
450    */
451   public HTableDescriptor[] getHTableDescriptors(List<String> tableNames)
452   throws IOException;
453 
454   /**
455    * @return string[] table names
456    * @throws IOException if a remote or network exception occurs
457    */
458   public String[] getTableNames() throws IOException;
459 
460   /**
461    * @return true if this connection is closed
462    */
463   public boolean isClosed();
464 
465   /**
466    * Clear any caches that pertain to server name <code>sn</code>
467    * @param sn A server name as hostname:port
468    */
469   public void clearCaches(final String sn);
470 }