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 }