View Javadoc

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 }