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.ipc;
21  
22  import java.io.IOException;
23  import java.net.ConnectException;
24  import java.util.List;
25  import java.util.NavigableSet;
26  
27  import org.apache.hadoop.hbase.Abortable;
28  import org.apache.hadoop.hbase.HRegionInfo;
29  import org.apache.hadoop.hbase.HServerInfo;
30  import org.apache.hadoop.hbase.NotServingRegionException;
31  import org.apache.hadoop.hbase.Stoppable;
32  import org.apache.hadoop.hbase.client.Delete;
33  import org.apache.hadoop.hbase.client.Get;
34  import org.apache.hadoop.hbase.client.Increment;
35  import org.apache.hadoop.hbase.client.MultiAction;
36  import org.apache.hadoop.hbase.client.MultiPut;
37  import org.apache.hadoop.hbase.client.MultiPutResponse;
38  import org.apache.hadoop.hbase.client.MultiResponse;
39  import org.apache.hadoop.hbase.client.Put;
40  import org.apache.hadoop.hbase.client.Result;
41  import org.apache.hadoop.hbase.client.Scan;
42  import org.apache.hadoop.hbase.regionserver.wal.HLog;
43  import org.apache.hadoop.ipc.RemoteException;
44  
45  /**
46   * Clients interact with HRegionServers using a handle to the HRegionInterface.
47   *
48   * <p>NOTE: if you change the interface, you must change the RPC version
49   * number in HBaseRPCProtocolVersion
50   */
51  public interface HRegionInterface extends HBaseRPCProtocolVersion, Stoppable, Abortable {
52    /**
53     * Get metainfo about an HRegion
54     *
55     * @param regionName name of the region
56     * @return HRegionInfo object for region
57     * @throws NotServingRegionException
58     * @throws ConnectException
59     * @throws IOException This can manifest as an Hadoop ipc {@link RemoteException}
60     */
61    public HRegionInfo getRegionInfo(final byte [] regionName)
62    throws NotServingRegionException, ConnectException, IOException;
63  
64    /**
65     * Return all the data for the row that matches <i>row</i> exactly,
66     * or the one that immediately preceeds it.
67     *
68     * @param regionName region name
69     * @param row row key
70     * @param family Column family to look for row in.
71     * @return map of values
72     * @throws IOException e
73     */
74    public Result getClosestRowBefore(final byte [] regionName,
75      final byte [] row, final byte [] family)
76    throws IOException;
77  
78    /**
79     * Perform Get operation.
80     * @param regionName name of region to get from
81     * @param get Get operation
82     * @return Result
83     * @throws IOException e
84     */
85    public Result get(byte [] regionName, Get get) throws IOException;
86  
87    /**
88     * Perform exists operation.
89     * @param regionName name of region to get from
90     * @param get Get operation describing cell to test
91     * @return true if exists
92     * @throws IOException e
93     */
94    public boolean exists(byte [] regionName, Get get) throws IOException;
95  
96    /**
97     * Put data into the specified region
98     * @param regionName region name
99     * @param put the data to be put
100    * @throws IOException e
101    */
102   public void put(final byte [] regionName, final Put put)
103   throws IOException;
104 
105   /**
106    * Put an array of puts into the specified region
107    *
108    * @param regionName region name
109    * @param puts List of puts to execute
110    * @return The number of processed put's.  Returns -1 if all Puts
111    * processed successfully.
112    * @throws IOException e
113    */
114   public int put(final byte[] regionName, final List<Put> puts)
115   throws IOException;
116 
117   /**
118    * Deletes all the KeyValues that match those found in the Delete object,
119    * if their ts <= to the Delete. In case of a delete with a specific ts it
120    * only deletes that specific KeyValue.
121    * @param regionName region name
122    * @param delete delete object
123    * @throws IOException e
124    */
125   public void delete(final byte[] regionName, final Delete delete)
126   throws IOException;
127 
128   /**
129    * Put an array of deletes into the specified region
130    *
131    * @param regionName region name
132    * @param deletes delete List to execute
133    * @return The number of processed deletes.  Returns -1 if all Deletes
134    * processed successfully.
135    * @throws IOException e
136    */
137   public int delete(final byte[] regionName, final List<Delete> deletes)
138   throws IOException;
139 
140   /**
141    * Atomically checks if a row/family/qualifier value match the expectedValue.
142    * If it does, it adds the put. If passed expected value is null, then the
143    * check is for non-existance of the row/column.
144    *
145    * @param regionName region name
146    * @param row row to check
147    * @param family column family
148    * @param qualifier column qualifier
149    * @param value the expected value
150    * @param put data to put if check succeeds
151    * @throws IOException e
152    * @return true if the new put was execute, false otherwise
153    */
154   public boolean checkAndPut(final byte[] regionName, final byte [] row,
155       final byte [] family, final byte [] qualifier, final byte [] value,
156       final Put put)
157   throws IOException;
158 
159 
160   /**
161    * Atomically checks if a row/family/qualifier value match the expectedValue.
162    * If it does, it adds the delete. If passed expected value is null, then the
163    * check is for non-existance of the row/column.
164    *
165    * @param regionName region name
166    * @param row row to check
167    * @param family column family
168    * @param qualifier column qualifier
169    * @param value the expected value
170    * @param delete data to delete if check succeeds
171    * @throws IOException e
172    * @return true if the new delete was execute, false otherwise
173    */
174   public boolean checkAndDelete(final byte[] regionName, final byte [] row,
175       final byte [] family, final byte [] qualifier, final byte [] value,
176       final Delete delete)
177   throws IOException;
178 
179   /**
180    * Atomically increments a column value. If the column value isn't long-like,
181    * this could throw an exception. If passed expected value is null, then the
182    * check is for non-existance of the row/column.
183    *
184    * @param regionName region name
185    * @param row row to check
186    * @param family column family
187    * @param qualifier column qualifier
188    * @param amount long amount to increment
189    * @param writeToWAL whether to write the increment to the WAL
190    * @return new incremented column value
191    * @throws IOException e
192    */
193   public long incrementColumnValue(byte [] regionName, byte [] row,
194       byte [] family, byte [] qualifier, long amount, boolean writeToWAL)
195   throws IOException;
196 
197   /**
198    * Increments one or more columns values in a row.  Returns the
199    * updated keys after the increment.
200    * <p>
201    * This operation does not appear atomic to readers.  Increments are done
202    * under a row lock but readers do not take row locks.
203    * @param regionName region name
204    * @param increment increment operation
205    * @return incremented cells
206    */
207   public Result increment(byte[] regionName, Increment increment)
208   throws IOException;
209 
210   //
211   // remote scanner interface
212   //
213 
214   /**
215    * Opens a remote scanner with a RowFilter.
216    *
217    * @param regionName name of region to scan
218    * @param scan configured scan object
219    * @return scannerId scanner identifier used in other calls
220    * @throws IOException e
221    */
222   public long openScanner(final byte [] regionName, final Scan scan)
223   throws IOException;
224 
225   /**
226    * Get the next set of values
227    * @param scannerId clientId passed to openScanner
228    * @return map of values; returns null if no results.
229    * @throws IOException e
230    */
231   public Result next(long scannerId) throws IOException;
232 
233   /**
234    * Get the next set of values
235    * @param scannerId clientId passed to openScanner
236    * @param numberOfRows the number of rows to fetch
237    * @return Array of Results (map of values); array is empty if done with this
238    * region and null if we are NOT to go to the next region (happens when a
239    * filter rules that the scan is done).
240    * @throws IOException e
241    */
242   public Result [] next(long scannerId, int numberOfRows) throws IOException;
243 
244   /**
245    * Close a scanner
246    *
247    * @param scannerId the scanner id returned by openScanner
248    * @throws IOException e
249    */
250   public void close(long scannerId) throws IOException;
251 
252   /**
253    * Opens a remote row lock.
254    *
255    * @param regionName name of region
256    * @param row row to lock
257    * @return lockId lock identifier
258    * @throws IOException e
259    */
260   public long lockRow(final byte [] regionName, final byte [] row)
261   throws IOException;
262 
263   /**
264    * Releases a remote row lock.
265    *
266    * @param regionName region name
267    * @param lockId the lock id returned by lockRow
268    * @throws IOException e
269    */
270   public void unlockRow(final byte [] regionName, final long lockId)
271   throws IOException;
272 
273 
274   /**
275    * @return All regions online on this region server
276    * @throws IOException e
277    */
278   public List<HRegionInfo> getOnlineRegions();
279 
280   /**
281    * Method used when a master is taking the place of another failed one.
282    * @return The HSI
283    * @throws IOException e
284    */
285   public HServerInfo getHServerInfo() throws IOException;
286 
287   /**
288    * Method used for doing multiple actions(Deletes, Gets and Puts) in one call
289    * @param multi
290    * @return MultiResult
291    * @throws IOException
292    */
293   public MultiResponse multi(MultiAction multi) throws IOException;
294 
295   /**
296    * Multi put for putting multiple regions worth of puts at once.
297    *
298    * @param puts the request
299    * @return the reply
300    * @throws IOException e
301    */
302   public MultiPutResponse multiPut(MultiPut puts) throws IOException;
303 
304   /**
305    * Bulk load an HFile into an open region
306    */
307   public void bulkLoadHFile(String hfilePath, byte[] regionName, byte[] familyName)
308   throws IOException;
309 
310   // Master methods
311 
312   /**
313    * Opens the specified region.
314    * @param region region to open
315    * @throws IOException
316    */
317   public void openRegion(final HRegionInfo region) throws IOException;
318 
319   /**
320    * Opens the specified regions.
321    * @param regions regions to open
322    * @throws IOException
323    */
324   public void openRegions(final List<HRegionInfo> regions) throws IOException;
325 
326   /**
327    * Closes the specified region.
328    * @param region region to close
329    * @return true if closing region, false if not
330    * @throws IOException
331    */
332   public boolean closeRegion(final HRegionInfo region)
333   throws IOException;
334 
335   /**
336    * Closes the specified region and will use or not use ZK during the close
337    * according to the specified flag.
338    * @param region region to close
339    * @param zk true if transitions should be done in ZK, false if not
340    * @return true if closing region, false if not
341    * @throws IOException
342    */
343   public boolean closeRegion(final HRegionInfo region, final boolean zk)
344   throws IOException;
345 
346   // Region administrative methods
347 
348   /**
349    * Flushes the MemStore of the specified region.
350    * <p>
351    * This method is synchronous.
352    * @param regionInfo region to flush
353    * @throws NotServingRegionException
354    * @throws IOException
355    */
356   void flushRegion(HRegionInfo regionInfo)
357   throws NotServingRegionException, IOException;
358 
359   /**
360    * Splits the specified region.
361    * <p>
362    * This method currently flushes the region and then forces a compaction which
363    * will then trigger a split.  The flush is done synchronously but the
364    * compaction is asynchronous.
365    * @param regionInfo region to split
366    * @throws NotServingRegionException
367    * @throws IOException
368    */
369   void splitRegion(HRegionInfo regionInfo)
370   throws NotServingRegionException, IOException;
371 
372   /**
373    * Splits the specified region.
374    * <p>
375    * This method currently flushes the region and then forces a compaction which
376    * will then trigger a split.  The flush is done synchronously but the
377    * compaction is asynchronous.
378    * @param regionInfo region to split
379    * @param splitPoint the explicit row to split on
380    * @throws NotServingRegionException
381    * @throws IOException
382    */
383   void splitRegion(HRegionInfo regionInfo, byte[] splitPoint)
384   throws NotServingRegionException, IOException;
385 
386   /**
387    * Compacts the specified region.  Performs a major compaction if specified.
388    * <p>
389    * This method is asynchronous.
390    * @param regionInfo region to compact
391    * @param major true to force major compaction
392    * @throws NotServingRegionException
393    * @throws IOException
394    */
395   void compactRegion(HRegionInfo regionInfo, boolean major)
396   throws NotServingRegionException, IOException;
397 
398   /**
399    * Replicates the given entries. The guarantee is that the given entries
400    * will be durable on the slave cluster if this method returns without
401    * any exception.
402    * hbase.replication has to be set to true for this to work.
403    *
404    * @param entries entries to replicate
405    * @throws IOException
406    */
407   public void replicateLogEntries(HLog.Entry[] entries) throws IOException;
408 }