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 26 import org.apache.hadoop.hbase.Abortable; 27 import org.apache.hadoop.hbase.HRegionInfo; 28 import org.apache.hadoop.hbase.HServerInfo; 29 import org.apache.hadoop.hbase.NotServingRegionException; 30 import org.apache.hadoop.hbase.Stoppable; 31 import org.apache.hadoop.hbase.client.Append; 32 import org.apache.hadoop.hbase.client.RowMutations; 33 import org.apache.hadoop.hbase.client.Delete; 34 import org.apache.hadoop.hbase.client.Get; 35 import org.apache.hadoop.hbase.client.Increment; 36 import org.apache.hadoop.hbase.client.MultiAction; 37 import org.apache.hadoop.hbase.client.MultiResponse; 38 import org.apache.hadoop.hbase.client.Put; 39 import org.apache.hadoop.hbase.client.Result; 40 import org.apache.hadoop.hbase.client.Scan; 41 import org.apache.hadoop.hbase.client.coprocessor.Exec; 42 import org.apache.hadoop.hbase.client.coprocessor.ExecResult; 43 import org.apache.hadoop.hbase.filter.CompareFilter.CompareOp; 44 import org.apache.hadoop.hbase.filter.WritableByteArrayComparable; 45 import org.apache.hadoop.hbase.io.hfile.BlockCacheColumnFamilySummary; 46 import org.apache.hadoop.hbase.regionserver.RegionOpeningState; 47 import org.apache.hadoop.hbase.regionserver.compactions.CompactionRequest.CompactionState; 48 import org.apache.hadoop.hbase.regionserver.wal.FailedLogCloseException; 49 import org.apache.hadoop.hbase.regionserver.wal.HLog; 50 import org.apache.hadoop.hbase.security.TokenInfo; 51 import org.apache.hadoop.hbase.security.KerberosInfo; 52 import org.apache.hadoop.hbase.util.Pair; 53 import org.apache.hadoop.ipc.RemoteException; 54 import org.apache.hadoop.hbase.ipc.VersionedProtocol; 55 56 /** 57 * Clients interact with HRegionServers using a handle to the HRegionInterface. 58 * 59 * <p>NOTE: if you change the interface, you must change the RPC version 60 * number in HBaseRPCProtocolVersion 61 */ 62 @KerberosInfo( 63 serverPrincipal = "hbase.regionserver.kerberos.principal") 64 @TokenInfo("HBASE_AUTH_TOKEN") 65 public interface HRegionInterface extends VersionedProtocol, Stoppable, Abortable { 66 /** 67 * This Interfaces' version. Version changes when the Interface changes. 68 */ 69 // All HBase Interfaces used derive from HBaseRPCProtocolVersion. It 70 // maintained a single global version number on all HBase Interfaces. This 71 // meant all HBase RPC was broke though only one of the three RPC Interfaces 72 // had changed. This has since been undone. 73 public static final long VERSION = 29L; 74 75 /** 76 * Get metainfo about an HRegion 77 * 78 * @param regionName name of the region 79 * @return HRegionInfo object for region 80 * @throws NotServingRegionException 81 * @throws ConnectException 82 * @throws IOException This can manifest as an Hadoop ipc {@link RemoteException} 83 */ 84 public HRegionInfo getRegionInfo(final byte [] regionName) 85 throws NotServingRegionException, ConnectException, IOException; 86 87 /** 88 * Flush the given region 89 * @param region name 90 */ 91 public void flushRegion(byte[] regionName) 92 throws IllegalArgumentException, IOException; 93 94 /** 95 * Flush the given region if lastFlushTime < ifOlderThanTS 96 * @param region name 97 * @param timestamp 98 */ 99 public void flushRegion(byte[] regionName, long ifOlderThanTS) 100 throws IllegalArgumentException, IOException; 101 102 /** 103 * Gets last flush time for the given region 104 * @return the last flush time for a region 105 */ 106 public long getLastFlushTime(byte[] regionName); 107 108 /** 109 * Get a list of store files for a particular CF in a particular region 110 * @param region name 111 * @param CF name 112 * @return the list of store files 113 */ 114 public List<String> getStoreFileList(byte[] regionName, byte[] columnFamily) 115 throws IllegalArgumentException; 116 117 /** 118 * Get a list of store files for a set of CFs in a particular region 119 * @param region name 120 * @param CF names 121 * @return the list of store files 122 */ 123 public List<String> getStoreFileList(byte[] regionName, byte[][] columnFamilies) 124 throws IllegalArgumentException; 125 126 /** 127 * Get a list of store files for all CFs in a particular region 128 * @param region name 129 * @return the list of store files 130 */ 131 public List<String> getStoreFileList(byte[] regionName) 132 throws IllegalArgumentException; 133 134 /** 135 * Return all the data for the row that matches <i>row</i> exactly, 136 * or the one that immediately preceeds it. 137 * 138 * @param regionName region name 139 * @param row row key 140 * @param family Column family to look for row in. 141 * @return map of values 142 * @throws IOException e 143 */ 144 public Result getClosestRowBefore(final byte [] regionName, 145 final byte [] row, final byte [] family) 146 throws IOException; 147 148 /** 149 * Perform Get operation. 150 * @param regionName name of region to get from 151 * @param get Get operation 152 * @return Result 153 * @throws IOException e 154 */ 155 public Result get(byte [] regionName, Get get) throws IOException; 156 157 /** 158 * Perform exists operation. 159 * @param regionName name of region to get from 160 * @param get Get operation describing cell to test 161 * @return true if exists 162 * @throws IOException e 163 */ 164 public boolean exists(byte [] regionName, Get get) throws IOException; 165 166 /** 167 * Put data into the specified region 168 * @param regionName region name 169 * @param put the data to be put 170 * @throws IOException e 171 */ 172 public void put(final byte [] regionName, final Put put) 173 throws IOException; 174 175 /** 176 * Put an array of puts into the specified region 177 * 178 * @param regionName region name 179 * @param puts List of puts to execute 180 * @return The number of processed put's. Returns -1 if all Puts 181 * processed successfully. 182 * @throws IOException e 183 */ 184 public int put(final byte[] regionName, final List<Put> puts) 185 throws IOException; 186 187 /** 188 * Deletes all the KeyValues that match those found in the Delete object, 189 * if their ts <= to the Delete. In case of a delete with a specific ts it 190 * only deletes that specific KeyValue. 191 * @param regionName region name 192 * @param delete delete object 193 * @throws IOException e 194 */ 195 public void delete(final byte[] regionName, final Delete delete) 196 throws IOException; 197 198 /** 199 * Put an array of deletes into the specified region 200 * 201 * @param regionName region name 202 * @param deletes delete List to execute 203 * @return The number of processed deletes. Returns -1 if all Deletes 204 * processed successfully. 205 * @throws IOException e 206 */ 207 public int delete(final byte[] regionName, final List<Delete> deletes) 208 throws IOException; 209 210 /** 211 * Atomically checks if a row/family/qualifier value match the expectedValue. 212 * If it does, it adds the put. If passed expected value is null, then the 213 * check is for non-existance of the row/column. 214 * 215 * @param regionName region name 216 * @param row row to check 217 * @param family column family 218 * @param qualifier column qualifier 219 * @param value the expected value 220 * @param put data to put if check succeeds 221 * @throws IOException e 222 * @return true if the new put was execute, false otherwise 223 */ 224 public boolean checkAndPut(final byte[] regionName, final byte [] row, 225 final byte [] family, final byte [] qualifier, final byte [] value, 226 final Put put) 227 throws IOException; 228 229 230 /** 231 * Atomically checks if a row/family/qualifier value match the expectedValue. 232 * If it does, it adds the delete. If passed expected value is null, then the 233 * check is for non-existance of the row/column. 234 * 235 * @param regionName region name 236 * @param row row to check 237 * @param family column family 238 * @param qualifier column qualifier 239 * @param value the expected value 240 * @param delete data to delete if check succeeds 241 * @throws IOException e 242 * @return true if the new delete was execute, false otherwise 243 */ 244 public boolean checkAndDelete(final byte[] regionName, final byte [] row, 245 final byte [] family, final byte [] qualifier, final byte [] value, 246 final Delete delete) 247 throws IOException; 248 249 /** 250 * Atomically increments a column value. If the column value isn't long-like, 251 * this could throw an exception. If passed expected value is null, then the 252 * check is for non-existance of the row/column. 253 * 254 * @param regionName region name 255 * @param row row to check 256 * @param family column family 257 * @param qualifier column qualifier 258 * @param amount long amount to increment 259 * @param writeToWAL whether to write the increment to the WAL 260 * @return new incremented column value 261 * @throws IOException e 262 */ 263 public long incrementColumnValue(byte [] regionName, byte [] row, 264 byte [] family, byte [] qualifier, long amount, boolean writeToWAL) 265 throws IOException; 266 267 public void mutateRow(byte[] regionName, RowMutations rm) 268 throws IOException; 269 270 /** 271 * Appends values to one or more columns values in a row. Optionally 272 * Returns the updated keys after the append. 273 * <p> 274 * This operation does not appear atomic to readers. Appends are done 275 * under a row lock but readers do not take row locks. 276 * @param regionName region name 277 * @param append Append operation 278 * @return changed cells (maybe null) 279 */ 280 public Result append(byte[] regionName, Append append) 281 throws IOException; 282 283 /** 284 * Increments one or more columns values in a row. Returns the 285 * updated keys after the increment. 286 * <p> 287 * This operation does not appear atomic to readers. Increments are done 288 * under a row lock but readers do not take row locks. 289 * @param regionName region name 290 * @param increment increment operation 291 * @return incremented cells 292 */ 293 public Result increment(byte[] regionName, Increment increment) 294 throws IOException; 295 296 // 297 // remote scanner interface 298 // 299 300 /** 301 * Opens a remote scanner with a RowFilter. 302 * 303 * @param regionName name of region to scan 304 * @param scan configured scan object 305 * @return scannerId scanner identifier used in other calls 306 * @throws IOException e 307 */ 308 public long openScanner(final byte [] regionName, final Scan scan) 309 throws IOException; 310 311 /** 312 * Get the next set of values 313 * @param scannerId clientId passed to openScanner 314 * @return map of values; returns null if no results. 315 * @throws IOException e 316 */ 317 public Result next(long scannerId) throws IOException; 318 319 /** 320 * Get the next set of values 321 * @param scannerId clientId passed to openScanner 322 * @param numberOfRows the number of rows to fetch 323 * @return Array of Results (map of values); array is empty if done with this 324 * region and null if we are NOT to go to the next region (happens when a 325 * filter rules that the scan is done). 326 * @throws IOException e 327 */ 328 public Result [] next(long scannerId, int numberOfRows) throws IOException; 329 330 /** 331 * Close a scanner 332 * 333 * @param scannerId the scanner id returned by openScanner 334 * @throws IOException e 335 */ 336 public void close(long scannerId) throws IOException; 337 338 /** 339 * Opens a remote row lock. 340 * 341 * @param regionName name of region 342 * @param row row to lock 343 * @return lockId lock identifier 344 * @throws IOException e 345 */ 346 public long lockRow(final byte [] regionName, final byte [] row) 347 throws IOException; 348 349 /** 350 * Releases a remote row lock. 351 * 352 * @param regionName region name 353 * @param lockId the lock id returned by lockRow 354 * @throws IOException e 355 */ 356 public void unlockRow(final byte [] regionName, final long lockId) 357 throws IOException; 358 359 360 /** 361 * @return All regions online on this region server 362 * @throws IOException e 363 */ 364 public List<HRegionInfo> getOnlineRegions() throws IOException; 365 366 /** 367 * Method used when a master is taking the place of another failed one. 368 * @return This servers {@link HServerInfo}; it has RegionServer POV on the 369 * hostname which may not agree w/ how the Master sees this server. 370 * @throws IOException e 371 * @deprecated 372 */ 373 public HServerInfo getHServerInfo() throws IOException; 374 375 /** 376 * Method used for doing multiple actions(Deletes, Gets and Puts) in one call 377 * @param multi 378 * @return MultiResult 379 * @throws IOException 380 */ 381 public <R> MultiResponse multi(MultiAction<R> multi) throws IOException; 382 383 /** 384 * Atomically bulk load multiple HFiles (say from different column families) 385 * into an open region. 386 * 387 * @param familyPaths List of (family, hfile path) pairs 388 * @param regionName name of region to load hfiles into 389 * @return true if successful, false if failed recoverably 390 * @throws IOException if fails unrecoverably 391 */ 392 public boolean bulkLoadHFiles(List<Pair<byte[], String>> familyPaths, byte[] regionName) 393 throws IOException; 394 395 /** 396 * Atomically bulk load multiple HFiles (say from different column families) 397 * into an open region. 398 * 399 * @param familyPaths List of (family, hfile path) pairs 400 * @param regionName name of region to load hfiles into 401 * @param assignSeqNum should we assign sequence numbers 402 * @return true if successful, false if failed recoverably 403 * @throws IOException if fails unrecoverably 404 */ 405 public boolean bulkLoadHFiles(List<Pair<byte[], String>> familyPaths, byte[] regionName, 406 boolean assignSeqNum) 407 throws IOException; 408 409 410 // Master methods 411 412 /** 413 * Opens the specified region. 414 * 415 * @param region 416 * region to open 417 * @return RegionOpeningState 418 * OPENED - if region open request was successful. 419 * ALREADY_OPENED - if the region was already opened. 420 * FAILED_OPENING - if region opening failed. 421 * 422 * @throws IOException 423 */ 424 public RegionOpeningState openRegion(final HRegionInfo region) throws IOException; 425 426 /** 427 * Opens the specified region. 428 * @param region 429 * region to open 430 * @param versionOfOfflineNode 431 * the version of znode to compare when RS transitions the znode from 432 * OFFLINE state. 433 * @return RegionOpeningState 434 * OPENED - if region open request was successful. 435 * ALREADY_OPENED - if the region was already opened. 436 * FAILED_OPENING - if region opening failed. 437 * @throws IOException 438 */ 439 public RegionOpeningState openRegion(HRegionInfo region, int versionOfOfflineNode) 440 throws IOException; 441 442 /** 443 * Opens the specified regions. 444 * @param regions regions to open 445 * @throws IOException 446 */ 447 public void openRegions(final List<HRegionInfo> regions) throws IOException; 448 449 /** 450 * Closes the specified region. 451 * @param region region to close 452 * @return true if closing region, false if not 453 * @throws IOException 454 */ 455 public boolean closeRegion(final HRegionInfo region) 456 throws IOException; 457 458 /** 459 * Closes the specified region. 460 * @param region region to close 461 * @param versionOfClosingNode 462 * the version of znode to compare when RS transitions the znode 463 * from CLOSING state. 464 * @return true if closing region, false if not 465 * @throws IOException 466 */ 467 public boolean closeRegion(final HRegionInfo region, 468 final int versionOfClosingNode) 469 throws IOException; 470 471 /** 472 * Closes the specified region and will use or not use ZK during the close 473 * according to the specified flag. 474 * @param region region to close 475 * @param zk true if transitions should be done in ZK, false if not 476 * @return true if closing region, false if not 477 * @throws IOException 478 */ 479 public boolean closeRegion(final HRegionInfo region, final boolean zk) 480 throws IOException; 481 482 /** 483 * Closes the region in the RS with the specified encoded regionName and will 484 * use or not use ZK during the close according to the specified flag. Note 485 * that the encoded region name is in byte format. 486 * 487 * @param encodedRegionName 488 * in bytes 489 * @param zk 490 * true if to use zookeeper, false if need not. 491 * @return true if region is closed, false if not. 492 * @throws IOException 493 */ 494 public boolean closeRegion(byte[] encodedRegionName, final boolean zk) 495 throws IOException; 496 497 // Region administrative methods 498 499 /** 500 * Flushes the MemStore of the specified region. 501 * <p> 502 * This method is synchronous. 503 * @param regionInfo region to flush 504 * @throws NotServingRegionException 505 * @throws IOException 506 * @deprecated use {@link #flushRegion(byte[])} instead 507 */ 508 void flushRegion(HRegionInfo regionInfo) 509 throws NotServingRegionException, IOException; 510 511 /** 512 * Splits the specified region. 513 * <p> 514 * This method currently flushes the region and then forces a compaction which 515 * will then trigger a split. The flush is done synchronously but the 516 * compaction is asynchronous. 517 * @param regionInfo region to split 518 * @throws NotServingRegionException 519 * @throws IOException 520 */ 521 void splitRegion(HRegionInfo regionInfo) 522 throws NotServingRegionException, IOException; 523 524 /** 525 * Splits the specified region. 526 * <p> 527 * This method currently flushes the region and then forces a compaction which 528 * will then trigger a split. The flush is done synchronously but the 529 * compaction is asynchronous. 530 * @param regionInfo region to split 531 * @param splitPoint the explicit row to split on 532 * @throws NotServingRegionException 533 * @throws IOException 534 */ 535 void splitRegion(HRegionInfo regionInfo, byte[] splitPoint) 536 throws NotServingRegionException, IOException; 537 538 /** 539 * Compacts the specified region. Performs a major compaction if specified. 540 * <p> 541 * This method is asynchronous. 542 * @param regionInfo region to compact 543 * @param major true to force major compaction 544 * @throws NotServingRegionException 545 * @throws IOException 546 */ 547 void compactRegion(HRegionInfo regionInfo, boolean major) 548 throws NotServingRegionException, IOException; 549 550 /** 551 * Compacts a column-family within a specified region. 552 * Performs a major compaction if specified. 553 * <p> 554 * This method is asynchronous. 555 * @param regionInfo region to compact 556 * @param major true to force major compaction 557 * @param columnFamily column family within a region to compact 558 * @throws NotServingRegionException 559 * @throws IOException 560 */ 561 void compactRegion(HRegionInfo regionInfo, boolean major, byte[] columnFamily) 562 throws NotServingRegionException, IOException; 563 564 /** 565 * Replicates the given entries. The guarantee is that the given entries 566 * will be durable on the slave cluster if this method returns without 567 * any exception. 568 * hbase.replication has to be set to true for this to work. 569 * 570 * @param entries entries to replicate 571 * @throws IOException 572 */ 573 public void replicateLogEntries(HLog.Entry[] entries) throws IOException; 574 575 /** 576 * Executes a single {@link org.apache.hadoop.hbase.ipc.CoprocessorProtocol} 577 * method using the registered protocol handlers. 578 * {@link CoprocessorProtocol} implementations must be registered via the 579 * {@link org.apache.hadoop.hbase.regionserver.HRegion#registerProtocol(Class, org.apache.hadoop.hbase.ipc.CoprocessorProtocol)} 580 * method before they are available. 581 * 582 * @param regionName name of the region against which the invocation is executed 583 * @param call an {@code Exec} instance identifying the protocol, method name, 584 * and parameters for the method invocation 585 * @return an {@code ExecResult} instance containing the region name of the 586 * invocation and the return value 587 * @throws IOException if no registered protocol handler is found or an error 588 * occurs during the invocation 589 * @see org.apache.hadoop.hbase.regionserver.HRegion#registerProtocol(Class, org.apache.hadoop.hbase.ipc.CoprocessorProtocol) 590 */ 591 ExecResult execCoprocessor(byte[] regionName, Exec call) 592 throws IOException; 593 594 /** 595 * Atomically checks if a row/family/qualifier value match the expectedValue. 596 * If it does, it adds the put. If passed expected value is null, then the 597 * check is for non-existance of the row/column. 598 * 599 * @param regionName 600 * @param row 601 * @param family 602 * @param qualifier 603 * @param compareOp 604 * @param comparator 605 * @param put 606 * @throws IOException 607 * @return true if the new put was execute, false otherwise 608 */ 609 public boolean checkAndPut(final byte[] regionName, final byte[] row, 610 final byte[] family, final byte[] qualifier, final CompareOp compareOp, 611 final WritableByteArrayComparable comparator, final Put put) 612 throws IOException; 613 614 /** 615 * Atomically checks if a row/family/qualifier value match the expectedValue. 616 * If it does, it adds the delete. If passed expected value is null, then the 617 * check is for non-existance of the row/column. 618 * 619 * @param regionName 620 * @param row 621 * @param family 622 * @param qualifier 623 * @param compareOp 624 * @param comparator 625 * @param delete 626 * @throws IOException 627 * @return true if the new put was execute, false otherwise 628 */ 629 public boolean checkAndDelete(final byte[] regionName, final byte[] row, 630 final byte[] family, final byte[] qualifier, final CompareOp compareOp, 631 final WritableByteArrayComparable comparator, final Delete delete) 632 throws IOException; 633 634 /** 635 * Performs a BlockCache summary and returns a List of BlockCacheColumnFamilySummary objects. 636 * This method could be fairly heavyweight in that it evaluates the entire HBase file-system 637 * against what is in the RegionServer BlockCache. 638 * 639 * @return BlockCacheColumnFamilySummary 640 * @throws IOException exception 641 */ 642 public List<BlockCacheColumnFamilySummary> getBlockCacheColumnFamilySummaries() throws IOException; 643 /** 644 * Roll the log writer. That is, start writing log messages to a new file. 645 * 646 * @throws IOException 647 * @throws FailedLogCloseException 648 * @return If lots of logs, flush the returned regions so next time through 649 * we can clean logs. Returns null if nothing to flush. Names are actual 650 * region names as returned by {@link HRegionInfo#getEncodedName()} 651 */ 652 public byte[][] rollHLogWriter() throws IOException, FailedLogCloseException; 653 654 /** 655 * Get the current compaction state of the region. 656 * 657 * @param regionName the name of the region to check compaction statte. 658 * @return the compaction state name. 659 * @throws IOException exception 660 */ 661 public String getCompactionState(final byte[] regionName) throws IOException; 662 663 @Override 664 public void stop(String why); 665 666 /** 667 * Perform scan operation. 668 * @param regionName name of region to get from 669 * @param Scan scan operation 670 * @param numberOfRows the maximum number of rows to fetch 671 * @return Array of Results;array is empty if done with this region and null 672 * if we are NOT to go to the next region (happens when a filter rules 673 * that the scan is done). 674 * @throws IOException e 675 */ 676 public Result[] scan(byte[] regionName, Scan scan, int numberOfRows) 677 throws IOException; 678 }