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.IOException;
23  import java.util.List;
24  import java.util.Map;
25  import java.util.concurrent.ExecutorService;
26  
27  import org.apache.hadoop.conf.Configuration;
28  import org.apache.hadoop.hbase.Abortable;
29  import org.apache.hadoop.hbase.HRegionInfo;
30  import org.apache.hadoop.hbase.HRegionLocation;
31  import org.apache.hadoop.hbase.HServerAddress;
32  import org.apache.hadoop.hbase.HTableDescriptor;
33  import org.apache.hadoop.hbase.MasterNotRunningException;
34  import org.apache.hadoop.hbase.ZooKeeperConnectionException;
35  import org.apache.hadoop.hbase.catalog.CatalogTracker;
36  import org.apache.hadoop.hbase.ipc.HMasterInterface;
37  import org.apache.hadoop.hbase.ipc.HRegionInterface;
38  import org.apache.hadoop.hbase.zookeeper.ZooKeeperWatcher;
39  
40  /**
41   * Cluster connection.  Hosts a connection to the ZooKeeper ensemble and
42   * thereafter into the HBase cluster.  Knows how to locate regions out on the cluster,
43   * keeps a cache of locations and then knows how to recalibrate after they move.
44   * {@link HConnectionManager} manages instances of this class.
45   *
46   * <p>HConnections are used by {@link HTable} mostly but also by
47   * {@link HBaseAdmin}, {@link CatalogTracker},
48   * and {@link ZooKeeperWatcher}.  HConnection instances can be shared.  Sharing
49   * is usually what you want because rather than each HConnection instance
50   * having to do its own discovery of regions out on the cluster, instead, all
51   * clients get to share the one cache of locations.  Sharing makes cleanup of
52   * HConnections awkward.  See {@link HConnectionManager} for cleanup
53   * discussion.
54   *
55   * @see HConnectionManager
56   */
57  public interface HConnection extends Abortable {
58    /**
59     * @return Configuration instance being used by this HConnection instance.
60     */
61    public Configuration getConfiguration();
62  
63    /**
64     * Retrieve ZooKeeperWatcher used by this connection.
65     * @return ZooKeeperWatcher handle being used by the connection.
66     * @throws IOException if a remote or network exception occurs
67     */
68    public ZooKeeperWatcher getZooKeeperWatcher() throws IOException;
69  
70    /**
71     * @return proxy connection to master server for this instance
72     * @throws MasterNotRunningException if the master is not running
73     * @throws ZooKeeperConnectionException if unable to connect to zookeeper
74     */
75    public HMasterInterface getMaster()
76    throws MasterNotRunningException, ZooKeeperConnectionException;
77  
78    /** @return - true if the master server is running */
79    public boolean isMasterRunning()
80    throws MasterNotRunningException, ZooKeeperConnectionException;
81  
82    /**
83     * A table that isTableEnabled == false and isTableDisabled == false
84     * is possible. This happens when a table has a lot of regions
85     * that must be processed.
86     * @param tableName table name
87     * @return true if the table is enabled, false otherwise
88     * @throws IOException if a remote or network exception occurs
89     */
90    public boolean isTableEnabled(byte[] tableName) throws IOException;
91  
92    /**
93     * @param tableName table name
94     * @return true if the table is disabled, false otherwise
95     * @throws IOException if a remote or network exception occurs
96     */
97    public boolean isTableDisabled(byte[] tableName) throws IOException;
98  
99    /**
100    * @param tableName table name
101    * @return true if all regions of the table are available, false otherwise
102    * @throws IOException if a remote or network exception occurs
103    */
104   public boolean isTableAvailable(byte[] tableName) throws IOException;
105 
106   /**
107    * List all the userspace tables.  In other words, scan the META table.
108    *
109    * If we wanted this to be really fast, we could implement a special
110    * catalog table that just contains table names and their descriptors.
111    * Right now, it only exists as part of the META table's region info.
112    *
113    * @return - returns an array of HTableDescriptors
114    * @throws IOException if a remote or network exception occurs
115    */
116   public HTableDescriptor[] listTables() throws IOException;
117 
118   /**
119    * @param tableName table name
120    * @return table metadata
121    * @throws IOException if a remote or network exception occurs
122    */
123   public HTableDescriptor getHTableDescriptor(byte[] tableName)
124   throws IOException;
125 
126   /**
127    * Find the location of the region of <i>tableName</i> that <i>row</i>
128    * lives in.
129    * @param tableName name of the table <i>row</i> is in
130    * @param row row key you're trying to find the region of
131    * @return HRegionLocation that describes where to find the region in
132    * question
133    * @throws IOException if a remote or network exception occurs
134    */
135   public HRegionLocation locateRegion(final byte [] tableName,
136       final byte [] row)
137   throws IOException;
138 
139   /**
140    * Allows flushing the region cache.
141    */
142   public void clearRegionCache();
143 
144   /**
145    * Allows flushing the region cache of all locations that pertain to
146    * <code>tableName</code>
147    * @param tableName Name of the table whose regions we are to remove from
148    * cache.
149    */
150   public void clearRegionCache(final byte [] tableName);
151 
152   /**
153    * Find the location of the region of <i>tableName</i> that <i>row</i>
154    * lives in, ignoring any value that might be in the cache.
155    * @param tableName name of the table <i>row</i> is in
156    * @param row row key you're trying to find the region of
157    * @return HRegionLocation that describes where to find the region in
158    * question
159    * @throws IOException if a remote or network exception occurs
160    */
161   public HRegionLocation relocateRegion(final byte [] tableName,
162       final byte [] row)
163   throws IOException;
164 
165   /**
166    * Gets the location of the region of <i>regionName</i>.
167    * @param regionName name of the region to locate
168    * @return HRegionLocation that describes where to find the region in
169    * question
170    * @throws IOException if a remote or network exception occurs
171    */
172   public HRegionLocation locateRegion(final byte [] regionName)
173   throws IOException;
174 
175   /**
176    * Gets the locations of all regions in the specified table, <i>tableName</i>.
177    * @param tableName table to get regions of
178    * @return list of region locations for all regions of table
179    * @throws IOException
180    */
181   public List<HRegionLocation> locateRegions(byte[] tableName)
182   throws IOException;
183 
184   /**
185    * Establishes a connection to the region server at the specified address.
186    * @param regionServer - the server to connect to
187    * @return proxy for HRegionServer
188    * @throws IOException if a remote or network exception occurs
189    */
190   public HRegionInterface getHRegionConnection(HServerAddress regionServer)
191   throws IOException;
192 
193   /**
194    * Establishes a connection to the region server at the specified address.
195    * @param regionServer - the server to connect to
196    * @param getMaster - do we check if master is alive
197    * @return proxy for HRegionServer
198    * @throws IOException if a remote or network exception occurs
199    */
200   public HRegionInterface getHRegionConnection(
201       HServerAddress regionServer, boolean getMaster)
202   throws IOException;
203 
204   /**
205    * Find region location hosting passed row
206    * @param tableName table name
207    * @param row Row to find.
208    * @param reload If true do not use cache, otherwise bypass.
209    * @return Location of row.
210    * @throws IOException if a remote or network exception occurs
211    */
212   HRegionLocation getRegionLocation(byte [] tableName, byte [] row,
213     boolean reload)
214   throws IOException;
215 
216   /**
217    * Pass in a ServerCallable with your particular bit of logic defined and
218    * this method will manage the process of doing retries with timed waits
219    * and refinds of missing regions.
220    *
221    * @param <T> the type of the return value
222    * @param callable callable to run
223    * @return an object of type T
224    * @throws IOException if a remote or network exception occurs
225    * @throws RuntimeException other unspecified error
226    */
227   public <T> T getRegionServerWithRetries(ServerCallable<T> callable)
228   throws IOException, RuntimeException;
229 
230   /**
231    * Pass in a ServerCallable with your particular bit of logic defined and
232    * this method will pass it to the defined region server.
233    * @param <T> the type of the return value
234    * @param callable callable to run
235    * @return an object of type T
236    * @throws IOException if a remote or network exception occurs
237    * @throws RuntimeException other unspecified error
238    */
239   public <T> T getRegionServerWithoutRetries(ServerCallable<T> callable)
240   throws IOException, RuntimeException;
241 
242   /**
243    * Process a mixed batch of Get, Put and Delete actions. All actions for a
244    * RegionServer are forwarded in one RPC call.
245    *
246    *
247    * @param actions The collection of actions.
248    * @param tableName Name of the hbase table
249    * @param pool thread pool for parallel execution
250    * @param results An empty array, same size as list. If an exception is thrown,
251    * you can test here for partial results, and to determine which actions
252    * processed successfully.
253    * @throws IOException if there are problems talking to META. Per-item
254    * exceptions are stored in the results array.
255    */
256   public void processBatch(List<Row> actions, final byte[] tableName,
257       ExecutorService pool, Object[] results)
258       throws IOException, InterruptedException;
259 
260   /**
261    * Process a batch of Puts.
262    *
263    * @param list The collection of actions. The list is mutated: all successful Puts
264    * are removed from the list.
265    * @param tableName Name of the hbase table
266    * @param pool Thread pool for parallel execution
267    * @throws IOException
268    * @deprecated Use HConnectionManager::processBatch instead.
269    */
270   public void processBatchOfPuts(List<Put> list,
271                                  final byte[] tableName, ExecutorService pool)
272       throws IOException;
273 
274   /**
275    * Enable or disable region cache prefetch for the table. It will be
276    * applied for the given table's all HTable instances within this
277    * connection. By default, the cache prefetch is enabled.
278    * @param tableName name of table to configure.
279    * @param enable Set to true to enable region cache prefetch.
280    */
281   public void setRegionCachePrefetch(final byte[] tableName,
282       final boolean enable);
283 
284   /**
285    * Check whether region cache prefetch is enabled or not.
286    * @param tableName name of table to check
287    * @return true if table's region cache prefetch is enabled. Otherwise
288    * it is disabled.
289    */
290   public boolean getRegionCachePrefetch(final byte[] tableName);
291 
292   /**
293    * Load the region map and warm up the global region cache for the table.
294    * @param tableName name of the table to perform region cache prewarm.
295    * @param regions a region map.
296    */
297   public void prewarmRegionCache(final byte[] tableName,
298       final Map<HRegionInfo, HServerAddress> regions);
299 }