1 /*
2 * Copyright 2010 The Apache Software Foundation
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package org.apache.hadoop.hbase.coprocessor;
18
19 import java.util.List;
20 import java.util.Map;
21
22 import com.google.common.collect.ImmutableList;
23 import org.apache.hadoop.hbase.Coprocessor;
24 import org.apache.hadoop.hbase.HRegionInfo;
25 import org.apache.hadoop.hbase.KeyValue;
26 import org.apache.hadoop.hbase.client.Delete;
27 import org.apache.hadoop.hbase.client.Get;
28 import org.apache.hadoop.hbase.client.Put;
29 import org.apache.hadoop.hbase.client.Result;
30 import org.apache.hadoop.hbase.client.Scan;
31 import org.apache.hadoop.hbase.client.Increment;
32 import org.apache.hadoop.hbase.filter.CompareFilter.CompareOp;
33 import org.apache.hadoop.hbase.filter.WritableByteArrayComparable;
34 import org.apache.hadoop.hbase.regionserver.HRegion;
35 import org.apache.hadoop.hbase.regionserver.InternalScanner;
36 import org.apache.hadoop.hbase.regionserver.RegionScanner;
37 import org.apache.hadoop.hbase.regionserver.Store;
38 import org.apache.hadoop.hbase.regionserver.StoreFile;
39 import org.apache.hadoop.hbase.regionserver.wal.HLogKey;
40 import org.apache.hadoop.hbase.regionserver.wal.WALEdit;
41
42 import java.io.IOException;
43
44 /**
45 * Coprocessors implement this interface to observe and mediate client actions
46 * on the region.
47 */
48 public interface RegionObserver extends Coprocessor {
49
50 /**
51 * Called before the region is reported as open to the master.
52 * @param c the environment provided by the region server
53 */
54 void preOpen(final ObserverContext<RegionCoprocessorEnvironment> c);
55
56 /**
57 * Called after the region is reported as open to the master.
58 * @param c the environment provided by the region server
59 */
60 void postOpen(final ObserverContext<RegionCoprocessorEnvironment> c);
61
62 /**
63 * Called before the memstore is flushed to disk.
64 * @param c the environment provided by the region server
65 */
66 void preFlush(final ObserverContext<RegionCoprocessorEnvironment> c);
67
68 /**
69 * Called after the memstore is flushed to disk.
70 * @param c the environment provided by the region server
71 */
72 void postFlush(final ObserverContext<RegionCoprocessorEnvironment> c);
73
74 /**
75 * Called prior to selecting the {@link StoreFile}s to compact from the list
76 * of available candidates. To alter the files used for compaction, you may
77 * mutate the passed in list of candidates.
78 * @param c the environment provided by the region server
79 * @param store the store where compaction is being requested
80 * @param candidates the store files currently available for compaction
81 */
82 void preCompactSelection(final ObserverContext<RegionCoprocessorEnvironment> c,
83 final Store store, final List<StoreFile> candidates);
84
85 /**
86 * Called after the {@link StoreFile}s to compact have been selected from the
87 * available candidates.
88 * @param c the environment provided by the region server
89 * @param store the store being compacted
90 * @param selected the store files selected to compact
91 */
92 void postCompactSelection(final ObserverContext<RegionCoprocessorEnvironment> c,
93 final Store store, final ImmutableList<StoreFile> selected);
94
95 /**
96 * Called prior to writing the {@link StoreFile}s selected for compaction into
97 * a new {@code StoreFile}. To override or modify the compaction process,
98 * implementing classes have two options:
99 * <ul>
100 * <li>Wrap the provided {@link InternalScanner} with a custom
101 * implementation that is returned from this method. The custom scanner
102 * can then inspect {@link KeyValue}s from the wrapped scanner, applying
103 * its own policy to what gets written.</li>
104 * <li>Call {@link org.apache.hadoop.hbase.coprocessor.ObserverContext#bypass()}
105 * and provide a custom implementation for writing of new
106 * {@link StoreFile}s. <strong>Note: any implementations bypassing
107 * core compaction using this approach must write out new store files
108 * themselves or the existing data will no longer be available after
109 * compaction.</strong></li>
110 * </ul>
111 * @param c the environment provided by the region server
112 * @param store the store being compacted
113 * @param scanner the scanner over existing data used in the store file
114 * rewriting
115 * @return the scanner to use during compaction. Should not be {@code null}
116 * unless the implementation is writing new store files on its own.
117 */
118 InternalScanner preCompact(final ObserverContext<RegionCoprocessorEnvironment> c,
119 final Store store, final InternalScanner scanner);
120
121 /**
122 * Called after compaction has completed and the new store file has been
123 * moved in to place.
124 * @param c the environment provided by the region server
125 * @param store the store being compacted
126 * @param resultFile the new store file written out during compaction
127 */
128 void postCompact(final ObserverContext<RegionCoprocessorEnvironment> c,
129 final Store store, StoreFile resultFile);
130
131 /**
132 * Called before the region is split.
133 * @param c the environment provided by the region server
134 * (e.getRegion() returns the parent region)
135 */
136 void preSplit(final ObserverContext<RegionCoprocessorEnvironment> c);
137
138 /**
139 * Called after the region is split.
140 * @param c the environment provided by the region server
141 * (e.getRegion() returns the parent region)
142 * @param l the left daughter region
143 * @param r the right daughter region
144 */
145 void postSplit(final ObserverContext<RegionCoprocessorEnvironment> c, final HRegion l,
146 final HRegion r);
147
148 /**
149 * Called before the region is reported as closed to the master.
150 * @param c the environment provided by the region server
151 * @param abortRequested true if the region server is aborting
152 */
153 void preClose(final ObserverContext<RegionCoprocessorEnvironment> c,
154 boolean abortRequested);
155
156 /**
157 * Called after the region is reported as closed to the master.
158 * @param c the environment provided by the region server
159 * @param abortRequested true if the region server is aborting
160 */
161 void postClose(final ObserverContext<RegionCoprocessorEnvironment> c,
162 boolean abortRequested);
163
164 /**
165 * Called before a client makes a GetClosestRowBefore request.
166 * <p>
167 * Call CoprocessorEnvironment#bypass to skip default actions
168 * <p>
169 * Call CoprocessorEnvironment#complete to skip any subsequent chained
170 * coprocessors
171 * @param c the environment provided by the region server
172 * @param row the row
173 * @param family the family
174 * @param result The result to return to the client if default processing
175 * is bypassed. Can be modified. Will not be used if default processing
176 * is not bypassed.
177 * @throws IOException if an error occurred on the coprocessor
178 */
179 void preGetClosestRowBefore(final ObserverContext<RegionCoprocessorEnvironment> c,
180 final byte [] row, final byte [] family, final Result result)
181 throws IOException;
182
183 /**
184 * Called after a client makes a GetClosestRowBefore request.
185 * <p>
186 * Call CoprocessorEnvironment#complete to skip any subsequent chained
187 * coprocessors
188 * @param c the environment provided by the region server
189 * @param row the row
190 * @param family the desired family
191 * @param result the result to return to the client, modify as necessary
192 * @throws IOException if an error occurred on the coprocessor
193 */
194 void postGetClosestRowBefore(final ObserverContext<RegionCoprocessorEnvironment> c,
195 final byte [] row, final byte [] family, final Result result)
196 throws IOException;
197
198 /**
199 * Called before the client performs a Get
200 * <p>
201 * Call CoprocessorEnvironment#bypass to skip default actions
202 * <p>
203 * Call CoprocessorEnvironment#complete to skip any subsequent chained
204 * coprocessors
205 * @param c the environment provided by the region server
206 * @param get the Get request
207 * @param result The result to return to the client if default processing
208 * is bypassed. Can be modified. Will not be used if default processing
209 * is not bypassed.
210 * @throws IOException if an error occurred on the coprocessor
211 */
212 void preGet(final ObserverContext<RegionCoprocessorEnvironment> c, final Get get,
213 final List<KeyValue> result)
214 throws IOException;
215
216 /**
217 * Called after the client performs a Get
218 * <p>
219 * Call CoprocessorEnvironment#complete to skip any subsequent chained
220 * coprocessors
221 * @param c the environment provided by the region server
222 * @param get the Get request
223 * @param result the result to return to the client, modify as necessary
224 * @throws IOException if an error occurred on the coprocessor
225 */
226 void postGet(final ObserverContext<RegionCoprocessorEnvironment> c, final Get get,
227 final List<KeyValue> result)
228 throws IOException;
229
230 /**
231 * Called before the client tests for existence using a Get.
232 * <p>
233 * Call CoprocessorEnvironment#bypass to skip default actions
234 * <p>
235 * Call CoprocessorEnvironment#complete to skip any subsequent chained
236 * coprocessors
237 * @param c the environment provided by the region server
238 * @param get the Get request
239 * @param exists
240 * @return the value to return to the client if bypassing default processing
241 * @throws IOException if an error occurred on the coprocessor
242 */
243 boolean preExists(final ObserverContext<RegionCoprocessorEnvironment> c, final Get get,
244 final boolean exists)
245 throws IOException;
246
247 /**
248 * Called after the client tests for existence using a Get.
249 * <p>
250 * Call CoprocessorEnvironment#complete to skip any subsequent chained
251 * coprocessors
252 * @param c the environment provided by the region server
253 * @param get the Get request
254 * @param exists the result returned by the region server
255 * @return the result to return to the client
256 * @throws IOException if an error occurred on the coprocessor
257 */
258 boolean postExists(final ObserverContext<RegionCoprocessorEnvironment> c, final Get get,
259 final boolean exists)
260 throws IOException;
261
262 /**
263 * Called before the client stores a value.
264 * <p>
265 * Call CoprocessorEnvironment#bypass to skip default actions
266 * <p>
267 * Call CoprocessorEnvironment#complete to skip any subsequent chained
268 * coprocessors
269 * @param c the environment provided by the region server
270 * @param put The Put object
271 * @param edit The WALEdit object that will be written to the wal
272 * @param writeToWAL true if the change should be written to the WAL
273 * @throws IOException if an error occurred on the coprocessor
274 */
275 void prePut(final ObserverContext<RegionCoprocessorEnvironment> c,
276 final Put put, final WALEdit edit, final boolean writeToWAL)
277 throws IOException;
278
279 /**
280 * Called after the client stores a value.
281 * <p>
282 * Call CoprocessorEnvironment#complete to skip any subsequent chained
283 * coprocessors
284 * @param c the environment provided by the region server
285 * @param put The Put object
286 * @param edit The WALEdit object for the wal
287 * @param writeToWAL true if the change should be written to the WAL
288 * @throws IOException if an error occurred on the coprocessor
289 */
290 void postPut(final ObserverContext<RegionCoprocessorEnvironment> c,
291 final Put put, final WALEdit edit, final boolean writeToWAL)
292 throws IOException;
293
294 /**
295 * Called before the client deletes a value.
296 * <p>
297 * Call CoprocessorEnvironment#bypass to skip default actions
298 * <p>
299 * Call CoprocessorEnvironment#complete to skip any subsequent chained
300 * coprocessors
301 * @param c the environment provided by the region server
302 * @param delete The Delete object
303 * @param edit The WALEdit object for the wal
304 * @param writeToWAL true if the change should be written to the WAL
305 * @throws IOException if an error occurred on the coprocessor
306 */
307 void preDelete(final ObserverContext<RegionCoprocessorEnvironment> c,
308 final Delete delete, final WALEdit edit, final boolean writeToWAL)
309 throws IOException;
310
311 /**
312 * Called after the client deletes a value.
313 * <p>
314 * Call CoprocessorEnvironment#complete to skip any subsequent chained
315 * coprocessors
316 * @param c the environment provided by the region server
317 * @param delete The Delete object
318 * @param edit The WALEdit object for the wal
319 * @param writeToWAL true if the change should be written to the WAL
320 * @throws IOException if an error occurred on the coprocessor
321 */
322 void postDelete(final ObserverContext<RegionCoprocessorEnvironment> c,
323 final Delete delete, final WALEdit edit, final boolean writeToWAL)
324 throws IOException;
325
326 /**
327 * Called before checkAndPut
328 * <p>
329 * Call CoprocessorEnvironment#bypass to skip default actions
330 * <p>
331 * Call CoprocessorEnvironment#complete to skip any subsequent chained
332 * coprocessors
333 * @param c the environment provided by the region server
334 * @param row row to check
335 * @param family column family
336 * @param qualifier column qualifier
337 * @param compareOp the comparison operation
338 * @param comparator the comparator
339 * @param put data to put if check succeeds
340 * @param result
341 * @return the return value to return to client if bypassing default
342 * processing
343 * @throws IOException if an error occurred on the coprocessor
344 */
345 boolean preCheckAndPut(final ObserverContext<RegionCoprocessorEnvironment> c,
346 final byte [] row, final byte [] family, final byte [] qualifier,
347 final CompareOp compareOp, final WritableByteArrayComparable comparator,
348 final Put put, final boolean result)
349 throws IOException;
350
351 /**
352 * Called after checkAndPut
353 * <p>
354 * Call CoprocessorEnvironment#complete to skip any subsequent chained
355 * coprocessors
356 * @param c the environment provided by the region server
357 * @param row row to check
358 * @param family column family
359 * @param qualifier column qualifier
360 * @param compareOp the comparison operation
361 * @param comparator the comparator
362 * @param put data to put if check succeeds
363 * @param result from the checkAndPut
364 * @return the possibly transformed return value to return to client
365 * @throws IOException if an error occurred on the coprocessor
366 */
367 boolean postCheckAndPut(final ObserverContext<RegionCoprocessorEnvironment> c,
368 final byte [] row, final byte [] family, final byte [] qualifier,
369 final CompareOp compareOp, final WritableByteArrayComparable comparator,
370 final Put put, final boolean result)
371 throws IOException;
372
373 /**
374 * Called before checkAndDelete
375 * <p>
376 * Call CoprocessorEnvironment#bypass to skip default actions
377 * <p>
378 * Call CoprocessorEnvironment#complete to skip any subsequent chained
379 * coprocessors
380 * @param c the environment provided by the region server
381 * @param row row to check
382 * @param family column family
383 * @param qualifier column qualifier
384 * @param compareOp the comparison operation
385 * @param comparator the comparator
386 * @param delete delete to commit if check succeeds
387 * @param result
388 * @return the value to return to client if bypassing default processing
389 * @throws IOException if an error occurred on the coprocessor
390 */
391 boolean preCheckAndDelete(final ObserverContext<RegionCoprocessorEnvironment> c,
392 final byte [] row, final byte [] family, final byte [] qualifier,
393 final CompareOp compareOp, final WritableByteArrayComparable comparator,
394 final Delete delete, final boolean result)
395 throws IOException;
396
397 /**
398 * Called after checkAndDelete
399 * <p>
400 * Call CoprocessorEnvironment#complete to skip any subsequent chained
401 * coprocessors
402 * @param c the environment provided by the region server
403 * @param row row to check
404 * @param family column family
405 * @param qualifier column qualifier
406 * @param compareOp the comparison operation
407 * @param comparator the comparator
408 * @param delete delete to commit if check succeeds
409 * @param result from the CheckAndDelete
410 * @return the possibly transformed returned value to return to client
411 * @throws IOException if an error occurred on the coprocessor
412 */
413 boolean postCheckAndDelete(final ObserverContext<RegionCoprocessorEnvironment> c,
414 final byte [] row, final byte [] family, final byte [] qualifier,
415 final CompareOp compareOp, final WritableByteArrayComparable comparator,
416 final Delete delete, final boolean result)
417 throws IOException;
418
419 /**
420 * Called before incrementColumnValue
421 * <p>
422 * Call CoprocessorEnvironment#bypass to skip default actions
423 * <p>
424 * Call CoprocessorEnvironment#complete to skip any subsequent chained
425 * coprocessors
426 * @param c the environment provided by the region server
427 * @param row row to check
428 * @param family column family
429 * @param qualifier column qualifier
430 * @param amount long amount to increment
431 * @param writeToWAL true if the change should be written to the WAL
432 * @return value to return to the client if bypassing default processing
433 * @throws IOException if an error occurred on the coprocessor
434 */
435 long preIncrementColumnValue(final ObserverContext<RegionCoprocessorEnvironment> c,
436 final byte [] row, final byte [] family, final byte [] qualifier,
437 final long amount, final boolean writeToWAL)
438 throws IOException;
439
440 /**
441 * Called after incrementColumnValue
442 * <p>
443 * Call CoprocessorEnvironment#complete to skip any subsequent chained
444 * coprocessors
445 * @param c the environment provided by the region server
446 * @param row row to check
447 * @param family column family
448 * @param qualifier column qualifier
449 * @param amount long amount to increment
450 * @param writeToWAL true if the change should be written to the WAL
451 * @param result the result returned by incrementColumnValue
452 * @return the result to return to the client
453 * @throws IOException if an error occurred on the coprocessor
454 */
455 long postIncrementColumnValue(final ObserverContext<RegionCoprocessorEnvironment> c,
456 final byte [] row, final byte [] family, final byte [] qualifier,
457 final long amount, final boolean writeToWAL, final long result)
458 throws IOException;
459
460 /**
461 * Called before Increment
462 * <p>
463 * Call CoprocessorEnvironment#bypass to skip default actions
464 * <p>
465 * Call CoprocessorEnvironment#complete to skip any subsequent chained
466 * coprocessors
467 * @param c the environment provided by the region server
468 * @param increment increment object
469 * @param result The result to return to the client if default processing
470 * is bypassed. Can be modified. Will not be used if default processing
471 * is not bypassed.
472 * @throws IOException if an error occurred on the coprocessor
473 */
474 void preIncrement(final ObserverContext<RegionCoprocessorEnvironment> c,
475 final Increment increment, final Result result)
476 throws IOException;
477
478 /**
479 * Called after increment
480 * <p>
481 * Call CoprocessorEnvironment#complete to skip any subsequent chained
482 * coprocessors
483 * @param c the environment provided by the region server
484 * @param increment increment object
485 * @param result the result returned by increment, can be modified
486 * @throws IOException if an error occurred on the coprocessor
487 */
488 void postIncrement(final ObserverContext<RegionCoprocessorEnvironment> c,
489 final Increment increment, final Result result)
490 throws IOException;
491
492 /**
493 * Called before the client opens a new scanner.
494 * <p>
495 * Call CoprocessorEnvironment#bypass to skip default actions
496 * <p>
497 * Call CoprocessorEnvironment#complete to skip any subsequent chained
498 * coprocessors
499 * @param c the environment provided by the region server
500 * @param scan the Scan specification
501 * @param s if not null, the base scanner
502 * @return an RegionScanner instance to use instead of the base scanner if
503 * overriding default behavior, null otherwise
504 * @throws IOException if an error occurred on the coprocessor
505 */
506 RegionScanner preScannerOpen(final ObserverContext<RegionCoprocessorEnvironment> c,
507 final Scan scan, final RegionScanner s)
508 throws IOException;
509
510 /**
511 * Called after the client opens a new scanner.
512 * <p>
513 * Call CoprocessorEnvironment#complete to skip any subsequent chained
514 * coprocessors
515 * @param c the environment provided by the region server
516 * @param scan the Scan specification
517 * @param s if not null, the base scanner
518 * @return the scanner instance to use
519 * @throws IOException if an error occurred on the coprocessor
520 */
521 RegionScanner postScannerOpen(final ObserverContext<RegionCoprocessorEnvironment> c,
522 final Scan scan, final RegionScanner s)
523 throws IOException;
524
525 /**
526 * Called before the client asks for the next row on a scanner.
527 * <p>
528 * Call CoprocessorEnvironment#bypass to skip default actions
529 * <p>
530 * Call CoprocessorEnvironment#complete to skip any subsequent chained
531 * coprocessors
532 * @param c the environment provided by the region server
533 * @param s the scanner
534 * @param result The result to return to the client if default processing
535 * is bypassed. Can be modified. Will not be returned if default processing
536 * is not bypassed.
537 * @param limit the maximum number of results to return
538 * @param hasNext the 'has more' indication
539 * @return 'has more' indication that should be sent to client
540 * @throws IOException if an error occurred on the coprocessor
541 */
542 boolean preScannerNext(final ObserverContext<RegionCoprocessorEnvironment> c,
543 final InternalScanner s, final List<Result> result,
544 final int limit, final boolean hasNext)
545 throws IOException;
546
547 /**
548 * Called after the client asks for the next row on a scanner.
549 * <p>
550 * Call CoprocessorEnvironment#complete to skip any subsequent chained
551 * coprocessors
552 * @param c the environment provided by the region server
553 * @param s the scanner
554 * @param result the result to return to the client, can be modified
555 * @param limit the maximum number of results to return
556 * @param hasNext the 'has more' indication
557 * @return 'has more' indication that should be sent to client
558 * @throws IOException if an error occurred on the coprocessor
559 */
560 boolean postScannerNext(final ObserverContext<RegionCoprocessorEnvironment> c,
561 final InternalScanner s, final List<Result> result, final int limit,
562 final boolean hasNext)
563 throws IOException;
564
565 /**
566 * Called before the client closes a scanner.
567 * <p>
568 * Call CoprocessorEnvironment#bypass to skip default actions
569 * <p>
570 * Call CoprocessorEnvironment#complete to skip any subsequent chained
571 * coprocessors
572 * @param c the environment provided by the region server
573 * @param s the scanner
574 * @throws IOException if an error occurred on the coprocessor
575 */
576 void preScannerClose(final ObserverContext<RegionCoprocessorEnvironment> c,
577 final InternalScanner s)
578 throws IOException;
579
580 /**
581 * Called after the client closes a scanner.
582 * <p>
583 * Call CoprocessorEnvironment#complete to skip any subsequent chained
584 * coprocessors
585 * @param c the environment provided by the region server
586 * @param s the scanner
587 * @throws IOException if an error occurred on the coprocessor
588 */
589 void postScannerClose(final ObserverContext<RegionCoprocessorEnvironment> c,
590 final InternalScanner s)
591 throws IOException;
592
593 /**
594 * Called before a {@link org.apache.hadoop.hbase.regionserver.wal.WALEdit}
595 * replayed for this region.
596 *
597 * @param ctx
598 * @param info
599 * @param logKey
600 * @param logEdit
601 * @throws IOException
602 */
603 void preWALRestore(final ObserverContext<RegionCoprocessorEnvironment> ctx,
604 HRegionInfo info, HLogKey logKey, WALEdit logEdit) throws IOException;
605
606 /**
607 * Called after a {@link org.apache.hadoop.hbase.regionserver.wal.WALEdit}
608 * replayed for this region.
609 *
610 * @param ctx
611 * @param info
612 * @param logKey
613 * @param logEdit
614 * @throws IOException
615 */
616 void postWALRestore(final ObserverContext<RegionCoprocessorEnvironment> ctx,
617 HRegionInfo info, HLogKey logKey, WALEdit logEdit) throws IOException;
618 }