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 * Get the next set of values 332 * @param scannerId clientId passed to openScanner 333 * @param numberOfRows the number of rows to fetch 334 * @param callSeq the number which represents the sequence used by client scanner 335 * @return Array of Results (map of values); array is empty if done with this 336 * region and null if we are NOT to go to the next region (happens when a 337 * filter rules that the scan is done). 338 * @throws IOException e 339 */ 340 public Result[] next(long scannerId, int caching, long callSeq) throws IOException; 341 342 /** 343 * Close a scanner 344 * 345 * @param scannerId the scanner id returned by openScanner 346 * @throws IOException e 347 */ 348 public void close(long scannerId) throws IOException; 349 350 /** 351 * Opens a remote row lock. 352 * 353 * @param regionName name of region 354 * @param row row to lock 355 * @return lockId lock identifier 356 * @throws IOException e 357 */ 358 public long lockRow(final byte [] regionName, final byte [] row) 359 throws IOException; 360 361 /** 362 * Releases a remote row lock. 363 * 364 * @param regionName region name 365 * @param lockId the lock id returned by lockRow 366 * @throws IOException e 367 */ 368 public void unlockRow(final byte [] regionName, final long lockId) 369 throws IOException; 370 371 372 /** 373 * @return All regions online on this region server 374 * @throws IOException e 375 */ 376 public List<HRegionInfo> getOnlineRegions() throws IOException; 377 378 /** 379 * Method used when a master is taking the place of another failed one. 380 * @return This servers {@link HServerInfo}; it has RegionServer POV on the 381 * hostname which may not agree w/ how the Master sees this server. 382 * @throws IOException e 383 * @deprecated 384 */ 385 public HServerInfo getHServerInfo() throws IOException; 386 387 /** 388 * Method used for doing multiple actions(Deletes, Gets and Puts) in one call 389 * @param multi 390 * @return MultiResult 391 * @throws IOException 392 */ 393 public <R> MultiResponse multi(MultiAction<R> multi) 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 * @return true if successful, false if failed recoverably 402 * @throws IOException if fails unrecoverably 403 */ 404 public boolean bulkLoadHFiles(List<Pair<byte[], String>> familyPaths, byte[] regionName) 405 throws IOException; 406 407 /** 408 * Atomically bulk load multiple HFiles (say from different column families) 409 * into an open region. 410 * 411 * @param familyPaths List of (family, hfile path) pairs 412 * @param regionName name of region to load hfiles into 413 * @param assignSeqNum should we assign sequence numbers 414 * @return true if successful, false if failed recoverably 415 * @throws IOException if fails unrecoverably 416 */ 417 public boolean bulkLoadHFiles(List<Pair<byte[], String>> familyPaths, byte[] regionName, 418 boolean assignSeqNum) 419 throws IOException; 420 421 422 // Master methods 423 424 /** 425 * Opens the specified region. 426 * 427 * @param region 428 * region to open 429 * @return RegionOpeningState 430 * OPENED - if region open request was successful. 431 * ALREADY_OPENED - if the region was already opened. 432 * FAILED_OPENING - if region opening failed. 433 * 434 * @throws IOException 435 */ 436 public RegionOpeningState openRegion(final HRegionInfo region) throws IOException; 437 438 /** 439 * Opens the specified region. 440 * @param region 441 * region to open 442 * @param versionOfOfflineNode 443 * the version of znode to compare when RS transitions the znode from 444 * OFFLINE state. 445 * @return RegionOpeningState 446 * OPENED - if region open request was successful. 447 * ALREADY_OPENED - if the region was already opened. 448 * FAILED_OPENING - if region opening failed. 449 * @throws IOException 450 */ 451 public RegionOpeningState openRegion(HRegionInfo region, int versionOfOfflineNode) 452 throws IOException; 453 454 /** 455 * Opens the specified regions. 456 * @param regions regions to open 457 * @throws IOException 458 */ 459 public void openRegions(final List<HRegionInfo> regions) throws IOException; 460 461 /** 462 * Closes the specified region. 463 * @param region region to close 464 * @return true if closing region, false if not 465 * @throws IOException 466 */ 467 public boolean closeRegion(final HRegionInfo region) 468 throws IOException; 469 470 /** 471 * Closes the specified region. 472 * @param region region to close 473 * @param versionOfClosingNode 474 * the version of znode to compare when RS transitions the znode 475 * from CLOSING state. 476 * @return true if closing region, false if not 477 * @throws IOException 478 */ 479 public boolean closeRegion(final HRegionInfo region, 480 final int versionOfClosingNode) 481 throws IOException; 482 483 /** 484 * Closes the specified region and will use or not use ZK during the close 485 * according to the specified flag. 486 * @param region region to close 487 * @param zk true if transitions should be done in ZK, false if not 488 * @return true if closing region, false if not 489 * @throws IOException 490 */ 491 public boolean closeRegion(final HRegionInfo region, final boolean zk) 492 throws IOException; 493 494 /** 495 * Closes the region in the RS with the specified encoded regionName and will 496 * use or not use ZK during the close according to the specified flag. Note 497 * that the encoded region name is in byte format. 498 * 499 * @param encodedRegionName 500 * in bytes 501 * @param zk 502 * true if to use zookeeper, false if need not. 503 * @return true if region is closed, false if not. 504 * @throws IOException 505 */ 506 public boolean closeRegion(byte[] encodedRegionName, final boolean zk) 507 throws IOException; 508 509 // Region administrative methods 510 511 /** 512 * Flushes the MemStore of the specified region. 513 * <p> 514 * This method is synchronous. 515 * @param regionInfo region to flush 516 * @throws NotServingRegionException 517 * @throws IOException 518 * @deprecated use {@link #flushRegion(byte[])} instead 519 */ 520 void flushRegion(HRegionInfo regionInfo) 521 throws NotServingRegionException, IOException; 522 523 /** 524 * Splits the specified region. 525 * <p> 526 * This method currently flushes the region and then forces a compaction which 527 * will then trigger a split. The flush is done synchronously but the 528 * compaction is asynchronous. 529 * @param regionInfo region to split 530 * @throws NotServingRegionException 531 * @throws IOException 532 */ 533 void splitRegion(HRegionInfo regionInfo) 534 throws NotServingRegionException, IOException; 535 536 /** 537 * Splits the specified region. 538 * <p> 539 * This method currently flushes the region and then forces a compaction which 540 * will then trigger a split. The flush is done synchronously but the 541 * compaction is asynchronous. 542 * @param regionInfo region to split 543 * @param splitPoint the explicit row to split on 544 * @throws NotServingRegionException 545 * @throws IOException 546 */ 547 void splitRegion(HRegionInfo regionInfo, byte[] splitPoint) 548 throws NotServingRegionException, IOException; 549 550 /** 551 * Compacts the specified region. Performs a major compaction if specified. 552 * <p> 553 * This method is asynchronous. 554 * @param regionInfo region to compact 555 * @param major true to force major compaction 556 * @throws NotServingRegionException 557 * @throws IOException 558 */ 559 void compactRegion(HRegionInfo regionInfo, boolean major) 560 throws NotServingRegionException, IOException; 561 562 /** 563 * Compacts a column-family within a specified region. 564 * Performs a major compaction if specified. 565 * <p> 566 * This method is asynchronous. 567 * @param regionInfo region to compact 568 * @param major true to force major compaction 569 * @param columnFamily column family within a region to compact 570 * @throws NotServingRegionException 571 * @throws IOException 572 */ 573 void compactRegion(HRegionInfo regionInfo, boolean major, byte[] columnFamily) 574 throws NotServingRegionException, IOException; 575 576 /** 577 * Replicates the given entries. The guarantee is that the given entries 578 * will be durable on the slave cluster if this method returns without 579 * any exception. 580 * hbase.replication has to be set to true for this to work. 581 * 582 * @param entries entries to replicate 583 * @throws IOException 584 */ 585 public void replicateLogEntries(HLog.Entry[] entries) throws IOException; 586 587 /** 588 * Executes a single {@link org.apache.hadoop.hbase.ipc.CoprocessorProtocol} 589 * method using the registered protocol handlers. 590 * {@link CoprocessorProtocol} implementations must be registered via the 591 * {@link org.apache.hadoop.hbase.regionserver.HRegion#registerProtocol(Class, org.apache.hadoop.hbase.ipc.CoprocessorProtocol)} 592 * method before they are available. 593 * 594 * @param regionName name of the region against which the invocation is executed 595 * @param call an {@code Exec} instance identifying the protocol, method name, 596 * and parameters for the method invocation 597 * @return an {@code ExecResult} instance containing the region name of the 598 * invocation and the return value 599 * @throws IOException if no registered protocol handler is found or an error 600 * occurs during the invocation 601 * @see org.apache.hadoop.hbase.regionserver.HRegion#registerProtocol(Class, org.apache.hadoop.hbase.ipc.CoprocessorProtocol) 602 */ 603 ExecResult execCoprocessor(byte[] regionName, Exec call) 604 throws IOException; 605 606 /** 607 * Atomically checks if a row/family/qualifier value match the expectedValue. 608 * If it does, it adds the put. If passed expected value is null, then the 609 * check is for non-existance of the row/column. 610 * 611 * @param regionName 612 * @param row 613 * @param family 614 * @param qualifier 615 * @param compareOp 616 * @param comparator 617 * @param put 618 * @throws IOException 619 * @return true if the new put was execute, false otherwise 620 */ 621 public boolean checkAndPut(final byte[] regionName, final byte[] row, 622 final byte[] family, final byte[] qualifier, final CompareOp compareOp, 623 final WritableByteArrayComparable comparator, final Put put) 624 throws IOException; 625 626 /** 627 * Atomically checks if a row/family/qualifier value match the expectedValue. 628 * If it does, it adds the delete. If passed expected value is null, then the 629 * check is for non-existance of the row/column. 630 * 631 * @param regionName 632 * @param row 633 * @param family 634 * @param qualifier 635 * @param compareOp 636 * @param comparator 637 * @param delete 638 * @throws IOException 639 * @return true if the new put was execute, false otherwise 640 */ 641 public boolean checkAndDelete(final byte[] regionName, final byte[] row, 642 final byte[] family, final byte[] qualifier, final CompareOp compareOp, 643 final WritableByteArrayComparable comparator, final Delete delete) 644 throws IOException; 645 646 /** 647 * Performs a BlockCache summary and returns a List of BlockCacheColumnFamilySummary objects. 648 * This method could be fairly heavyweight in that it evaluates the entire HBase file-system 649 * against what is in the RegionServer BlockCache. 650 * 651 * @return BlockCacheColumnFamilySummary 652 * @throws IOException exception 653 */ 654 public List<BlockCacheColumnFamilySummary> getBlockCacheColumnFamilySummaries() throws IOException; 655 /** 656 * Roll the log writer. That is, start writing log messages to a new file. 657 * 658 * @throws IOException 659 * @throws FailedLogCloseException 660 * @return If lots of logs, flush the returned regions so next time through 661 * we can clean logs. Returns null if nothing to flush. Names are actual 662 * region names as returned by {@link HRegionInfo#getEncodedName()} 663 */ 664 public byte[][] rollHLogWriter() throws IOException, FailedLogCloseException; 665 666 /** 667 * Get the current compaction state of the region. 668 * 669 * @param regionName the name of the region to check compaction statte. 670 * @return the compaction state name. 671 * @throws IOException exception 672 */ 673 public String getCompactionState(final byte[] regionName) throws IOException; 674 675 @Override 676 public void stop(String why); 677 678 /** 679 * Perform scan operation. 680 * @param regionName name of region to get from 681 * @param Scan scan operation 682 * @param numberOfRows the maximum number of rows to fetch 683 * @return Array of Results;array is empty if done with this region and null 684 * if we are NOT to go to the next region (happens when a filter rules 685 * that the scan is done). 686 * @throws IOException e 687 */ 688 public Result[] scan(byte[] regionName, Scan scan, int numberOfRows) 689 throws IOException; 690 }