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