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