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 }