View Javadoc

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 }