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 }