001/* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, software 013 * distributed under the License is distributed on an "AS IS" BASIS, 014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 015 * See the License for the specific language governing permissions and 016 * limitations under the License. 017 */ 018package org.apache.hadoop.hbase.regionserver; 019 020import java.io.IOException; 021import java.util.Collection; 022import java.util.List; 023import java.util.Map; 024import org.apache.hadoop.conf.Configuration; 025import org.apache.hadoop.hbase.Cell; 026import org.apache.hadoop.hbase.CellComparator; 027import org.apache.hadoop.hbase.CompareOperator; 028import org.apache.hadoop.hbase.HBaseInterfaceAudience; 029import org.apache.hadoop.hbase.client.Append; 030import org.apache.hadoop.hbase.client.CheckAndMutate; 031import org.apache.hadoop.hbase.client.CheckAndMutateResult; 032import org.apache.hadoop.hbase.client.CompactionState; 033import org.apache.hadoop.hbase.client.Delete; 034import org.apache.hadoop.hbase.client.Get; 035import org.apache.hadoop.hbase.client.Increment; 036import org.apache.hadoop.hbase.client.Mutation; 037import org.apache.hadoop.hbase.client.Put; 038import org.apache.hadoop.hbase.client.RegionInfo; 039import org.apache.hadoop.hbase.client.Result; 040import org.apache.hadoop.hbase.client.RowMutations; 041import org.apache.hadoop.hbase.client.Scan; 042import org.apache.hadoop.hbase.client.TableDescriptor; 043import org.apache.hadoop.hbase.conf.ConfigurationObserver; 044import org.apache.hadoop.hbase.coprocessor.RegionCoprocessor; 045import org.apache.hadoop.hbase.filter.ByteArrayComparable; 046import org.apache.hadoop.hbase.filter.Filter; 047import org.apache.hadoop.hbase.io.TimeRange; 048import org.apache.hadoop.hbase.regionserver.compactions.CompactionLifeCycleTracker; 049import org.apache.yetus.audience.InterfaceAudience; 050import org.apache.yetus.audience.InterfaceStability; 051 052/** 053 * Region is a subset of HRegion with operations required for the {@link RegionCoprocessor 054 * Coprocessors}. The operations include ability to do mutations, requesting compaction, getting 055 * different counters/sizes, locking rows and getting access to {@linkplain Store}s. 056 */ 057@InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.COPROC) 058@InterfaceStability.Evolving 059public interface Region extends ConfigurationObserver { 060 061 /////////////////////////////////////////////////////////////////////////// 062 // Region state 063 064 /** Returns region information for this region */ 065 RegionInfo getRegionInfo(); 066 067 /** Returns table descriptor for this region */ 068 TableDescriptor getTableDescriptor(); 069 070 /** Returns true if region is available (not closed and not closing) */ 071 boolean isAvailable(); 072 073 /** Returns true if region is closed */ 074 boolean isClosed(); 075 076 /** Returns True if closing process has started */ 077 boolean isClosing(); 078 079 /** Returns True if region is read only */ 080 boolean isReadOnly(); 081 082 /** Returns true if region is splittable */ 083 boolean isSplittable(); 084 085 /** Returns true if region is mergeable */ 086 boolean isMergeable(); 087 088 /** 089 * Return the list of Stores managed by this region 090 * <p> 091 * Use with caution. Exposed for use of fixup utilities. 092 * @return a list of the Stores managed by this region 093 */ 094 List<? extends Store> getStores(); 095 096 /** 097 * Return the Store for the given family 098 * <p> 099 * Use with caution. Exposed for use of fixup utilities. 100 * @return the Store for the given family 101 */ 102 Store getStore(byte[] family); 103 104 /** Returns list of store file names for the given families */ 105 List<String> getStoreFileList(byte[][] columns); 106 107 /** 108 * Check the region's underlying store files, open the files that have not been opened yet, and 109 * remove the store file readers for store files no longer available. n 110 */ 111 boolean refreshStoreFiles() throws IOException; 112 113 /** 114 * @return the max sequence id of flushed data on this region; no edit in memory will have a 115 * sequence id that is less that what is returned here. 116 */ 117 long getMaxFlushedSeqId(); 118 119 /** 120 * This can be used to determine the last time all files of this region were major compacted. 121 * @param majorCompactionOnly Only consider HFile that are the result of major compaction 122 * @return the timestamp of the oldest HFile for all stores of this region 123 */ 124 long getOldestHfileTs(boolean majorCompactionOnly) throws IOException; 125 126 /** 127 * @return map of column family names to max sequence id that was read from storage when this 128 * region was opened 129 */ 130 public Map<byte[], Long> getMaxStoreSeqId(); 131 132 /** 133 * @return The earliest time a store in the region was flushed. All other stores in the region 134 * would have been flushed either at, or after this time. 135 */ 136 long getEarliestFlushTimeForAllStores(); 137 138 /////////////////////////////////////////////////////////////////////////// 139 // Metrics 140 141 /** Returns read requests count for this region */ 142 long getReadRequestsCount(); 143 144 /** Returns filtered read requests count for this region */ 145 long getFilteredReadRequestsCount(); 146 147 /** Returns write request count for this region */ 148 long getWriteRequestsCount(); 149 150 /** 151 * @return memstore size for this region, in bytes. It just accounts data size of cells added to 152 * the memstores of this Region. Means size in bytes for key, value and tags within Cells. 153 * It wont consider any java heap overhead for the cell objects or any other. 154 */ 155 long getMemStoreDataSize(); 156 157 /** 158 * @return memstore heap size for this region, in bytes. It accounts data size of cells added to 159 * the memstores of this Region, as well as java heap overhead for the cell objects or any 160 * other. 161 */ 162 long getMemStoreHeapSize(); 163 164 /** 165 * @return memstore off-heap size for this region, in bytes. It accounts data size of cells added 166 * to the memstores of this Region, as well as overhead for the cell objects or any other 167 * that is allocated off-heap. 168 */ 169 long getMemStoreOffHeapSize(); 170 171 /** Returns the number of mutations processed bypassing the WAL */ 172 long getNumMutationsWithoutWAL(); 173 174 /** Returns the size of data processed bypassing the WAL, in bytes */ 175 long getDataInMemoryWithoutWAL(); 176 177 /** Returns the number of blocked requests */ 178 long getBlockedRequestsCount(); 179 180 /** Returns the number of checkAndMutate guards that passed */ 181 long getCheckAndMutateChecksPassed(); 182 183 /** Returns the number of failed checkAndMutate guards */ 184 long getCheckAndMutateChecksFailed(); 185 186 /////////////////////////////////////////////////////////////////////////// 187 // Locking 188 189 // Region read locks 190 191 /** 192 * Operation enum is used in {@link Region#startRegionOperation} and elsewhere to provide context 193 * for various checks. 194 */ 195 enum Operation { 196 ANY, 197 GET, 198 PUT, 199 DELETE, 200 SCAN, 201 APPEND, 202 INCREMENT, 203 SPLIT_REGION, 204 MERGE_REGION, 205 BATCH_MUTATE, 206 REPLAY_BATCH_MUTATE, 207 COMPACT_REGION, 208 REPLAY_EVENT, 209 SNAPSHOT, 210 COMPACT_SWITCH, 211 CHECK_AND_MUTATE 212 } 213 214 /** 215 * This method needs to be called before any public call that reads or modifies data. Acquires a 216 * read lock and checks if the region is closing or closed. 217 * <p> 218 * {@link #closeRegionOperation} MUST then always be called after the operation has completed, 219 * whether it succeeded or failed. n 220 */ 221 // TODO Exposing this and closeRegionOperation() as we have getRowLock() exposed. 222 // Remove if we get rid of exposing getRowLock(). 223 void startRegionOperation() throws IOException; 224 225 /** 226 * This method needs to be called before any public call that reads or modifies data. Acquires a 227 * read lock and checks if the region is closing or closed. 228 * <p> 229 * {@link #closeRegionOperation} MUST then always be called after the operation has completed, 230 * whether it succeeded or failed. 231 * @param op The operation is about to be taken on the region n 232 */ 233 void startRegionOperation(Operation op) throws IOException; 234 235 /** 236 * Closes the region operation lock. n 237 */ 238 void closeRegionOperation() throws IOException; 239 240 /** 241 * Closes the region operation lock. This needs to be called in the finally block corresponding to 242 * the try block of {@link #startRegionOperation(Operation)} n 243 */ 244 void closeRegionOperation(Operation op) throws IOException; 245 246 // Row write locks 247 248 /** 249 * Row lock held by a given thread. One thread may acquire multiple locks on the same row 250 * simultaneously. The locks must be released by calling release() from the same thread. 251 */ 252 public interface RowLock { 253 /** 254 * Release the given lock. If there are no remaining locks held by the current thread then 255 * unlock the row and allow other threads to acquire the lock. 256 * @throws IllegalArgumentException if called by a different thread than the lock owning thread 257 */ 258 void release(); 259 } 260 261 /** 262 * Get a row lock for the specified row. All locks are reentrant. Before calling this function 263 * make sure that a region operation has already been started (the calling thread has already 264 * acquired the region-close-guard lock). 265 * <p> 266 * The obtained locks should be released after use by {@link RowLock#release()} 267 * <p> 268 * NOTE: the boolean passed here has changed. It used to be a boolean that stated whether or not 269 * to wait on the lock. Now it is whether it an exclusive lock is requested. 270 * @param row The row actions will be performed against 271 * @param readLock is the lock reader or writer. True indicates that a non-exclusive lock is 272 * requested 273 * @see #startRegionOperation() 274 * @see #startRegionOperation(Operation) 275 */ 276 // TODO this needs to be exposed as we have RowProcessor now. If RowProcessor is removed, we can 277 // remove this too.. 278 RowLock getRowLock(byte[] row, boolean readLock) throws IOException; 279 280 /////////////////////////////////////////////////////////////////////////// 281 // Region operations 282 283 /** 284 * Perform one or more append operations on a row. n * @return result of the operation n 285 */ 286 Result append(Append append) throws IOException; 287 288 /** 289 * Perform a batch of mutations. 290 * <p> 291 * Please do not operate on a same column of a single row in a batch, we will not consider the 292 * previous operation in the same batch when performing the operations in the batch. 293 * @param mutations the list of mutations 294 * @return an array of OperationStatus which internally contains the OperationStatusCode and the 295 * exceptionMessage if any. n 296 */ 297 OperationStatus[] batchMutate(Mutation[] mutations) throws IOException; 298 299 /** 300 * Atomically checks if a row/family/qualifier value matches the expected value and if it does, it 301 * performs the mutation. If the passed value is null, the lack of column value (ie: 302 * non-existence) is used. See checkAndRowMutate to do many checkAndPuts at a time on a single 303 * row. 304 * @param row to check 305 * @param family column family to check 306 * @param qualifier column qualifier to check 307 * @param op the comparison operator 308 * @param comparator the expected value 309 * @param mutation data to put if check succeeds 310 * @return true if mutation was applied, false otherwise 311 * @deprecated since 2.4.0 and will be removed in 4.0.0. Use 312 * {@link #checkAndMutate(CheckAndMutate)} instead. 313 */ 314 @Deprecated 315 default boolean checkAndMutate(byte[] row, byte[] family, byte[] qualifier, CompareOperator op, 316 ByteArrayComparable comparator, Mutation mutation) throws IOException { 317 return checkAndMutate(row, family, qualifier, op, comparator, TimeRange.allTime(), mutation); 318 } 319 320 /** 321 * Atomically checks if a row/family/qualifier value matches the expected value and if it does, it 322 * performs the mutation. If the passed value is null, the lack of column value (ie: 323 * non-existence) is used. See checkAndRowMutate to do many checkAndPuts at a time on a single 324 * row. 325 * @param row to check 326 * @param family column family to check 327 * @param qualifier column qualifier to check 328 * @param op the comparison operator 329 * @param comparator the expected value 330 * @param mutation data to put if check succeeds 331 * @param timeRange time range to check 332 * @return true if mutation was applied, false otherwise 333 * @deprecated since 2.4.0 and will be removed in 4.0.0. Use 334 * {@link #checkAndMutate(CheckAndMutate)} instead. 335 */ 336 @Deprecated 337 boolean checkAndMutate(byte[] row, byte[] family, byte[] qualifier, CompareOperator op, 338 ByteArrayComparable comparator, TimeRange timeRange, Mutation mutation) throws IOException; 339 340 /** 341 * Atomically checks if a row matches the filter and if it does, it performs the mutation. See 342 * checkAndRowMutate to do many checkAndPuts at a time on a single row. 343 * @param row to check 344 * @param filter the filter 345 * @param mutation data to put if check succeeds 346 * @return true if mutation was applied, false otherwise 347 * @deprecated since 2.4.0 and will be removed in 4.0.0. Use 348 * {@link #checkAndMutate(CheckAndMutate)} instead. 349 */ 350 @Deprecated 351 default boolean checkAndMutate(byte[] row, Filter filter, Mutation mutation) throws IOException { 352 return checkAndMutate(row, filter, TimeRange.allTime(), mutation); 353 } 354 355 /** 356 * Atomically checks if a row value matches the filter and if it does, it performs the mutation. 357 * See checkAndRowMutate to do many checkAndPuts at a time on a single row. 358 * @param row to check 359 * @param filter the filter 360 * @param mutation data to put if check succeeds 361 * @param timeRange time range to check 362 * @return true if mutation was applied, false otherwise 363 * @deprecated since 2.4.0 and will be removed in 4.0.0. Use 364 * {@link #checkAndMutate(CheckAndMutate)} instead. 365 */ 366 @Deprecated 367 boolean checkAndMutate(byte[] row, Filter filter, TimeRange timeRange, Mutation mutation) 368 throws IOException; 369 370 /** 371 * Atomically checks if a row/family/qualifier value matches the expected values and if it does, 372 * it performs the row mutations. If the passed value is null, the lack of column value (ie: 373 * non-existence) is used. Use to do many mutations on a single row. Use checkAndMutate to do one 374 * checkAndMutate at a time. 375 * @param row to check 376 * @param family column family to check 377 * @param qualifier column qualifier to check 378 * @param op the comparison operator 379 * @param comparator the expected value 380 * @param mutations data to put if check succeeds 381 * @return true if mutations were applied, false otherwise 382 * @deprecated since 2.4.0 and will be removed in 4.0.0. Use 383 * {@link #checkAndMutate(CheckAndMutate)} instead. 384 */ 385 @Deprecated 386 default boolean checkAndRowMutate(byte[] row, byte[] family, byte[] qualifier, CompareOperator op, 387 ByteArrayComparable comparator, RowMutations mutations) throws IOException { 388 return checkAndRowMutate(row, family, qualifier, op, comparator, TimeRange.allTime(), 389 mutations); 390 } 391 392 /** 393 * Atomically checks if a row/family/qualifier value matches the expected values and if it does, 394 * it performs the row mutations. If the passed value is null, the lack of column value (ie: 395 * non-existence) is used. Use to do many mutations on a single row. Use checkAndMutate to do one 396 * checkAndMutate at a time. 397 * @param row to check 398 * @param family column family to check 399 * @param qualifier column qualifier to check 400 * @param op the comparison operator 401 * @param comparator the expected value 402 * @param mutations data to put if check succeeds 403 * @param timeRange time range to check 404 * @return true if mutations were applied, false otherwise 405 * @deprecated since 2.4.0 and will be removed in 4.0.0. Use 406 * {@link #checkAndMutate(CheckAndMutate)} instead. 407 */ 408 @Deprecated 409 boolean checkAndRowMutate(byte[] row, byte[] family, byte[] qualifier, CompareOperator op, 410 ByteArrayComparable comparator, TimeRange timeRange, RowMutations mutations) throws IOException; 411 412 /** 413 * Atomically checks if a row matches the filter and if it does, it performs the row mutations. 414 * Use to do many mutations on a single row. Use checkAndMutate to do one checkAndMutate at a 415 * time. 416 * @param row to check 417 * @param filter the filter 418 * @param mutations data to put if check succeeds 419 * @return true if mutations were applied, false otherwise 420 * @deprecated since 2.4.0 and will be removed in 4.0.0. Use 421 * {@link #checkAndMutate(CheckAndMutate)} instead. 422 */ 423 @Deprecated 424 default boolean checkAndRowMutate(byte[] row, Filter filter, RowMutations mutations) 425 throws IOException { 426 return checkAndRowMutate(row, filter, TimeRange.allTime(), mutations); 427 } 428 429 /** 430 * Atomically checks if a row matches the filter and if it does, it performs the row mutations. 431 * Use to do many mutations on a single row. Use checkAndMutate to do one checkAndMutate at a 432 * time. 433 * @param row to check 434 * @param filter the filter 435 * @param mutations data to put if check succeeds 436 * @param timeRange time range to check 437 * @return true if mutations were applied, false otherwise 438 * @deprecated since 2.4.0 and will be removed in 4.0.0. Use 439 * {@link #checkAndMutate(CheckAndMutate)} instead. 440 */ 441 @Deprecated 442 boolean checkAndRowMutate(byte[] row, Filter filter, TimeRange timeRange, RowMutations mutations) 443 throws IOException; 444 445 /** 446 * Atomically checks if a row matches the conditions and if it does, it performs the actions. Use 447 * to do many mutations on a single row. Use checkAndMutate to do one checkAndMutate at a time. 448 * @param checkAndMutate the CheckAndMutate object 449 * @return true if mutations were applied, false otherwise 450 * @throws IOException if an error occurred in this method 451 */ 452 CheckAndMutateResult checkAndMutate(CheckAndMutate checkAndMutate) throws IOException; 453 454 /** 455 * Deletes the specified cells/row. nn 456 */ 457 void delete(Delete delete) throws IOException; 458 459 /** 460 * Do a get based on the get parameter. 461 * @param get query parameters 462 * @return result of the operation 463 */ 464 Result get(Get get) throws IOException; 465 466 /** 467 * Do a get based on the get parameter. 468 * @param get query parameters 469 * @param withCoprocessor invoke coprocessor or not. We don't want to always invoke cp. 470 * @return list of cells resulting from the operation 471 */ 472 List<Cell> get(Get get, boolean withCoprocessor) throws IOException; 473 474 /** 475 * Return an iterator that scans over the HRegion, returning the indicated columns and rows 476 * specified by the {@link Scan}. 477 * <p> 478 * This Iterator must be closed by the caller. 479 * @param scan configured {@link Scan} n * @throws IOException read exceptions 480 */ 481 RegionScanner getScanner(Scan scan) throws IOException; 482 483 /** 484 * Return an iterator that scans over the HRegion, returning the indicated columns and rows 485 * specified by the {@link Scan}. The scanner will also include the additional scanners passed 486 * along with the scanners for the specified Scan instance. Should be careful with the usage to 487 * pass additional scanners only within this Region 488 * <p> 489 * This Iterator must be closed by the caller. 490 * @param scan configured {@link Scan} 491 * @param additionalScanners Any additional scanners to be used n * @throws IOException read 492 * exceptions 493 */ 494 RegionScanner getScanner(Scan scan, List<KeyValueScanner> additionalScanners) throws IOException; 495 496 /** The comparator to be used with the region */ 497 CellComparator getCellComparator(); 498 499 /** 500 * Perform one or more increment operations on a row. n * @return result of the operation n 501 */ 502 Result increment(Increment increment) throws IOException; 503 504 /** 505 * Performs multiple mutations atomically on a single row. 506 * @param mutations object that specifies the set of mutations to perform atomically 507 * @return results of Increment/Append operations. If no Increment/Append operations, it returns 508 * null n 509 */ 510 Result mutateRow(RowMutations mutations) throws IOException; 511 512 /** 513 * Perform atomic mutations within the region. 514 * @param mutations The list of mutations to perform. <code>mutations</code> can contain 515 * operations for multiple rows. Caller has to ensure that all rows are 516 * contained in this region. 517 * @param rowsToLock Rows to lock 518 * @param nonceGroup Optional nonce group of the operation (client Id) 519 * @param nonce Optional nonce of the operation (unique random id to ensure "more 520 * idempotence") If multiple rows are locked care should be taken that 521 * <code>rowsToLock</code> is sorted in order to avoid deadlocks. n 522 */ 523 // TODO Should not be exposing with params nonceGroup, nonce. Change when doing the jira for 524 // Changing processRowsWithLocks and RowProcessor 525 void mutateRowsWithLocks(Collection<Mutation> mutations, Collection<byte[]> rowsToLock, 526 long nonceGroup, long nonce) throws IOException; 527 528 /** 529 * Performs atomic multiple reads and writes on a given row. 530 * @param processor The object defines the reads and writes to a row. 531 * @deprecated As of release 2.0.0, this will be removed in HBase 3.0.0. For customization, use 532 * Coprocessors instead. 533 */ 534 @Deprecated 535 void processRowsWithLocks(RowProcessor<?, ?> processor) throws IOException; 536 537 /** 538 * Performs atomic multiple reads and writes on a given row. 539 * @param processor The object defines the reads and writes to a row. 540 * @param nonceGroup Optional nonce group of the operation (client Id) 541 * @param nonce Optional nonce of the operation (unique random id to ensure "more 542 * idempotence") 543 * @deprecated As of release 2.0.0, this will be removed in HBase 3.0.0. For customization, use 544 * Coprocessors instead. 545 */ 546 // TODO Should not be exposing with params nonceGroup, nonce. Change when doing the jira for 547 // Changing processRowsWithLocks and RowProcessor 548 @Deprecated 549 void processRowsWithLocks(RowProcessor<?, ?> processor, long nonceGroup, long nonce) 550 throws IOException; 551 552 /** 553 * Performs atomic multiple reads and writes on a given row. 554 * @param processor The object defines the reads and writes to a row. 555 * @param timeout The timeout of the processor.process() execution Use a negative number to 556 * switch off the time bound 557 * @param nonceGroup Optional nonce group of the operation (client Id) 558 * @param nonce Optional nonce of the operation (unique random id to ensure "more 559 * idempotence") 560 * @deprecated As of release 2.0.0, this will be removed in HBase 3.0.0. For customization, use 561 * Coprocessors instead. 562 */ 563 // TODO Should not be exposing with params nonceGroup, nonce. Change when doing the jira for 564 // Changing processRowsWithLocks and RowProcessor 565 @Deprecated 566 void processRowsWithLocks(RowProcessor<?, ?> processor, long timeout, long nonceGroup, long nonce) 567 throws IOException; 568 569 /** 570 * Puts some data in the table. nn 571 */ 572 void put(Put put) throws IOException; 573 574 /////////////////////////////////////////////////////////////////////////// 575 // Flushes, compactions, splits, etc. 576 // Wizards only, please 577 578 /** Returns if a given region is in compaction now. */ 579 CompactionState getCompactionState(); 580 581 /** 582 * Request compaction on this region. 583 */ 584 void requestCompaction(String why, int priority, boolean major, 585 CompactionLifeCycleTracker tracker) throws IOException; 586 587 /** 588 * Request compaction for the given family 589 */ 590 void requestCompaction(byte[] family, String why, int priority, boolean major, 591 CompactionLifeCycleTracker tracker) throws IOException; 592 593 /** 594 * Request flush on this region. 595 */ 596 void requestFlush(FlushLifeCycleTracker tracker) throws IOException; 597 598 /** 599 * Wait for all current flushes of the region to complete 600 * @param timeout The maximum time to wait in milliseconds. 601 * @return False when timeout elapsed but flushes are not over. True when flushes are over within 602 * max wait time period. 603 */ 604 boolean waitForFlushes(long timeout); 605 606 /** 607 * @return a read only configuration of this region; throws {@link UnsupportedOperationException} 608 * if you try to set a configuration. 609 */ 610 Configuration getReadOnlyConfiguration(); 611}