1 /* 2 * 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 package org.apache.hadoop.hbase.coprocessor; 17 18 import java.io.IOException; 19 import java.util.List; 20 import java.util.NavigableSet; 21 22 import org.apache.hadoop.classification.InterfaceAudience; 23 import org.apache.hadoop.classification.InterfaceStability; 24 import org.apache.hadoop.hbase.Coprocessor; 25 import org.apache.hadoop.hbase.HRegionInfo; 26 import org.apache.hadoop.hbase.KeyValue; 27 import org.apache.hadoop.hbase.client.Append; 28 import org.apache.hadoop.hbase.client.Delete; 29 import org.apache.hadoop.hbase.client.Get; 30 import org.apache.hadoop.hbase.client.Increment; 31 import org.apache.hadoop.hbase.client.Mutation; 32 import org.apache.hadoop.hbase.client.Put; 33 import org.apache.hadoop.hbase.client.Result; 34 import org.apache.hadoop.hbase.client.Scan; 35 import org.apache.hadoop.hbase.filter.CompareFilter.CompareOp; 36 import org.apache.hadoop.hbase.filter.ByteArrayComparable; 37 import org.apache.hadoop.hbase.regionserver.HRegion; 38 import org.apache.hadoop.hbase.regionserver.InternalScanner; 39 import org.apache.hadoop.hbase.regionserver.KeyValueScanner; 40 import org.apache.hadoop.hbase.regionserver.MiniBatchOperationInProgress; 41 import org.apache.hadoop.hbase.regionserver.RegionScanner; 42 import org.apache.hadoop.hbase.regionserver.ScanType; 43 import org.apache.hadoop.hbase.regionserver.Store; 44 import org.apache.hadoop.hbase.regionserver.StoreFile; 45 import org.apache.hadoop.hbase.regionserver.StoreFileScanner; 46 import org.apache.hadoop.hbase.regionserver.compactions.CompactionRequest; 47 import org.apache.hadoop.hbase.regionserver.wal.HLogKey; 48 import org.apache.hadoop.hbase.regionserver.wal.WALEdit; 49 50 import com.google.common.collect.ImmutableList; 51 import org.apache.hadoop.hbase.util.Pair; 52 53 /** 54 * Coprocessors implement this interface to observe and mediate client actions 55 * on the region. 56 */ 57 @InterfaceAudience.Public 58 @InterfaceStability.Evolving 59 public interface RegionObserver extends Coprocessor { 60 61 /** 62 * Called before the region is reported as open to the master. 63 * @param c the environment provided by the region server 64 * @throws IOException if an error occurred on the coprocessor 65 */ 66 void preOpen(final ObserverContext<RegionCoprocessorEnvironment> c) throws IOException; 67 68 /** 69 * Called after the region is reported as open to the master. 70 * @param c the environment provided by the region server 71 */ 72 void postOpen(final ObserverContext<RegionCoprocessorEnvironment> c); 73 74 /** 75 * Called before a memstore is flushed to disk and prior to creating the scanner to read from 76 * the memstore. To override or modify how a memstore is flushed, 77 * implementing classes can return a new scanner to provide the KeyValues to be 78 * stored into the new {@code StoreFile} or null to perform the default processing. 79 * Calling {@link org.apache.hadoop.hbase.coprocessor.ObserverContext#bypass()} has no 80 * effect in this hook. 81 * @param c the environment provided by the region server 82 * @param store the store being flushed 83 * @param memstoreScanner the scanner for the memstore that is flushed 84 * @param s the base scanner, if not {@code null}, from previous RegionObserver in the chain 85 * @return the scanner to use during the flush. {@code null} if the default implementation 86 * is to be used. 87 * @throws IOException if an error occurred on the coprocessor 88 */ 89 InternalScanner preFlushScannerOpen(final ObserverContext<RegionCoprocessorEnvironment> c, 90 final Store store, final KeyValueScanner memstoreScanner, final InternalScanner s) 91 throws IOException; 92 93 /** 94 * Called before the memstore is flushed to disk. 95 * @param c the environment provided by the region server 96 * @throws IOException if an error occurred on the coprocessor 97 * @deprecated use {@link #preFlush(ObserverContext, Store, InternalScanner)} instead 98 */ 99 void preFlush(final ObserverContext<RegionCoprocessorEnvironment> c) throws IOException; 100 101 /** 102 * Called before a Store's memstore is flushed to disk. 103 * @param c the environment provided by the region server 104 * @param store the store where compaction is being requested 105 * @param scanner the scanner over existing data used in the store file 106 * @return the scanner to use during compaction. Should not be {@code null} 107 * unless the implementation is writing new store files on its own. 108 * @throws IOException if an error occurred on the coprocessor 109 */ 110 InternalScanner preFlush(final ObserverContext<RegionCoprocessorEnvironment> c, final Store store, 111 final InternalScanner scanner) throws IOException; 112 113 /** 114 * Called after the memstore is flushed to disk. 115 * @param c the environment provided by the region server 116 * @throws IOException if an error occurred on the coprocessor 117 * @deprecated use {@link #preFlush(ObserverContext, Store, InternalScanner)} instead. 118 */ 119 void postFlush(final ObserverContext<RegionCoprocessorEnvironment> c) throws IOException; 120 121 /** 122 * Called after a Store's memstore is flushed to disk. 123 * @param c the environment provided by the region server 124 * @param store the store being flushed 125 * @param resultFile the new store file written out during compaction 126 * @throws IOException if an error occurred on the coprocessor 127 */ 128 void postFlush(final ObserverContext<RegionCoprocessorEnvironment> c, final Store store, 129 final StoreFile resultFile) throws IOException; 130 131 /** 132 * Called prior to selecting the {@link StoreFile StoreFiles} to compact from the list of 133 * available candidates. To alter the files used for compaction, you may mutate the passed in list 134 * of candidates. 135 * @param c the environment provided by the region server 136 * @param store the store where compaction is being requested 137 * @param candidates the store files currently available for compaction 138 * @param request custom compaction request 139 * @throws IOException if an error occurred on the coprocessor 140 */ 141 void preCompactSelection(final ObserverContext<RegionCoprocessorEnvironment> c, 142 final Store store, final List<StoreFile> candidates, final CompactionRequest request) 143 throws IOException; 144 145 /** 146 * Called prior to selecting the {@link StoreFile}s to compact from the list of available 147 * candidates. To alter the files used for compaction, you may mutate the passed in list of 148 * candidates. 149 * @param c the environment provided by the region server 150 * @param store the store where compaction is being requested 151 * @param candidates the store files currently available for compaction 152 * @throws IOException if an error occurred on the coprocessor 153 * @deprecated Use {@link #preCompactSelection(ObserverContext, Store, List, CompactionRequest)} 154 * instead 155 */ 156 @Deprecated 157 void preCompactSelection(final ObserverContext<RegionCoprocessorEnvironment> c, 158 final Store store, final List<StoreFile> candidates) throws IOException; 159 160 /** 161 * Called after the {@link StoreFile}s to compact have been selected from the available 162 * candidates. 163 * @param c the environment provided by the region server 164 * @param store the store being compacted 165 * @param selected the store files selected to compact 166 * @param request custom compaction request 167 */ 168 void postCompactSelection(final ObserverContext<RegionCoprocessorEnvironment> c, 169 final Store store, final ImmutableList<StoreFile> selected, CompactionRequest request); 170 171 /** 172 * Called after the {@link StoreFile}s to compact have been selected from the available 173 * candidates. 174 * @param c the environment provided by the region server 175 * @param store the store being compacted 176 * @param selected the store files selected to compact 177 * @deprecated use {@link #postCompactSelection(ObserverContext, Store, ImmutableList, 178 * CompactionRequest)} instead. 179 */ 180 @Deprecated 181 void postCompactSelection(final ObserverContext<RegionCoprocessorEnvironment> c, 182 final Store store, final ImmutableList<StoreFile> selected); 183 184 /** 185 * Called prior to writing the {@link StoreFile}s selected for compaction into a new 186 * {@code StoreFile}. To override or modify the compaction process, implementing classes have two 187 * options: 188 * <ul> 189 * <li>Wrap the provided {@link InternalScanner} with a custom implementation that is returned 190 * from this method. The custom scanner can then inspect {@link KeyValue}s from the wrapped 191 * scanner, applying its own policy to what gets written.</li> 192 * <li>Call {@link org.apache.hadoop.hbase.coprocessor.ObserverContext#bypass()} and provide a 193 * custom implementation for writing of new {@link StoreFile}s. <strong>Note: any implementations 194 * bypassing core compaction using this approach must write out new store files themselves or the 195 * existing data will no longer be available after compaction.</strong></li> 196 * </ul> 197 * @param c the environment provided by the region server 198 * @param store the store being compacted 199 * @param scanner the scanner over existing data used in the store file rewriting 200 * @param scanType type of Scan 201 * @param request the requested compaction 202 * @return the scanner to use during compaction. Should not be {@code null} unless the 203 * implementation is writing new store files on its own. 204 * @throws IOException if an error occurred on the coprocessor 205 */ 206 InternalScanner preCompact(final ObserverContext<RegionCoprocessorEnvironment> c, 207 final Store store, final InternalScanner scanner, final ScanType scanType, 208 CompactionRequest request) throws IOException; 209 210 /** 211 * Called prior to writing the {@link StoreFile}s selected for compaction into a new 212 * {@code StoreFile}. To override or modify the compaction process, implementing classes have two 213 * options: 214 * <ul> 215 * <li>Wrap the provided {@link InternalScanner} with a custom implementation that is returned 216 * from this method. The custom scanner can then inspect {@link KeyValue}s from the wrapped 217 * scanner, applying its own policy to what gets written.</li> 218 * <li>Call {@link org.apache.hadoop.hbase.coprocessor.ObserverContext#bypass()} and provide a 219 * custom implementation for writing of new {@link StoreFile}s. <strong>Note: any implementations 220 * bypassing core compaction using this approach must write out new store files themselves or the 221 * existing data will no longer be available after compaction.</strong></li> 222 * </ul> 223 * @param c the environment provided by the region server 224 * @param store the store being compacted 225 * @param scanner the scanner over existing data used in the store file rewriting 226 * @param scanType type of Scan 227 * @return the scanner to use during compaction. Should not be {@code null} unless the 228 * implementation is writing new store files on its own. 229 * @throws IOException if an error occurred on the coprocessor 230 * @deprecated use 231 * {@link #preCompact(ObserverContext, Store, InternalScanner, 232 * ScanType, CompactionRequest)} instead 233 */ 234 @Deprecated 235 InternalScanner preCompact(final ObserverContext<RegionCoprocessorEnvironment> c, 236 final Store store, final InternalScanner scanner, final ScanType scanType) throws IOException; 237 238 /** 239 * Called prior to writing the {@link StoreFile}s selected for compaction into a new 240 * {@code StoreFile} and prior to creating the scanner used to read the input files. To override 241 * or modify the compaction process, implementing classes can return a new scanner to provide the 242 * KeyValues to be stored into the new {@code StoreFile} or null to perform the default 243 * processing. Calling {@link org.apache.hadoop.hbase.coprocessor.ObserverContext#bypass()} has no 244 * effect in this hook. 245 * @param c the environment provided by the region server 246 * @param store the store being compacted 247 * @param scanners the list {@link StoreFileScanner}s to be read from 248 * @param scanType the {@link ScanType} indicating whether this is a major or minor compaction 249 * @param earliestPutTs timestamp of the earliest put that was found in any of the involved store 250 * files 251 * @param s the base scanner, if not {@code null}, from previous RegionObserver in the chain 252 * @param request the requested compaction 253 * @return the scanner to use during compaction. {@code null} if the default implementation is to 254 * be used. 255 * @throws IOException if an error occurred on the coprocessor 256 */ 257 InternalScanner preCompactScannerOpen(final ObserverContext<RegionCoprocessorEnvironment> c, 258 final Store store, List<? extends KeyValueScanner> scanners, final ScanType scanType, 259 final long earliestPutTs, final InternalScanner s, CompactionRequest request) 260 throws IOException; 261 262 /** 263 * Called prior to writing the {@link StoreFile}s selected for compaction into a new 264 * {@code StoreFile} and prior to creating the scanner used to read the input files. To override 265 * or modify the compaction process, implementing classes can return a new scanner to provide the 266 * KeyValues to be stored into the new {@code StoreFile} or null to perform the default 267 * processing. Calling {@link org.apache.hadoop.hbase.coprocessor.ObserverContext#bypass()} has no 268 * effect in this hook. 269 * @param c the environment provided by the region server 270 * @param store the store being compacted 271 * @param scanners the list {@link StoreFileScanner}s to be read from 272 * @param scanType the {@link ScanType} indicating whether this is a major or minor compaction 273 * @param earliestPutTs timestamp of the earliest put that was found in any of the involved store 274 * files 275 * @param s the base scanner, if not {@code null}, from previous RegionObserver in the chain 276 * @return the scanner to use during compaction. {@code null} if the default implementation is to 277 * be used. 278 * @throws IOException if an error occurred on the coprocessor 279 * @deprecated Use 280 * {@link #preCompactScannerOpen(ObserverContext, Store, List, ScanType, long, 281 * InternalScanner, CompactionRequest)} instead. 282 */ 283 @Deprecated 284 InternalScanner preCompactScannerOpen(final ObserverContext<RegionCoprocessorEnvironment> c, 285 final Store store, List<? extends KeyValueScanner> scanners, final ScanType scanType, 286 final long earliestPutTs, final InternalScanner s) throws IOException; 287 288 /** 289 * Called after compaction has completed and the new store file has been moved in to place. 290 * @param c the environment provided by the region server 291 * @param store the store being compacted 292 * @param resultFile the new store file written out during compaction 293 * @param request the requested compaction 294 * @throws IOException if an error occurred on the coprocessor 295 */ 296 void postCompact(final ObserverContext<RegionCoprocessorEnvironment> c, final Store store, 297 StoreFile resultFile, CompactionRequest request) throws IOException; 298 299 /** 300 * Called after compaction has completed and the new store file has been moved in to place. 301 * @param c the environment provided by the region server 302 * @param store the store being compacted 303 * @param resultFile the new store file written out during compaction 304 * @throws IOException if an error occurred on the coprocessor 305 * @deprecated Use {@link #postCompact(ObserverContext, Store, StoreFile, CompactionRequest)} 306 * instead 307 */ 308 @Deprecated 309 void postCompact(final ObserverContext<RegionCoprocessorEnvironment> c, final Store store, 310 StoreFile resultFile) throws IOException; 311 312 /** 313 * Called before the region is split. 314 * @param c the environment provided by the region server 315 * (e.getRegion() returns the parent region) 316 * @throws IOException if an error occurred on the coprocessor 317 * @deprecated Use preSplit( 318 * final ObserverContext<RegionCoprocessorEnvironment> c, byte[] splitRow) 319 */ 320 void preSplit(final ObserverContext<RegionCoprocessorEnvironment> c) throws IOException; 321 322 /** 323 * Called before the region is split. 324 * @param c the environment provided by the region server 325 * (e.getRegion() returns the parent region) 326 * @throws IOException if an error occurred on the coprocessor 327 */ 328 void preSplit(final ObserverContext<RegionCoprocessorEnvironment> c, byte[] splitRow) 329 throws IOException; 330 331 /** 332 * Called after the region is split. 333 * @param c the environment provided by the region server 334 * (e.getRegion() returns the parent region) 335 * @param l the left daughter region 336 * @param r the right daughter region 337 * @throws IOException if an error occurred on the coprocessor 338 * @deprecated Use postCompleteSplit() instead 339 */ 340 void postSplit(final ObserverContext<RegionCoprocessorEnvironment> c, final HRegion l, 341 final HRegion r) throws IOException; 342 343 /** 344 * This will be called before the roll back of the split region is completed 345 * @param ctx 346 * @throws IOException 347 */ 348 void preRollBackSplit(final ObserverContext<RegionCoprocessorEnvironment> ctx) throws IOException; 349 350 /** 351 * This will be called after the roll back of the split region is completed 352 * @param ctx 353 * @throws IOException 354 */ 355 void postRollBackSplit(final ObserverContext<RegionCoprocessorEnvironment> ctx) 356 throws IOException; 357 358 /** 359 * Called after any split request is processed. This will be called irrespective of success or 360 * failure of the split. 361 * @param ctx 362 * @throws IOException 363 */ 364 void postCompleteSplit(final ObserverContext<RegionCoprocessorEnvironment> ctx) 365 throws IOException; 366 /** 367 * Called before the region is reported as closed to the master. 368 * @param c the environment provided by the region server 369 * @param abortRequested true if the region server is aborting 370 * @throws IOException 371 */ 372 void preClose(final ObserverContext<RegionCoprocessorEnvironment> c, 373 boolean abortRequested) throws IOException; 374 375 /** 376 * Called after the region is reported as closed to the master. 377 * @param c the environment provided by the region server 378 * @param abortRequested true if the region server is aborting 379 */ 380 void postClose(final ObserverContext<RegionCoprocessorEnvironment> c, 381 boolean abortRequested); 382 383 /** 384 * Called before a client makes a GetClosestRowBefore request. 385 * <p> 386 * Call CoprocessorEnvironment#bypass to skip default actions 387 * <p> 388 * Call CoprocessorEnvironment#complete to skip any subsequent chained 389 * coprocessors 390 * @param c the environment provided by the region server 391 * @param row the row 392 * @param family the family 393 * @param result The result to return to the client if default processing 394 * is bypassed. Can be modified. Will not be used if default processing 395 * is not bypassed. 396 * @throws IOException if an error occurred on the coprocessor 397 */ 398 void preGetClosestRowBefore(final ObserverContext<RegionCoprocessorEnvironment> c, 399 final byte [] row, final byte [] family, final Result result) 400 throws IOException; 401 402 /** 403 * Called after a client makes a GetClosestRowBefore request. 404 * <p> 405 * Call CoprocessorEnvironment#complete to skip any subsequent chained 406 * coprocessors 407 * @param c the environment provided by the region server 408 * @param row the row 409 * @param family the desired family 410 * @param result the result to return to the client, modify as necessary 411 * @throws IOException if an error occurred on the coprocessor 412 */ 413 void postGetClosestRowBefore(final ObserverContext<RegionCoprocessorEnvironment> c, 414 final byte [] row, final byte [] family, final Result result) 415 throws IOException; 416 417 /** 418 * Called before the client performs a Get 419 * <p> 420 * Call CoprocessorEnvironment#bypass to skip default actions 421 * <p> 422 * Call CoprocessorEnvironment#complete to skip any subsequent chained 423 * coprocessors 424 * @param c the environment provided by the region server 425 * @param get the Get request 426 * @param result The result to return to the client if default processing 427 * is bypassed. Can be modified. Will not be used if default processing 428 * is not bypassed. 429 * @throws IOException if an error occurred on the coprocessor 430 */ 431 void preGet(final ObserverContext<RegionCoprocessorEnvironment> c, final Get get, 432 final List<KeyValue> result) 433 throws IOException; 434 435 /** 436 * Called after the client performs a Get 437 * <p> 438 * Call CoprocessorEnvironment#complete to skip any subsequent chained 439 * coprocessors 440 * @param c the environment provided by the region server 441 * @param get the Get request 442 * @param result the result to return to the client, modify as necessary 443 * @throws IOException if an error occurred on the coprocessor 444 */ 445 void postGet(final ObserverContext<RegionCoprocessorEnvironment> c, final Get get, 446 final List<KeyValue> result) 447 throws IOException; 448 449 /** 450 * Called before the client tests for existence using a Get. 451 * <p> 452 * Call CoprocessorEnvironment#bypass to skip default actions 453 * <p> 454 * Call CoprocessorEnvironment#complete to skip any subsequent chained 455 * coprocessors 456 * @param c the environment provided by the region server 457 * @param get the Get request 458 * @param exists 459 * @return the value to return to the client if bypassing default processing 460 * @throws IOException if an error occurred on the coprocessor 461 */ 462 boolean preExists(final ObserverContext<RegionCoprocessorEnvironment> c, final Get get, 463 final boolean exists) 464 throws IOException; 465 466 /** 467 * Called after the client tests for existence using a Get. 468 * <p> 469 * Call CoprocessorEnvironment#complete to skip any subsequent chained 470 * coprocessors 471 * @param c the environment provided by the region server 472 * @param get the Get request 473 * @param exists the result returned by the region server 474 * @return the result to return to the client 475 * @throws IOException if an error occurred on the coprocessor 476 */ 477 boolean postExists(final ObserverContext<RegionCoprocessorEnvironment> c, final Get get, 478 final boolean exists) 479 throws IOException; 480 481 /** 482 * Called before the client stores a value. 483 * <p> 484 * Call CoprocessorEnvironment#bypass to skip default actions 485 * <p> 486 * Call CoprocessorEnvironment#complete to skip any subsequent chained 487 * coprocessors 488 * @param c the environment provided by the region server 489 * @param put The Put object 490 * @param edit The WALEdit object that will be written to the wal 491 * @param writeToWAL true if the change should be written to the WAL 492 * @throws IOException if an error occurred on the coprocessor 493 */ 494 void prePut(final ObserverContext<RegionCoprocessorEnvironment> c, 495 final Put put, final WALEdit edit, final boolean writeToWAL) 496 throws IOException; 497 498 /** 499 * Called after the client stores a value. 500 * <p> 501 * Call CoprocessorEnvironment#complete to skip any subsequent chained 502 * coprocessors 503 * @param c the environment provided by the region server 504 * @param put The Put object 505 * @param edit The WALEdit object for the wal 506 * @param writeToWAL true if the change should be written to the WAL 507 * @throws IOException if an error occurred on the coprocessor 508 */ 509 void postPut(final ObserverContext<RegionCoprocessorEnvironment> c, 510 final Put put, final WALEdit edit, final boolean writeToWAL) 511 throws IOException; 512 513 /** 514 * Called before the client deletes a value. 515 * <p> 516 * Call CoprocessorEnvironment#bypass to skip default actions 517 * <p> 518 * Call CoprocessorEnvironment#complete to skip any subsequent chained 519 * coprocessors 520 * @param c the environment provided by the region server 521 * @param delete The Delete object 522 * @param edit The WALEdit object for the wal 523 * @param writeToWAL true if the change should be written to the WAL 524 * @throws IOException if an error occurred on the coprocessor 525 */ 526 void preDelete(final ObserverContext<RegionCoprocessorEnvironment> c, 527 final Delete delete, final WALEdit edit, final boolean writeToWAL) 528 throws IOException; 529 530 /** 531 * Called after the client deletes a value. 532 * <p> 533 * Call CoprocessorEnvironment#complete to skip any subsequent chained 534 * coprocessors 535 * @param c the environment provided by the region server 536 * @param delete The Delete object 537 * @param edit The WALEdit object for the wal 538 * @param writeToWAL true if the change should be written to the WAL 539 * @throws IOException if an error occurred on the coprocessor 540 */ 541 void postDelete(final ObserverContext<RegionCoprocessorEnvironment> c, 542 final Delete delete, final WALEdit edit, final boolean writeToWAL) 543 throws IOException; 544 545 /** 546 * This will be called for every batch mutation operation happening at the server. This will be 547 * called after acquiring the locks on the mutating rows and after applying the proper timestamp 548 * for each Mutation at the server. The batch may contain Put/Delete. By setting OperationStatus 549 * of Mutations ({@link MiniBatchOperationInProgress#setOperationStatus(int, OperationStatus)}), 550 * {@link RegionObserver} can make HRegion to skip these Mutations. 551 * @param c the environment provided by the region server 552 * @param miniBatchOp batch of Mutations getting applied to region. 553 * @throws IOException if an error occurred on the coprocessor 554 */ 555 void preBatchMutate(final ObserverContext<RegionCoprocessorEnvironment> c, 556 final MiniBatchOperationInProgress<Pair<Mutation, Integer>> miniBatchOp) throws IOException; 557 558 /** 559 * This will be called after applying a batch of Mutations on a region. The Mutations are added to 560 * memstore and WAL. 561 * @param c the environment provided by the region server 562 * @param miniBatchOp batch of Mutations applied to region. 563 * @throws IOException if an error occurred on the coprocessor 564 */ 565 void postBatchMutate(final ObserverContext<RegionCoprocessorEnvironment> c, 566 final MiniBatchOperationInProgress<Pair<Mutation, Integer>> miniBatchOp) throws IOException; 567 568 /** 569 * Called before checkAndPut 570 * <p> 571 * Call CoprocessorEnvironment#bypass to skip default actions 572 * <p> 573 * Call CoprocessorEnvironment#complete to skip any subsequent chained 574 * coprocessors 575 * @param c the environment provided by the region server 576 * @param row row to check 577 * @param family column family 578 * @param qualifier column qualifier 579 * @param compareOp the comparison operation 580 * @param comparator the comparator 581 * @param put data to put if check succeeds 582 * @param result 583 * @return the return value to return to client if bypassing default 584 * processing 585 * @throws IOException if an error occurred on the coprocessor 586 */ 587 boolean preCheckAndPut(final ObserverContext<RegionCoprocessorEnvironment> c, 588 final byte [] row, final byte [] family, final byte [] qualifier, 589 final CompareOp compareOp, final ByteArrayComparable comparator, 590 final Put put, final boolean result) 591 throws IOException; 592 593 /** 594 * Called after checkAndPut 595 * <p> 596 * Call CoprocessorEnvironment#complete to skip any subsequent chained 597 * coprocessors 598 * @param c the environment provided by the region server 599 * @param row row to check 600 * @param family column family 601 * @param qualifier column qualifier 602 * @param compareOp the comparison operation 603 * @param comparator the comparator 604 * @param put data to put if check succeeds 605 * @param result from the checkAndPut 606 * @return the possibly transformed return value to return to client 607 * @throws IOException if an error occurred on the coprocessor 608 */ 609 boolean postCheckAndPut(final ObserverContext<RegionCoprocessorEnvironment> c, 610 final byte [] row, final byte [] family, final byte [] qualifier, 611 final CompareOp compareOp, final ByteArrayComparable comparator, 612 final Put put, final boolean result) 613 throws IOException; 614 615 /** 616 * Called before checkAndDelete 617 * <p> 618 * Call CoprocessorEnvironment#bypass to skip default actions 619 * <p> 620 * Call CoprocessorEnvironment#complete to skip any subsequent chained 621 * coprocessors 622 * @param c the environment provided by the region server 623 * @param row row to check 624 * @param family column family 625 * @param qualifier column qualifier 626 * @param compareOp the comparison operation 627 * @param comparator the comparator 628 * @param delete delete to commit if check succeeds 629 * @param result 630 * @return the value to return to client if bypassing default processing 631 * @throws IOException if an error occurred on the coprocessor 632 */ 633 boolean preCheckAndDelete(final ObserverContext<RegionCoprocessorEnvironment> c, 634 final byte [] row, final byte [] family, final byte [] qualifier, 635 final CompareOp compareOp, final ByteArrayComparable comparator, 636 final Delete delete, final boolean result) 637 throws IOException; 638 639 /** 640 * Called after checkAndDelete 641 * <p> 642 * Call CoprocessorEnvironment#complete to skip any subsequent chained 643 * coprocessors 644 * @param c the environment provided by the region server 645 * @param row row to check 646 * @param family column family 647 * @param qualifier column qualifier 648 * @param compareOp the comparison operation 649 * @param comparator the comparator 650 * @param delete delete to commit if check succeeds 651 * @param result from the CheckAndDelete 652 * @return the possibly transformed returned value to return to client 653 * @throws IOException if an error occurred on the coprocessor 654 */ 655 boolean postCheckAndDelete(final ObserverContext<RegionCoprocessorEnvironment> c, 656 final byte [] row, final byte [] family, final byte [] qualifier, 657 final CompareOp compareOp, final ByteArrayComparable comparator, 658 final Delete delete, final boolean result) 659 throws IOException; 660 661 /** 662 * Called before incrementColumnValue 663 * <p> 664 * Call CoprocessorEnvironment#bypass to skip default actions 665 * <p> 666 * Call CoprocessorEnvironment#complete to skip any subsequent chained 667 * coprocessors 668 * @param c the environment provided by the region server 669 * @param row row to check 670 * @param family column family 671 * @param qualifier column qualifier 672 * @param amount long amount to increment 673 * @param writeToWAL true if the change should be written to the WAL 674 * @return value to return to the client if bypassing default processing 675 * @throws IOException if an error occurred on the coprocessor 676 * @deprecated This hook is no longer called by the RegionServer 677 */ 678 @Deprecated 679 long preIncrementColumnValue(final ObserverContext<RegionCoprocessorEnvironment> c, 680 final byte [] row, final byte [] family, final byte [] qualifier, 681 final long amount, final boolean writeToWAL) 682 throws IOException; 683 684 /** 685 * Called after incrementColumnValue 686 * <p> 687 * Call CoprocessorEnvironment#complete to skip any subsequent chained 688 * coprocessors 689 * @param c the environment provided by the region server 690 * @param row row to check 691 * @param family column family 692 * @param qualifier column qualifier 693 * @param amount long amount to increment 694 * @param writeToWAL true if the change should be written to the WAL 695 * @param result the result returned by incrementColumnValue 696 * @return the result to return to the client 697 * @throws IOException if an error occurred on the coprocessor 698 * @deprecated This hook is no longer called by the RegionServer 699 */ 700 @Deprecated 701 long postIncrementColumnValue(final ObserverContext<RegionCoprocessorEnvironment> c, 702 final byte [] row, final byte [] family, final byte [] qualifier, 703 final long amount, final boolean writeToWAL, final long result) 704 throws IOException; 705 706 /** 707 * Called before Append 708 * <p> 709 * Call CoprocessorEnvironment#bypass to skip default actions 710 * <p> 711 * Call CoprocessorEnvironment#complete to skip any subsequent chained 712 * coprocessors 713 * @param c the environment provided by the region server 714 * @param append Append object 715 * @return result to return to the client if bypassing default processing 716 * @throws IOException if an error occurred on the coprocessor 717 */ 718 Result preAppend(final ObserverContext<RegionCoprocessorEnvironment> c, 719 final Append append) 720 throws IOException; 721 722 /** 723 * Called after Append 724 * <p> 725 * Call CoprocessorEnvironment#complete to skip any subsequent chained 726 * coprocessors 727 * @param c the environment provided by the region server 728 * @param append Append object 729 * @param result the result returned by increment 730 * @return the result to return to the client 731 * @throws IOException if an error occurred on the coprocessor 732 */ 733 Result postAppend(final ObserverContext<RegionCoprocessorEnvironment> c, 734 final Append append, final Result result) 735 throws IOException; 736 737 /** 738 * Called before Increment 739 * <p> 740 * Call CoprocessorEnvironment#bypass to skip default actions 741 * <p> 742 * Call CoprocessorEnvironment#complete to skip any subsequent chained 743 * coprocessors 744 * @param c the environment provided by the region server 745 * @param increment increment object 746 * @return result to return to the client if bypassing default processing 747 * @throws IOException if an error occurred on the coprocessor 748 */ 749 Result preIncrement(final ObserverContext<RegionCoprocessorEnvironment> c, 750 final Increment increment) 751 throws IOException; 752 753 /** 754 * Called after increment 755 * <p> 756 * Call CoprocessorEnvironment#complete to skip any subsequent chained 757 * coprocessors 758 * @param c the environment provided by the region server 759 * @param increment increment object 760 * @param result the result returned by increment 761 * @return the result to return to the client 762 * @throws IOException if an error occurred on the coprocessor 763 */ 764 Result postIncrement(final ObserverContext<RegionCoprocessorEnvironment> c, 765 final Increment increment, final Result result) 766 throws IOException; 767 768 /** 769 * Called before the client opens a new scanner. 770 * <p> 771 * Call CoprocessorEnvironment#bypass to skip default actions 772 * <p> 773 * Call CoprocessorEnvironment#complete to skip any subsequent chained 774 * coprocessors 775 * @param c the environment provided by the region server 776 * @param scan the Scan specification 777 * @param s if not null, the base scanner 778 * @return an RegionScanner instance to use instead of the base scanner if 779 * overriding default behavior, null otherwise 780 * @throws IOException if an error occurred on the coprocessor 781 */ 782 RegionScanner preScannerOpen(final ObserverContext<RegionCoprocessorEnvironment> c, 783 final Scan scan, final RegionScanner s) 784 throws IOException; 785 786 /** 787 * Called before a store opens a new scanner. 788 * This hook is called when a "user" scanner is opened. 789 * <p> 790 * See {@link #preFlushScannerOpen(ObserverContext, Store, KeyValueScanner, InternalScanner)} 791 * and {@link #preCompactScannerOpen(ObserverContext, 792 * Store, List, ScanType, long, InternalScanner)} 793 * to override scanners created for flushes or compactions, resp. 794 * <p> 795 * Call CoprocessorEnvironment#complete to skip any subsequent chained 796 * coprocessors. 797 * Calling {@link org.apache.hadoop.hbase.coprocessor.ObserverContext#bypass()} has no 798 * effect in this hook. 799 * @param c the environment provided by the region server 800 * @param store the store being scanned 801 * @param scan the Scan specification 802 * @param targetCols columns to be used in the scanner 803 * @param s the base scanner, if not {@code null}, from previous RegionObserver in the chain 804 * @return a KeyValueScanner instance to use or {@code null} to use the default implementation 805 * @throws IOException if an error occurred on the coprocessor 806 */ 807 KeyValueScanner preStoreScannerOpen(final ObserverContext<RegionCoprocessorEnvironment> c, 808 final Store store, final Scan scan, final NavigableSet<byte[]> targetCols, 809 final KeyValueScanner s) throws IOException; 810 811 /** 812 * Called after the client opens a new scanner. 813 * <p> 814 * Call CoprocessorEnvironment#complete to skip any subsequent chained 815 * coprocessors 816 * @param c the environment provided by the region server 817 * @param scan the Scan specification 818 * @param s if not null, the base scanner 819 * @return the scanner instance to use 820 * @throws IOException if an error occurred on the coprocessor 821 */ 822 RegionScanner postScannerOpen(final ObserverContext<RegionCoprocessorEnvironment> c, 823 final Scan scan, final RegionScanner s) 824 throws IOException; 825 826 /** 827 * Called before the client asks for the next row on a scanner. 828 * <p> 829 * Call CoprocessorEnvironment#bypass to skip default actions 830 * <p> 831 * Call CoprocessorEnvironment#complete to skip any subsequent chained 832 * coprocessors 833 * @param c the environment provided by the region server 834 * @param s the scanner 835 * @param result The result to return to the client if default processing 836 * is bypassed. Can be modified. Will not be returned if default processing 837 * is not bypassed. 838 * @param limit the maximum number of results to return 839 * @param hasNext the 'has more' indication 840 * @return 'has more' indication that should be sent to client 841 * @throws IOException if an error occurred on the coprocessor 842 */ 843 boolean preScannerNext(final ObserverContext<RegionCoprocessorEnvironment> c, 844 final InternalScanner s, final List<Result> result, 845 final int limit, final boolean hasNext) 846 throws IOException; 847 848 /** 849 * Called after the client asks for the next row on a scanner. 850 * <p> 851 * Call CoprocessorEnvironment#complete to skip any subsequent chained 852 * coprocessors 853 * @param c the environment provided by the region server 854 * @param s the scanner 855 * @param result the result to return to the client, can be modified 856 * @param limit the maximum number of results to return 857 * @param hasNext the 'has more' indication 858 * @return 'has more' indication that should be sent to client 859 * @throws IOException if an error occurred on the coprocessor 860 */ 861 boolean postScannerNext(final ObserverContext<RegionCoprocessorEnvironment> c, 862 final InternalScanner s, final List<Result> result, final int limit, 863 final boolean hasNext) 864 throws IOException; 865 866 /** 867 * This will be called by the scan flow when the current scanned row is being filtered out by the 868 * filter. The filter may be filtering out the row via any of the below scenarios 869 * <ol> 870 * <li> 871 * <code>boolean filterRowKey(byte [] buffer, int offset, int length)</code> returning true</li> 872 * <li> 873 * <code>boolean filterRow()</code> returning true</li> 874 * <li> 875 * <code>void filterRow(List<KeyValue> kvs)</code> removing all the kvs from the passed List</li> 876 * </ol> 877 * @param c the environment provided by the region server 878 * @param s the scanner 879 * @param currentRow The current rowkey which got filtered out 880 * @param hasMore the 'has more' indication 881 * @return whether more rows are available for the scanner or not 882 * @throws IOException 883 */ 884 boolean postScannerFilterRow(final ObserverContext<RegionCoprocessorEnvironment> c, 885 final InternalScanner s, final byte[] currentRow, final boolean hasMore) throws IOException; 886 887 /** 888 * Called before the client closes a scanner. 889 * <p> 890 * Call CoprocessorEnvironment#bypass to skip default actions 891 * <p> 892 * Call CoprocessorEnvironment#complete to skip any subsequent chained 893 * coprocessors 894 * @param c the environment provided by the region server 895 * @param s the scanner 896 * @throws IOException if an error occurred on the coprocessor 897 */ 898 void preScannerClose(final ObserverContext<RegionCoprocessorEnvironment> c, 899 final InternalScanner s) 900 throws IOException; 901 902 /** 903 * Called after the client closes a scanner. 904 * <p> 905 * Call CoprocessorEnvironment#complete to skip any subsequent chained 906 * coprocessors 907 * @param c the environment provided by the region server 908 * @param s the scanner 909 * @throws IOException if an error occurred on the coprocessor 910 */ 911 void postScannerClose(final ObserverContext<RegionCoprocessorEnvironment> c, 912 final InternalScanner s) 913 throws IOException; 914 915 /** 916 * Called before a {@link org.apache.hadoop.hbase.regionserver.wal.WALEdit} 917 * replayed for this region. 918 * 919 * @param ctx 920 * @param info 921 * @param logKey 922 * @param logEdit 923 * @throws IOException 924 */ 925 void preWALRestore(final ObserverContext<RegionCoprocessorEnvironment> ctx, 926 HRegionInfo info, HLogKey logKey, WALEdit logEdit) throws IOException; 927 928 /** 929 * Called after a {@link org.apache.hadoop.hbase.regionserver.wal.WALEdit} 930 * replayed for this region. 931 * 932 * @param ctx 933 * @param info 934 * @param logKey 935 * @param logEdit 936 * @throws IOException 937 */ 938 void postWALRestore(final ObserverContext<RegionCoprocessorEnvironment> ctx, 939 HRegionInfo info, HLogKey logKey, WALEdit logEdit) throws IOException; 940 941 /** 942 * Called before bulkLoadHFile. Users can create a StoreFile instance to 943 * access the contents of a HFile. 944 * 945 * @param ctx 946 * @param familyPaths pairs of { CF, HFile path } submitted for bulk load. Adding 947 * or removing from this list will add or remove HFiles to be bulk loaded. 948 * @throws IOException 949 */ 950 void preBulkLoadHFile(final ObserverContext<RegionCoprocessorEnvironment> ctx, 951 List<Pair<byte[], String>> familyPaths) throws IOException; 952 953 /** 954 * Called after bulkLoadHFile. 955 * 956 * @param ctx 957 * @param familyPaths pairs of { CF, HFile path } submitted for bulk load 958 * @param hasLoaded whether the bulkLoad was successful 959 * @return the new value of hasLoaded 960 * @throws IOException 961 */ 962 boolean postBulkLoadHFile(final ObserverContext<RegionCoprocessorEnvironment> ctx, 963 List<Pair<byte[], String>> familyPaths, boolean hasLoaded) throws IOException; 964 }