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.ArrayList;
24  import java.util.List;
25  
26  import org.apache.hadoop.classification.InterfaceAudience;
27  import org.apache.hadoop.hbase.Cell;
28  import org.apache.hadoop.hbase.KeyValue;
29  import org.apache.hadoop.hbase.KeyValueUtil;
30  
31  /**
32   * Abstract base class to help you implement new Filters.  Common "ignore" or NOOP type
33   * methods can go here, helping to reduce boiler plate in an ever-expanding filter
34   * library.
35   *
36   * If you could instantiate FilterBase, it would end up being a "null" filter -
37   * that is one that never filters anything.
38   */
39  @InterfaceAudience.Private // TODO add filter limited private level
40  public abstract class FilterBase extends Filter {
41  
42    /**
43     * Filters that are purely stateless and do nothing in their reset() methods can inherit
44     * this null/empty implementation.
45     *
46     * @inheritDoc
47     */
48    @Override
49    public void reset() throws IOException {
50    }
51  
52    /**
53     * Filters that do not filter by row key can inherit this implementation that
54     * never filters anything. (ie: returns false).
55     *
56     * @inheritDoc
57     */
58    @Override
59    public boolean filterRowKey(byte[] buffer, int offset, int length) throws IOException {
60      return false;
61    }
62  
63    /**
64     * Filters that never filter all remaining can inherit this implementation that
65     * never stops the filter early.
66     *
67     * @inheritDoc
68     */
69    @Override
70    public boolean filterAllRemaining() throws IOException {
71      return false;
72    }
73  
74    /**
75     * By default no transformation takes place
76     *
77     * @inheritDoc
78     */
79    @Override
80    public Cell transformCell(Cell v) throws IOException {
81      // Old filters based off of this class will override KeyValue transform(KeyValue).
82      // Thus to maintain compatibility we need to call the old version.
83      return transform(KeyValueUtil.ensureKeyValue(v));
84    }
85  
86    /**
87     * WARNING: please to not override this method.  Instead override {@link #transformCell(Cell)}.
88     *
89     * This is for transition from 0.94 -> 0.96
90     */
91    @Override
92    @Deprecated
93    public KeyValue transform(KeyValue currentKV) throws IOException {
94      return currentKV;
95    }
96  
97    /**
98     * Filters that never filter by modifying the returned List of Cells can
99     * inherit this implementation that does nothing.
100    *
101    * @inheritDoc
102    */
103   @Override
104   public void filterRowCells(List<Cell> ignored) throws IOException {
105   }
106 
107   /**
108    * Fitlers that never filter by modifying the returned List of Cells can
109    * inherit this implementation that does nothing.
110    *
111    * @inheritDoc
112    */
113   @Override
114   public boolean hasFilterRow() {
115     return false;
116   }
117 
118   /**
119    * Filters that never filter by rows based on previously gathered state from
120    * {@link #filterKeyValue(Cell)} can inherit this implementation that
121    * never filters a row.
122    *
123    * @inheritDoc
124    */
125   @Override
126   public boolean filterRow() throws IOException {
127     return false;
128   }
129 
130   /**
131    * This method is deprecated and you should override Cell getNextKeyHint(Cell) instead.
132    */
133   @Override
134   @Deprecated
135   public KeyValue getNextKeyHint(KeyValue currentKV) throws IOException {
136     return null;
137   }
138   
139   /**
140    * Filters that are not sure which key must be next seeked to, can inherit
141    * this implementation that, by default, returns a null Cell.
142    *
143    * @inheritDoc
144    */
145   public Cell getNextCellHint(Cell currentCell) throws IOException {
146     return null;
147   }
148 
149   /**
150    * By default, we require all scan's column families to be present. Our
151    * subclasses may be more precise.
152    *
153    * @inheritDoc
154    */
155   public boolean isFamilyEssential(byte[] name) throws IOException {
156     return true;
157   }
158 
159   /**
160    * Given the filter's arguments it constructs the filter
161    * <p>
162    * @param filterArguments the filter's arguments
163    * @return constructed filter object
164    */
165   public static Filter createFilterFromArguments(ArrayList<byte []> filterArguments) {
166     throw new IllegalArgumentException("This method has not been implemented");
167   }
168 
169   /**
170    * Return filter's info for debugging and logging purpose.
171    */
172   public String toString() {
173     return this.getClass().getSimpleName();
174   }
175 
176   /**
177    * Return length 0 byte array for Filters that don't require special serialization
178    */
179   public byte[] toByteArray() throws IOException {
180     return new byte[0];
181   }
182 
183   /**
184    * Default implementation so that writers of custom filters aren't forced to implement.
185    *
186    * @param other
187    * @return true if and only if the fields of the filter that are serialized
188    * are equal to the corresponding fields in other.  Used for testing.
189    */
190   boolean areSerializedFieldsEqual(Filter other) {
191     return true;
192   }
193 }