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 org.apache.hadoop.hbase.HRegionInfo;
23  import org.apache.hadoop.hbase.HServerInfo;
24  import org.apache.hadoop.hbase.NotServingRegionException;
25  import org.apache.hadoop.hbase.client.Delete;
26  import org.apache.hadoop.hbase.client.Get;
27  import org.apache.hadoop.hbase.client.MultiPut;
28  import org.apache.hadoop.hbase.client.MultiPutResponse;
29  import org.apache.hadoop.hbase.client.Put;
30  import org.apache.hadoop.hbase.client.Result;
31  import org.apache.hadoop.hbase.client.Scan;
32  import org.apache.hadoop.hbase.regionserver.HRegion;
33  import org.apache.hadoop.hbase.regionserver.wal.HLog;
34  
35  import java.io.IOException;
36  import java.util.List;
37  
38  /**
39   * Clients interact with HRegionServers using a handle to the HRegionInterface.
40   *
41   * <p>NOTE: if you change the interface, you must change the RPC version
42   * number in HBaseRPCProtocolVersion
43   */
44  public interface HRegionInterface extends HBaseRPCProtocolVersion {
45    /**
46     * Get metainfo about an HRegion
47     *
48     * @param regionName name of the region
49     * @return HRegionInfo object for region
50     * @throws NotServingRegionException e
51     */
52    public HRegionInfo getRegionInfo(final byte [] regionName)
53    throws NotServingRegionException;
54  
55  
56    /**
57     * Return all the data for the row that matches <i>row</i> exactly,
58     * or the one that immediately preceeds it.
59     *
60     * @param regionName region name
61     * @param row row key
62     * @param family Column family to look for row in.
63     * @return map of values
64     * @throws IOException e
65     */
66    public Result getClosestRowBefore(final byte [] regionName,
67      final byte [] row, final byte [] family)
68    throws IOException;
69  
70    /**
71     *
72     * @return the regions served by this regionserver
73     */
74    public HRegion [] getOnlineRegionsAsArray();
75  
76    /**
77     * Perform Get operation.
78     * @param regionName name of region to get from
79     * @param get Get operation
80     * @return Result
81     * @throws IOException e
82     */
83    public Result get(byte [] regionName, Get get) throws IOException;
84  
85    /**
86     * Perform exists operation.
87     * @param regionName name of region to get from
88     * @param get Get operation describing cell to test
89     * @return true if exists
90     * @throws IOException e
91     */
92    public boolean exists(byte [] regionName, Get get) throws IOException;
93  
94    /**
95     * Put data into the specified region
96     * @param regionName region name
97     * @param put the data to be put
98     * @throws IOException e
99     */
100   public void put(final byte [] regionName, final Put put)
101   throws IOException;
102 
103   /**
104    * Put an array of puts into the specified region
105    *
106    * @param regionName region name
107    * @param puts List of puts to execute
108    * @return The number of processed put's.  Returns -1 if all Puts
109    * processed successfully.
110    * @throws IOException e
111    */
112   public int put(final byte[] regionName, final List<Put> puts)
113   throws IOException;
114 
115   /**
116    * Deletes all the KeyValues that match those found in the Delete object,
117    * if their ts <= to the Delete. In case of a delete with a specific ts it
118    * only deletes that specific KeyValue.
119    * @param regionName region name
120    * @param delete delete object
121    * @throws IOException e
122    */
123   public void delete(final byte[] regionName, final Delete delete)
124   throws IOException;
125 
126   /**
127    * Put an array of deletes into the specified region
128    *
129    * @param regionName region name
130    * @param deletes delete List to execute
131    * @return The number of processed deletes.  Returns -1 if all Deletes
132    * processed successfully.
133    * @throws IOException e
134    */
135   public int delete(final byte[] regionName, final List<Delete> deletes)
136   throws IOException;
137 
138   /**
139    * Atomically checks if a row/family/qualifier value match the expectedValue.
140    * If it does, it adds the put. If passed expected value is null, then the
141    * check is for non-existance of the row/column.
142    *
143    * @param regionName region name
144    * @param row row to check
145    * @param family column family
146    * @param qualifier column qualifier
147    * @param value the expected value
148    * @param put data to put if check succeeds
149    * @throws IOException e
150    * @return true if the new put was execute, false otherwise
151    */
152   public boolean checkAndPut(final byte[] regionName, final byte [] row,
153       final byte [] family, final byte [] qualifier, final byte [] value,
154       final Put put)
155   throws IOException;
156 
157 
158   /**
159    * Atomically checks if a row/family/qualifier value match the expectedValue.
160    * If it does, it adds the delete. If passed expected value is null, then the
161    * check is for non-existance of the row/column.
162    *
163    * @param regionName region name
164    * @param row row to check
165    * @param family column family
166    * @param qualifier column qualifier
167    * @param value the expected value
168    * @param delete data to delete if check succeeds
169    * @throws IOException e
170    * @return true if the new delete was execute, false otherwise
171    */
172   public boolean checkAndDelete(final byte[] regionName, final byte [] row,
173       final byte [] family, final byte [] qualifier, final byte [] value,
174       final Delete delete)
175   throws IOException;
176 
177   /**
178    * Atomically increments a column value. If the column value isn't long-like,
179    * this could throw an exception. If passed expected value is null, then the
180    * check is for non-existance of the row/column.
181    *
182    * @param regionName region name
183    * @param row row to check
184    * @param family column family
185    * @param qualifier column qualifier
186    * @param amount long amount to increment
187    * @param writeToWAL whether to write the increment to the WAL
188    * @return new incremented column value
189    * @throws IOException e
190    */
191   public long incrementColumnValue(byte [] regionName, byte [] row,
192       byte [] family, byte [] qualifier, long amount, boolean writeToWAL)
193   throws IOException;
194 
195 
196   //
197   // remote scanner interface
198   //
199 
200   /**
201    * Opens a remote scanner with a RowFilter.
202    *
203    * @param regionName name of region to scan
204    * @param scan configured scan object
205    * @return scannerId scanner identifier used in other calls
206    * @throws IOException e
207    */
208   public long openScanner(final byte [] regionName, final Scan scan)
209   throws IOException;
210 
211   /**
212    * Get the next set of values
213    * @param scannerId clientId passed to openScanner
214    * @return map of values; returns null if no results.
215    * @throws IOException e
216    */
217   public Result next(long scannerId) throws IOException;
218 
219   /**
220    * Get the next set of values
221    * @param scannerId clientId passed to openScanner
222    * @param numberOfRows the number of rows to fetch
223    * @return Array of Results (map of values); array is empty if done with this
224    * region and null if we are NOT to go to the next region (happens when a
225    * filter rules that the scan is done).
226    * @throws IOException e
227    */
228   public Result [] next(long scannerId, int numberOfRows) throws IOException;
229 
230   /**
231    * Close a scanner
232    *
233    * @param scannerId the scanner id returned by openScanner
234    * @throws IOException e
235    */
236   public void close(long scannerId) throws IOException;
237 
238   /**
239    * Opens a remote row lock.
240    *
241    * @param regionName name of region
242    * @param row row to lock
243    * @return lockId lock identifier
244    * @throws IOException e
245    */
246   public long lockRow(final byte [] regionName, final byte [] row)
247   throws IOException;
248 
249   /**
250    * Releases a remote row lock.
251    *
252    * @param regionName region name
253    * @param lockId the lock id returned by lockRow
254    * @throws IOException e
255    */
256   public void unlockRow(final byte [] regionName, final long lockId)
257   throws IOException;
258 
259 
260   /**
261    * Method used when a master is taking the place of another failed one.
262    * @return All regions assigned on this region server
263    * @throws IOException e
264    */
265   public HRegionInfo[] getRegionsAssignment() throws IOException;
266 
267   /**
268    * Method used when a master is taking the place of another failed one.
269    * @return The HSI
270    * @throws IOException e
271    */
272   public HServerInfo getHServerInfo() throws IOException;
273 
274 
275   /**
276    * Multi put for putting multiple regions worth of puts at once.
277    *
278    * @param puts the request
279    * @return the reply
280    * @throws IOException e
281    */
282   public MultiPutResponse multiPut(MultiPut puts) throws IOException;
283 
284   /**
285    * Bulk load an HFile into an open region
286    */
287   public void bulkLoadHFile(String hfilePath,
288       byte[] regionName, byte[] familyName) throws IOException;
289 
290   /**
291    * Replicates the given entries. The guarantee is that the given entries
292    * will be durable on the slave cluster if this method returns without
293    * any exception.
294    * hbase.replication has to be set to true for this to work.
295    *
296    * @param entries entries to replicate
297    * @throws IOException
298    */
299   public void replicateLogEntries(HLog.Entry[] entries) throws IOException;
300 
301 }