View Javadoc

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