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     */
73    public ZooKeeperWatcher getZooKeeperWatcher() throws IOException;
74  
75    /**
76     * @return proxy connection to master server for this instance
77     * @throws MasterNotRunningException if the master is not running
78     * @throws ZooKeeperConnectionException if unable to connect to zookeeper
79     */
80    public HMasterInterface getMaster()
81    throws MasterNotRunningException, ZooKeeperConnectionException;
82  
83    /** @return - true if the master server is running */
84    public boolean isMasterRunning()
85    throws MasterNotRunningException, ZooKeeperConnectionException;
86  
87    /**
88     * A table that isTableEnabled == false and isTableDisabled == false
89     * is possible. This happens when a table has a lot of regions
90     * that must be processed.
91     * @param tableName table name
92     * @return true if the table is enabled, false otherwise
93     * @throws IOException if a remote or network exception occurs
94     */
95    public boolean isTableEnabled(byte[] tableName) throws IOException;
96  
97    /**
98     * @param tableName table name
99     * @return true if the table is disabled, false otherwise
100    * @throws IOException if a remote or network exception occurs
101    */
102   public boolean isTableDisabled(byte[] tableName) throws IOException;
103 
104   /**
105    * @param tableName table name
106    * @return true if all regions of the table are available, false otherwise
107    * @throws IOException if a remote or network exception occurs
108    */
109   public boolean isTableAvailable(byte[] tableName) throws IOException;
110 
111   /**
112    * List all the userspace tables.  In other words, scan the META table.
113    *
114    * If we wanted this to be really fast, we could implement a special
115    * catalog table that just contains table names and their descriptors.
116    * Right now, it only exists as part of the META table's region info.
117    *
118    * @return - returns an array of HTableDescriptors
119    * @throws IOException if a remote or network exception occurs
120    */
121   public HTableDescriptor[] listTables() throws IOException;
122 
123   /**
124    * @param tableName table name
125    * @return table metadata
126    * @throws IOException if a remote or network exception occurs
127    */
128   public HTableDescriptor getHTableDescriptor(byte[] tableName)
129   throws IOException;
130 
131   /**
132    * Find the location of the region of <i>tableName</i> that <i>row</i>
133    * lives in.
134    * @param tableName name of the table <i>row</i> is in
135    * @param row row key you're trying to find the region of
136    * @return HRegionLocation that describes where to find the region in
137    * question
138    * @throws IOException if a remote or network exception occurs
139    */
140   public HRegionLocation locateRegion(final byte [] tableName,
141       final byte [] row)
142   throws IOException;
143 
144   /**
145    * Allows flushing the region cache.
146    */
147   public void clearRegionCache();
148 
149   /**
150    * Allows flushing the region cache of all locations that pertain to
151    * <code>tableName</code>
152    * @param tableName Name of the table whose regions we are to remove from
153    * cache.
154    */
155   public void clearRegionCache(final byte [] tableName);
156 
157   /**
158    * Find the location of the region of <i>tableName</i> that <i>row</i>
159    * lives in, ignoring any value that might be in the cache.
160    * @param tableName name of the table <i>row</i> is in
161    * @param row row key you're trying to find the region of
162    * @return HRegionLocation that describes where to find the region in
163    * question
164    * @throws IOException if a remote or network exception occurs
165    */
166   public HRegionLocation relocateRegion(final byte [] tableName,
167       final byte [] row)
168   throws IOException;
169 
170   /**
171    * Gets the location of the region of <i>regionName</i>.
172    * @param regionName name of the region to locate
173    * @return HRegionLocation that describes where to find the region in
174    * question
175    * @throws IOException if a remote or network exception occurs
176    */
177   public HRegionLocation locateRegion(final byte [] regionName)
178   throws IOException;
179 
180   /**
181    * Gets the locations of all regions in the specified table, <i>tableName</i>.
182    * @param tableName table to get regions of
183    * @return list of region locations for all regions of table
184    * @throws IOException
185    */
186   public List<HRegionLocation> locateRegions(byte[] tableName)
187   throws IOException;
188 
189   /**
190    * Establishes a connection to the region server at the specified address.
191    * @param regionServer - the server to connect to
192    * @return proxy for HRegionServer
193    * @throws IOException if a remote or network exception occurs
194    * @deprecated Use {@link #getHRegionConnection(String, int)}
195    */
196   public HRegionInterface getHRegionConnection(HServerAddress regionServer)
197   throws IOException;
198 
199   /**
200    * Establishes a connection to the region server at the specified address.
201    * @param hostname RegionServer hostname
202    * @param port RegionServer port
203    * @return proxy for HRegionServer
204    * @throws IOException if a remote or network exception occurs
205    *
206    */
207   public HRegionInterface getHRegionConnection(final String hostname, final int port)
208   throws IOException;
209 
210   /**
211    * Establishes a connection to the region server at the specified address.
212    * @param regionServer - the server to connect to
213    * @param getMaster - do we check if master is alive
214    * @return proxy for HRegionServer
215    * @throws IOException if a remote or network exception occurs
216    * @deprecated Use {@link #getHRegionConnection(HServerAddress, boolean)}
217    */
218   public HRegionInterface getHRegionConnection(HServerAddress regionServer,
219      boolean getMaster)
220   throws IOException;
221 
222   /**
223    * Establishes a connection to the region server at the specified address.
224    * @param hostname RegionServer hostname
225    * @param port RegionServer port
226    * @param getMaster - do we check if master is alive
227    * @return proxy for HRegionServer
228    * @throws IOException if a remote or network exception occurs
229    */
230   public HRegionInterface getHRegionConnection(final String hostname,
231      final int port, boolean getMaster)
232   throws IOException;
233 
234   /**
235    * Find region location hosting passed row
236    * @param tableName table name
237    * @param row Row to find.
238    * @param reload If true do not use cache, otherwise bypass.
239    * @return Location of row.
240    * @throws IOException if a remote or network exception occurs
241    */
242   HRegionLocation getRegionLocation(byte [] tableName, byte [] row,
243     boolean reload)
244   throws IOException;
245 
246   /**
247    * Pass in a ServerCallable with your particular bit of logic defined and
248    * this method will manage the process of doing retries with timed waits
249    * and refinds of missing regions.
250    *
251    * @param <T> the type of the return value
252    * @param callable callable to run
253    * @return an object of type T
254    * @throws IOException if a remote or network exception occurs
255    * @throws RuntimeException other unspecified error
256    */
257   public <T> T getRegionServerWithRetries(ServerCallable<T> callable)
258   throws IOException, RuntimeException;
259 
260   /**
261    * Pass in a ServerCallable with your particular bit of logic defined and
262    * this method will pass it to the defined region server.
263    * @param <T> the type of the return value
264    * @param callable callable to run
265    * @return an object of type T
266    * @throws IOException if a remote or network exception occurs
267    * @throws RuntimeException other unspecified error
268    */
269   public <T> T getRegionServerWithoutRetries(ServerCallable<T> callable)
270   throws IOException, RuntimeException;
271 
272   /**
273    * Process a mixed batch of Get, Put and Delete actions. All actions for a
274    * RegionServer are forwarded in one RPC call.
275    *
276    *
277    * @param actions The collection of actions.
278    * @param tableName Name of the hbase table
279    * @param pool thread pool for parallel execution
280    * @param results An empty array, same size as list. If an exception is thrown,
281    * you can test here for partial results, and to determine which actions
282    * processed successfully.
283    * @throws IOException if there are problems talking to META. Per-item
284    * exceptions are stored in the results array.
285    */
286   public void processBatch(List<? extends Row> actions, final byte[] tableName,
287       ExecutorService pool, Object[] results)
288       throws IOException, InterruptedException;
289 
290   /**
291    * Parameterized batch processing, allowing varying return types for different
292    * {@link Row} implementations.
293    */
294   public <R> void processBatchCallback(List<? extends Row> list,
295       byte[] tableName,
296       ExecutorService pool,
297       Object[] results,
298       Batch.Callback<R> callback) throws IOException, InterruptedException;
299 
300 
301   /**
302    * Executes the given
303    * {@link org.apache.hadoop.hbase.client.coprocessor.Batch.Call}
304    * callable for each row in the given list and invokes
305    * {@link org.apache.hadoop.hbase.client.coprocessor.Batch.Callback#update(byte[], byte[], Object)}
306    * for each result returned.
307    *
308    * @param protocol the protocol interface being called
309    * @param rows a list of row keys for which the callable should be invoked
310    * @param tableName table name for the coprocessor invoked
311    * @param pool ExecutorService used to submit the calls per row
312    * @param call instance on which to invoke
313    * {@link org.apache.hadoop.hbase.client.coprocessor.Batch.Call#call(Object)}
314    * for each row
315    * @param callback instance on which to invoke
316    * {@link org.apache.hadoop.hbase.client.coprocessor.Batch.Callback#update(byte[], byte[], Object)}
317    * for each result
318    * @param <T> the protocol interface type
319    * @param <R> the callable's return type
320    * @throws IOException
321    */
322   public <T extends CoprocessorProtocol,R> void processExecs(
323       final Class<T> protocol,
324       List<byte[]> rows,
325       final byte[] tableName,
326       ExecutorService pool,
327       final Batch.Call<T,R> call,
328       final Batch.Callback<R> callback) throws IOException, Throwable;
329 
330   /**
331    * Enable or disable region cache prefetch for the table. It will be
332    * applied for the given table's all HTable instances within this
333    * connection. By default, the cache prefetch is enabled.
334    * @param tableName name of table to configure.
335    * @param enable Set to true to enable region cache prefetch.
336    */
337   public void setRegionCachePrefetch(final byte[] tableName,
338       final boolean enable);
339 
340   /**
341    * Check whether region cache prefetch is enabled or not.
342    * @param tableName name of table to check
343    * @return true if table's region cache prefetch is enabled. Otherwise
344    * it is disabled.
345    */
346   public boolean getRegionCachePrefetch(final byte[] tableName);
347 
348   /**
349    * Load the region map and warm up the global region cache for the table.
350    * @param tableName name of the table to perform region cache prewarm.
351    * @param regions a region map.
352    */
353   public void prewarmRegionCache(final byte[] tableName,
354       final Map<HRegionInfo, HServerAddress> regions);
355 
356   /**
357    * Scan zookeeper to get the number of region servers
358    * @return the number of region servers that are currently running
359    * @throws IOException if a remote or network exception occurs
360    * @deprecated This method will be changed from public to package protected.
361    */
362   public int getCurrentNrHRS() throws IOException;
363 
364   /**
365    * @param tableNames List of table names
366    * @return HTD[] table metadata
367    * @throws IOException if a remote or network exception occurs
368    */
369   public HTableDescriptor[] getHTableDescriptors(List<String> tableNames)
370   throws IOException;
371 
372   /**
373    * @return true if this connection is closed
374    */
375   public boolean isClosed();
376 }