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. 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 coprocessor requests count for this region */ 145 long getCpRequestsCount(); 146 147 /** Returns filtered read requests count for this region */ 148 long getFilteredReadRequestsCount(); 149 150 /** Returns write request count for this region */ 151 long getWriteRequestsCount(); 152 153 /** 154 * @return memstore size for this region, in bytes. It just accounts data size of cells added to 155 * the memstores of this Region. Means size in bytes for key, value and tags within Cells. 156 * It wont consider any java heap overhead for the cell objects or any other. 157 */ 158 long getMemStoreDataSize(); 159 160 /** 161 * @return memstore heap size for this region, in bytes. It accounts data size of cells added to 162 * the memstores of this Region, as well as java heap overhead for the cell objects or any 163 * other. 164 */ 165 long getMemStoreHeapSize(); 166 167 /** 168 * @return memstore off-heap size for this region, in bytes. It accounts data size of cells added 169 * to the memstores of this Region, as well as overhead for the cell objects or any other 170 * that is allocated off-heap. 171 */ 172 long getMemStoreOffHeapSize(); 173 174 /** Returns the number of mutations processed bypassing the WAL */ 175 long getNumMutationsWithoutWAL(); 176 177 /** Returns the size of data processed bypassing the WAL, in bytes */ 178 long getDataInMemoryWithoutWAL(); 179 180 /** Returns the number of blocked requests */ 181 long getBlockedRequestsCount(); 182 183 /** Returns the number of checkAndMutate guards that passed */ 184 long getCheckAndMutateChecksPassed(); 185 186 /** Returns the number of failed checkAndMutate guards */ 187 long getCheckAndMutateChecksFailed(); 188 189 /////////////////////////////////////////////////////////////////////////// 190 // Locking 191 192 // Region read locks 193 194 /** 195 * Operation enum is used in {@link Region#startRegionOperation} and elsewhere to provide context 196 * for various checks. 197 */ 198 enum Operation { 199 ANY, 200 GET, 201 PUT, 202 DELETE, 203 SCAN, 204 APPEND, 205 INCREMENT, 206 SPLIT_REGION, 207 MERGE_REGION, 208 BATCH_MUTATE, 209 REPLAY_BATCH_MUTATE, 210 COMPACT_REGION, 211 REPLAY_EVENT, 212 SNAPSHOT, 213 COMPACT_SWITCH, 214 CHECK_AND_MUTATE 215 } 216 217 /** 218 * This method needs to be called before any public call that reads or modifies data. Acquires a 219 * read lock and checks if the region is closing or closed. 220 * <p> 221 * {@link #closeRegionOperation} MUST then always be called after the operation has completed, 222 * whether it succeeded or failed. 223 */ 224 // TODO Exposing this and closeRegionOperation() as we have getRowLock() exposed. 225 // Remove if we get rid of exposing getRowLock(). 226 void startRegionOperation() throws IOException; 227 228 /** 229 * This method needs to be called before any public call that reads or modifies data. Acquires a 230 * read lock and checks if the region is closing or closed. 231 * <p> 232 * {@link #closeRegionOperation} MUST then always be called after the operation has completed, 233 * whether it succeeded or failed. 234 * @param op The operation is about to be taken on the region 235 */ 236 void startRegionOperation(Operation op) throws IOException; 237 238 /** 239 * Closes the region operation lock. 240 */ 241 void closeRegionOperation() throws IOException; 242 243 /** 244 * Closes the region operation lock. This needs to be called in the finally block corresponding to 245 * the try block of {@link #startRegionOperation(Operation)} 246 */ 247 void closeRegionOperation(Operation op) throws IOException; 248 249 // Row write locks 250 251 /** 252 * Row lock held by a given thread. One thread may acquire multiple locks on the same row 253 * simultaneously. The locks must be released by calling release() from the same thread. 254 */ 255 public interface RowLock { 256 /** 257 * Release the given lock. If there are no remaining locks held by the current thread then 258 * unlock the row and allow other threads to acquire the lock. 259 * @throws IllegalArgumentException if called by a different thread than the lock owning thread 260 */ 261 void release(); 262 } 263 264 /** 265 * Get a row lock for the specified row. All locks are reentrant. Before calling this function 266 * make sure that a region operation has already been started (the calling thread has already 267 * acquired the region-close-guard lock). 268 * <p> 269 * The obtained locks should be released after use by {@link RowLock#release()} 270 * <p> 271 * NOTE: the boolean passed here has changed. It used to be a boolean that stated whether or not 272 * to wait on the lock. Now it is whether it an exclusive lock is requested. 273 * @param row The row actions will be performed against 274 * @param readLock is the lock reader or writer. True indicates that a non-exclusive lock is 275 * requested 276 * @see #startRegionOperation() 277 * @see #startRegionOperation(Operation) 278 */ 279 RowLock getRowLock(byte[] row, boolean readLock) throws IOException; 280 281 /////////////////////////////////////////////////////////////////////////// 282 // Region operations 283 284 /** 285 * Perform one or more append operations on a row. 286 * @return result of the operation 287 */ 288 Result append(Append append) throws IOException; 289 290 /** 291 * Perform a batch of mutations. 292 * <p> 293 * Please do not operate on a same column of a single row in a batch, we will not consider the 294 * previous operation in the same batch when performing the operations in the batch. 295 * @param mutations the list of mutations 296 * @return an array of OperationStatus which internally contains the OperationStatusCode and the 297 * exceptionMessage if any. 298 */ 299 OperationStatus[] batchMutate(Mutation[] mutations) throws IOException; 300 301 /** 302 * Atomically checks if a row/family/qualifier value matches the expected value and if it does, it 303 * performs the mutation. If the passed value is null, the lack of column value (ie: 304 * non-existence) is used. See checkAndRowMutate to do many checkAndPuts at a time on a single 305 * row. 306 * @param row to check 307 * @param family column family to check 308 * @param qualifier column qualifier to check 309 * @param op the comparison operator 310 * @param comparator the expected value 311 * @param mutation data to put if check succeeds 312 * @return true if mutation was applied, false otherwise 313 * @deprecated since 3.0.0 and will be removed in 4.0.0. Use 314 * {@link #checkAndMutate(CheckAndMutate)} instead. 315 */ 316 @Deprecated 317 default boolean checkAndMutate(byte[] row, byte[] family, byte[] qualifier, CompareOperator op, 318 ByteArrayComparable comparator, Mutation mutation) throws IOException { 319 return checkAndMutate(row, family, qualifier, op, comparator, TimeRange.allTime(), mutation); 320 } 321 322 /** 323 * Atomically checks if a row/family/qualifier value matches the expected value and if it does, it 324 * performs the mutation. If the passed value is null, the lack of column value (ie: 325 * non-existence) is used. See checkAndRowMutate to do many checkAndPuts at a time on a single 326 * row. 327 * @param row to check 328 * @param family column family to check 329 * @param qualifier column qualifier to check 330 * @param op the comparison operator 331 * @param comparator the expected value 332 * @param mutation data to put if check succeeds 333 * @param timeRange time range to check 334 * @return true if mutation was applied, false otherwise 335 * @deprecated since 3.0.0 and will be removed in 4.0.0. Use 336 * {@link #checkAndMutate(CheckAndMutate)} instead. 337 */ 338 @Deprecated 339 boolean checkAndMutate(byte[] row, byte[] family, byte[] qualifier, CompareOperator op, 340 ByteArrayComparable comparator, TimeRange timeRange, Mutation mutation) throws IOException; 341 342 /** 343 * Atomically checks if a row matches the filter and if it does, it performs the mutation. See 344 * checkAndRowMutate to do many checkAndPuts at a time on a single row. 345 * @param row to check 346 * @param filter the filter 347 * @param mutation data to put if check succeeds 348 * @return true if mutation was applied, false otherwise 349 * @deprecated since 3.0.0 and will be removed in 4.0.0. Use 350 * {@link #checkAndMutate(CheckAndMutate)} instead. 351 */ 352 @Deprecated 353 default boolean checkAndMutate(byte[] row, Filter filter, Mutation mutation) throws IOException { 354 return checkAndMutate(row, filter, TimeRange.allTime(), mutation); 355 } 356 357 /** 358 * Atomically checks if a row value matches the filter and if it does, it performs the mutation. 359 * See checkAndRowMutate to do many checkAndPuts at a time on a single row. 360 * @param row to check 361 * @param filter the filter 362 * @param mutation data to put if check succeeds 363 * @param timeRange time range to check 364 * @return true if mutation was applied, false otherwise 365 * @deprecated since 3.0.0 and will be removed in 4.0.0. Use 366 * {@link #checkAndMutate(CheckAndMutate)} instead. 367 */ 368 @Deprecated 369 boolean checkAndMutate(byte[] row, Filter filter, TimeRange timeRange, Mutation mutation) 370 throws IOException; 371 372 /** 373 * Atomically checks if a row/family/qualifier value matches the expected values and if it does, 374 * it performs the row mutations. If the passed value is null, the lack of column value (ie: 375 * non-existence) is used. Use to do many mutations on a single row. Use checkAndMutate to do one 376 * checkAndMutate at a time. 377 * @param row to check 378 * @param family column family to check 379 * @param qualifier column qualifier to check 380 * @param op the comparison operator 381 * @param comparator the expected value 382 * @param mutations data to put if check succeeds 383 * @return true if mutations were applied, false otherwise 384 * @deprecated since 3.0.0 and will be removed in 4.0.0. Use 385 * {@link #checkAndMutate(CheckAndMutate)} instead. 386 */ 387 @Deprecated 388 default boolean checkAndRowMutate(byte[] row, byte[] family, byte[] qualifier, CompareOperator op, 389 ByteArrayComparable comparator, RowMutations mutations) throws IOException { 390 return checkAndRowMutate(row, family, qualifier, op, comparator, TimeRange.allTime(), 391 mutations); 392 } 393 394 /** 395 * Atomically checks if a row/family/qualifier value matches the expected values and if it does, 396 * it performs the row mutations. If the passed value is null, the lack of column value (ie: 397 * non-existence) is used. Use to do many mutations on a single row. Use checkAndMutate to do one 398 * checkAndMutate at a time. 399 * @param row to check 400 * @param family column family to check 401 * @param qualifier column qualifier to check 402 * @param op the comparison operator 403 * @param comparator the expected value 404 * @param mutations data to put if check succeeds 405 * @param timeRange time range to check 406 * @return true if mutations were applied, false otherwise 407 * @deprecated since 3.0.0 and will be removed in 4.0.0. Use 408 * {@link #checkAndMutate(CheckAndMutate)} instead. 409 */ 410 @Deprecated 411 boolean checkAndRowMutate(byte[] row, byte[] family, byte[] qualifier, CompareOperator op, 412 ByteArrayComparable comparator, TimeRange timeRange, RowMutations mutations) throws IOException; 413 414 /** 415 * Atomically checks if a row matches the filter and if it does, it performs the row mutations. 416 * Use to do many mutations on a single row. Use checkAndMutate to do one checkAndMutate at a 417 * time. 418 * @param row to check 419 * @param filter the filter 420 * @param mutations data to put if check succeeds 421 * @return true if mutations were applied, false otherwise 422 * @deprecated since 3.0.0 and will be removed in 4.0.0. Use 423 * {@link #checkAndMutate(CheckAndMutate)} instead. 424 */ 425 @Deprecated 426 default boolean checkAndRowMutate(byte[] row, Filter filter, RowMutations mutations) 427 throws IOException { 428 return checkAndRowMutate(row, filter, TimeRange.allTime(), mutations); 429 } 430 431 /** 432 * Atomically checks if a row matches the filter and if it does, it performs the row mutations. 433 * Use to do many mutations on a single row. Use checkAndMutate to do one checkAndMutate at a 434 * time. 435 * @param row to check 436 * @param filter the filter 437 * @param mutations data to put if check succeeds 438 * @param timeRange time range to check 439 * @return true if mutations were applied, false otherwise 440 * @deprecated since 3.0.0 and will be removed in 4.0.0. Use 441 * {@link #checkAndMutate(CheckAndMutate)} instead. 442 */ 443 @Deprecated 444 boolean checkAndRowMutate(byte[] row, Filter filter, TimeRange timeRange, RowMutations mutations) 445 throws IOException; 446 447 /** 448 * Atomically checks if a row matches the conditions and if it does, it performs the actions. Use 449 * to do many mutations on a single row. Use checkAndMutate to do one checkAndMutate at a time. 450 * @param checkAndMutate the CheckAndMutate object 451 * @return true if mutations were applied, false otherwise 452 * @throws IOException if an error occurred in this method 453 */ 454 CheckAndMutateResult checkAndMutate(CheckAndMutate checkAndMutate) throws IOException; 455 456 /** 457 * Deletes the specified cells/row. 458 */ 459 void delete(Delete delete) throws IOException; 460 461 /** 462 * Do a get based on the get parameter. 463 * @param get query parameters 464 * @return result of the operation 465 */ 466 Result get(Get get) throws IOException; 467 468 /** 469 * Do a get based on the get parameter. 470 * @param get query parameters 471 * @param withCoprocessor invoke coprocessor or not. We don't want to always invoke cp. 472 * @return list of cells resulting from the operation 473 */ 474 List<Cell> get(Get get, boolean withCoprocessor) throws IOException; 475 476 /** 477 * Return an iterator that scans over the HRegion, returning the indicated columns and rows 478 * specified by the {@link Scan}. 479 * <p> 480 * This Iterator must be closed by the caller. 481 * @param scan configured {@link Scan} 482 * @throws IOException read exceptions 483 */ 484 RegionScanner getScanner(Scan scan) throws IOException; 485 486 /** 487 * Return an iterator that scans over the HRegion, returning the indicated columns and rows 488 * specified by the {@link Scan}. The scanner will also include the additional scanners passed 489 * along with the scanners for the specified Scan instance. Should be careful with the usage to 490 * pass additional scanners only within this Region 491 * <p> 492 * This Iterator must be closed by the caller. 493 * @param scan configured {@link Scan} 494 * @param additionalScanners Any additional scanners to be used 495 * @throws IOException read exceptions 496 */ 497 RegionScanner getScanner(Scan scan, List<KeyValueScanner> additionalScanners) throws IOException; 498 499 /** The comparator to be used with the region */ 500 CellComparator getCellComparator(); 501 502 /** 503 * Perform one or more increment operations on a row. 504 * @return result of the operation 505 */ 506 Result increment(Increment increment) throws IOException; 507 508 /** 509 * Performs multiple mutations atomically on a single row. 510 * @param mutations object that specifies the set of mutations to perform atomically 511 * @return results of Increment/Append operations. If no Increment/Append operations, it returns 512 * null 513 */ 514 Result mutateRow(RowMutations mutations) throws IOException; 515 516 /** 517 * Perform atomic mutations within the region. 518 * @param mutations The list of mutations to perform. <code>mutations</code> can contain 519 * operations for multiple rows. Caller has to ensure that all rows are 520 * contained in this region. 521 * @param rowsToLock Rows to lock 522 * @param nonceGroup Optional nonce group of the operation (client Id) 523 * @param nonce Optional nonce of the operation (unique random id to ensure "more 524 * idempotence") If multiple rows are locked care should be taken that 525 * <code>rowsToLock</code> is sorted in order to avoid deadlocks. 526 */ 527 // TODO Should not be exposing with params nonceGroup, nonce. Change when doing the jira for 528 // Changing processRowsWithLocks 529 void mutateRowsWithLocks(Collection<Mutation> mutations, Collection<byte[]> rowsToLock, 530 long nonceGroup, long nonce) throws IOException; 531 532 /** 533 * Puts some data in the table. 534 */ 535 void put(Put put) throws IOException; 536 537 /////////////////////////////////////////////////////////////////////////// 538 // Flushes, compactions, splits, etc. 539 // Wizards only, please 540 541 /** Returns if a given region is in compaction now. */ 542 CompactionState getCompactionState(); 543 544 /** 545 * Request compaction on this region. 546 */ 547 void requestCompaction(String why, int priority, boolean major, 548 CompactionLifeCycleTracker tracker) throws IOException; 549 550 /** 551 * Request compaction for the given family 552 */ 553 void requestCompaction(byte[] family, String why, int priority, boolean major, 554 CompactionLifeCycleTracker tracker) throws IOException; 555 556 /** 557 * Request flush on this region. 558 */ 559 void requestFlush(FlushLifeCycleTracker tracker) throws IOException; 560 561 /** 562 * Wait for all current flushes of the region to complete 563 * @param timeout The maximum time to wait in milliseconds. 564 * @return False when timeout elapsed but flushes are not over. True when flushes are over within 565 * max wait time period. 566 */ 567 boolean waitForFlushes(long timeout); 568 569 /** 570 * @return a read only configuration of this region; throws {@link UnsupportedOperationException} 571 * if you try to set a configuration. 572 */ 573 Configuration getReadOnlyConfiguration(); 574 575 /** 576 * The minimum block size configuration from all relevant column families. This is used when 577 * estimating quota consumption. 578 */ 579 int getMinBlockSizeBytes(); 580}