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.hbase.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 @Override
146 public Cell getNextCellHint(Cell currentKV) throws IOException {
147 // Old filters based off of this class will override KeyValue getNextKeyHint(KeyValue).
148 // Thus to maintain compatibility we need to call the old version.
149 return getNextKeyHint(KeyValueUtil.ensureKeyValue(currentKV));
150 }
151
152 /**
153 * By default, we require all scan's column families to be present. Our
154 * subclasses may be more precise.
155 *
156 * {@inheritDoc}
157 */
158 @Override
159 public boolean isFamilyEssential(byte[] name) throws IOException {
160 return true;
161 }
162
163 /**
164 * Given the filter's arguments it constructs the filter
165 * <p>
166 * @param filterArguments the filter's arguments
167 * @return constructed filter object
168 */
169 public static Filter createFilterFromArguments(ArrayList<byte []> filterArguments) {
170 throw new IllegalArgumentException("This method has not been implemented");
171 }
172
173 /**
174 * Return filter's info for debugging and logging purpose.
175 */
176 @Override
177 public String toString() {
178 return this.getClass().getSimpleName();
179 }
180
181 /**
182 * Return length 0 byte array for Filters that don't require special serialization
183 */
184 @Override
185 public byte[] toByteArray() throws IOException {
186 return new byte[0];
187 }
188
189 /**
190 * Default implementation so that writers of custom filters aren't forced to implement.
191 *
192 * @param other
193 * @return true if and only if the fields of the filter that are serialized
194 * are equal to the corresponding fields in other. Used for testing.
195 */
196 @Override
197 boolean areSerializedFieldsEqual(Filter other) {
198 return true;
199 }
200 }