View Javadoc

1   /*
2    *
3    * Licensed to the Apache Software Foundation (ASF) under one
4    * or more contributor license agreements.  See the NOTICE file
5    * distributed with this work for additional information
6    * regarding copyright ownership.  The ASF licenses this file
7    * to you under the Apache License, Version 2.0 (the
8    * "License"); you may not use this file except in compliance
9    * with the License.  You may obtain a copy of the License at
10   *
11   *     http://www.apache.org/licenses/LICENSE-2.0
12   *
13   * Unless required by applicable law or agreed to in writing, software
14   * distributed under the License is distributed on an "AS IS" BASIS,
15   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16   * See the License for the specific language governing permissions and
17   * limitations under the License.
18   */
19  
20  package org.apache.hadoop.hbase.filter;
21  
22  import java.io.IOException;
23  import java.util.List;
24  
25  import org.apache.hadoop.classification.InterfaceAudience;
26  import org.apache.hadoop.classification.InterfaceStability;
27  import org.apache.hadoop.hbase.Cell;
28  import org.apache.hadoop.hbase.KeyValue;
29  import org.apache.hadoop.hbase.exceptions.DeserializationException;
30  
31  /**
32   * Interface for row and column filters directly applied within the regionserver.
33   *
34   * A filter can expect the following call sequence:
35   * <ul>
36   *   <li> {@link #reset()} : reset the filter state before filtering a new row. </li>
37   *   <li> {@link #filterAllRemaining()}: true means row scan is over; false means keep going. </li>
38   *   <li> {@link #filterRowKey(byte[],int,int)}: true means drop this row; false means include.</li>
39   *   <li> {@link #filterKeyValue(Cell)}: decides whether to include or exclude this KeyValue.
40   *        See {@link ReturnCode}. </li>
41   *   <li> {@link #transform(KeyValue)}: if the KeyValue is included, let the filter transform the
42   *        KeyValue. </li>
43   *   <li> {@link #filterRowCells(List)}: allows direct modification of the final list to be submitted
44   *   <li> {@link #filterRow()}: last chance to drop entire row based on the sequence of
45   *        filter calls. Eg: filter a row if it doesn't contain a specified column. </li>
46   * </ul>
47   *
48   * Filter instances are created one per region/scan.  This abstract class replaces
49   * the old RowFilterInterface.
50   *
51   * When implementing your own filters, consider inheriting {@link FilterBase} to help
52   * you reduce boilerplate.
53   *
54   * @see FilterBase
55   */
56  @InterfaceAudience.Public
57  @InterfaceStability.Stable
58  public abstract class Filter {
59    protected boolean reversed;
60    /**
61     * Reset the state of the filter between rows.
62     * 
63     * Concrete implementers can signal a failure condition in their code by throwing an
64     * {@link IOException}.
65     * 
66     * @throws IOException in case an I/O or an filter specific failure needs to be signaled.
67     */
68    abstract public void reset() throws IOException;
69  
70    /**
71     * Filters a row based on the row key. If this returns true, the entire row will be excluded. If
72     * false, each KeyValue in the row will be passed to {@link #filterKeyValue(Cell)} below.
73     * 
74     * Concrete implementers can signal a failure condition in their code by throwing an
75     * {@link IOException}.
76     * 
77     * @param buffer buffer containing row key
78     * @param offset offset into buffer where row key starts
79     * @param length length of the row key
80     * @return true, remove entire row, false, include the row (maybe).
81     * @throws IOException in case an I/O or an filter specific failure needs to be signaled.
82     */
83    abstract public boolean filterRowKey(byte[] buffer, int offset, int length) throws IOException;
84  
85    /**
86     * If this returns true, the scan will terminate.
87     * 
88     * Concrete implementers can signal a failure condition in their code by throwing an
89     * {@link IOException}.
90     * 
91     * @return true to end scan, false to continue.
92     * @throws IOException in case an I/O or an filter specific failure needs to be signaled.
93     */
94    abstract public boolean filterAllRemaining() throws IOException;
95  
96    /**
97     * A way to filter based on the column family, column qualifier and/or the column value. Return
98     * code is described below. This allows filters to filter only certain number of columns, then
99     * terminate without matching ever column.
100    * 
101    * If filterRowKey returns true, filterKeyValue needs to be consistent with it.
102    * 
103    * filterKeyValue can assume that filterRowKey has already been called for the row.
104    * 
105    * If your filter returns <code>ReturnCode.NEXT_ROW</code>, it should return
106    * <code>ReturnCode.NEXT_ROW</code> until {@link #reset()} is called just in case the caller calls
107    * for the next row.
108    * 
109    * Concrete implementers can signal a failure condition in their code by throwing an
110    * {@link IOException}.
111    * 
112    * @param v the Cell in question
113    * @return code as described below
114    * @throws IOException in case an I/O or an filter specific failure needs to be signaled.
115    * @see Filter.ReturnCode
116    */
117   abstract public ReturnCode filterKeyValue(final Cell v) throws IOException;
118 
119   /**
120    * Give the filter a chance to transform the passed KeyValue. If the Cell is changed a new
121    * Cell object must be returned.
122    * 
123    * @see org.apache.hadoop.hbase.KeyValue#shallowCopy()
124    *      The transformed KeyValue is what is eventually returned to the client. Most filters will
125    *      return the passed KeyValue unchanged.
126    * @see org.apache.hadoop.hbase.filter.KeyOnlyFilter#transform(KeyValue) for an example of a
127    *      transformation.
128    * 
129    *      Concrete implementers can signal a failure condition in their code by throwing an
130    *      {@link IOException}.
131    * 
132    * @param v the KeyValue in question
133    * @return the changed KeyValue
134    * @throws IOException in case an I/O or an filter specific failure needs to be signaled.
135    */
136   abstract public Cell transformCell(final Cell v) throws IOException;
137 
138   /**
139    * WARNING: please to not override this method.  Instead override {@link #transformCell(Cell)}.
140    * This is for transition from 0.94 -> 0.96
141    **/
142   @Deprecated // use Cell transformCell(final Cell)
143   abstract public KeyValue transform(final KeyValue currentKV) throws IOException;
144  
145   
146   /**
147    * Return codes for filterValue().
148    */
149   @InterfaceAudience.Public
150   @InterfaceStability.Stable
151   public enum ReturnCode {
152     /**
153      * Include the Cell
154      */
155     INCLUDE,
156     /**
157      * Include the Cell and seek to the next column skipping older versions.
158      */
159     INCLUDE_AND_NEXT_COL,
160     /**
161      * Skip this Cell
162      */
163     SKIP,
164     /**
165      * Skip this column. Go to the next column in this row.
166      */
167     NEXT_COL,
168     /**
169      * Done with columns, skip to next row. Note that filterRow() will
170      * still be called.
171      */
172     NEXT_ROW,
173     /**
174      * Seek to next key which is given as hint by the filter.
175      */
176     SEEK_NEXT_USING_HINT,
177 }
178 
179   /**
180    * Chance to alter the list of Cells to be submitted. Modifications to the list will carry on
181    * 
182    * Concrete implementers can signal a failure condition in their code by throwing an
183    * {@link IOException}.
184    * 
185    * @param kvs the list of Cells to be filtered
186    * @throws IOException in case an I/O or an filter specific failure needs to be signaled.
187    */
188   abstract public void filterRowCells(List<Cell> kvs) throws IOException;
189 
190   /**
191    * Primarily used to check for conflicts with scans(such as scans that do not read a full row at a
192    * time).
193    * 
194    * @return True if this filter actively uses filterRowCells(List) or filterRow().
195    */
196   abstract public boolean hasFilterRow();
197 
198   /**
199    * Last chance to veto row based on previous {@link #filterKeyValue(Cell)} calls. The filter
200    * needs to retain state then return a particular value for this call if they wish to exclude a
201    * row if a certain column is missing (for example).
202    * 
203    * Concrete implementers can signal a failure condition in their code by throwing an
204    * {@link IOException}.
205    * 
206    * @return true to exclude row, false to include row.
207    * @throws IOException in case an I/O or an filter specific failure needs to be signaled.
208    */
209   abstract public boolean filterRow() throws IOException;
210 
211   @Deprecated // use Cell GetNextKeyHint(final Cell)
212   abstract public KeyValue getNextKeyHint(final KeyValue currentKV) throws IOException;
213 
214   /**
215    * If the filter returns the match code SEEK_NEXT_USING_HINT, then it should also tell which is
216    * the next key it must seek to. After receiving the match code SEEK_NEXT_USING_HINT, the
217    * QueryMatcher would call this function to find out which key it must next seek to.
218    * 
219    * Concrete implementers can signal a failure condition in their code by throwing an
220    * {@link IOException}.
221    * 
222    * @return KeyValue which must be next seeked. return null if the filter is not sure which key to
223    *         seek to next.
224    * @throws IOException in case an I/O or an filter specific failure needs to be signaled.
225    */
226   abstract public Cell getNextCellHint(final Cell currentKV) throws IOException;
227 
228   /**
229    * Check that given column family is essential for filter to check row. Most filters always return
230    * true here. But some could have more sophisticated logic which could significantly reduce
231    * scanning process by not even touching columns until we are 100% sure that it's data is needed
232    * in result.
233    * 
234    * Concrete implementers can signal a failure condition in their code by throwing an
235    * {@link IOException}.
236    * 
237    * @throws IOException in case an I/O or an filter specific failure needs to be signaled.
238    */
239   abstract public boolean isFamilyEssential(byte[] name) throws IOException;
240 
241   /**
242    * TODO: JAVADOC
243    * 
244    * Concrete implementers can signal a failure condition in their code by throwing an
245    * {@link IOException}.
246    * 
247    * @return The filter serialized using pb
248    * @throws IOException in case an I/O or an filter specific failure needs to be signaled.
249    */
250   abstract public byte[] toByteArray() throws IOException;
251 
252   /**
253    * 
254    * Concrete implementers can signal a failure condition in their code by throwing an
255    * {@link IOException}.
256    * 
257    * @param pbBytes A pb serialized {@link Filter} instance
258    * @return An instance of {@link Filter} made from <code>bytes</code>
259    * @throws DeserializationException
260    * @throws IOException in case an I/O or an filter specific failure needs to be signaled.
261    * @see #toByteArray
262    */
263   public static Filter parseFrom(final byte [] pbBytes) throws DeserializationException {
264     throw new DeserializationException(
265       "parseFrom called on base Filter, but should be called on derived type");
266   }
267 
268   /**
269    * Concrete implementers can signal a failure condition in their code by throwing an
270    * {@link IOException}.
271    * 
272    * @param other
273    * @return true if and only if the fields of the filter that are serialized are equal to the
274    *         corresponding fields in other. Used for testing.
275    * @throws IOException in case an I/O or an filter specific failure needs to be signaled.
276    */
277   abstract boolean areSerializedFieldsEqual(Filter other);
278 
279   /**
280    * alter the reversed scan flag
281    * @param reversed flag
282    */
283   public void setReversed(boolean reversed) {
284     this.reversed = reversed;
285   }
286 
287   public boolean isReversed() {
288     return this.reversed;
289   }
290 }