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 with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18
19 package org.apache.hadoop.hbase.filter;
20
21 import java.io.IOException;
22 import java.util.ArrayList;
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.KeyValue;
28
29 /**
30 * Abstract base class to help you implement new Filters. Common "ignore" or NOOP type
31 * methods can go here, helping to reduce boiler plate in an ever-expanding filter
32 * library.
33 *
34 * If you could instantiate FilterBase, it would end up being a "null" filter -
35 * that is one that never filters anything.
36 */
37 @InterfaceAudience.Public
38 @InterfaceStability.Stable
39 public abstract class FilterBase extends Filter {
40
41 /**
42 * Filters that are purely stateless and do nothing in their reset() methods can inherit
43 * this null/empty implementation.
44 *
45 * @inheritDoc
46 */
47 @Override
48 public void reset() throws IOException {
49 }
50
51 /**
52 * Filters that do not filter by row key can inherit this implementation that
53 * never filters anything. (ie: returns false).
54 *
55 * @inheritDoc
56 */
57 @Override
58 public boolean filterRowKey(byte[] buffer, int offset, int length) throws IOException {
59 return false;
60 }
61
62 /**
63 * Filters that never filter all remaining can inherit this implementation that
64 * never stops the filter early.
65 *
66 * @inheritDoc
67 */
68 @Override
69 public boolean filterAllRemaining() throws IOException {
70 return false;
71 }
72
73 /**
74 * Filters that dont filter by key value can inherit this implementation that
75 * includes all KeyValues.
76 *
77 * @inheritDoc
78 */
79 @Override
80 public ReturnCode filterKeyValue(KeyValue ignored) throws IOException {
81 return ReturnCode.INCLUDE;
82 }
83
84 /**
85 * By default no transformation takes place
86 *
87 * @inheritDoc
88 */
89 @Override
90 public KeyValue transform(KeyValue v) throws IOException {
91 return v;
92 }
93
94 /**
95 * Filters that never filter by modifying the returned List of KeyValues can
96 * inherit this implementation that does nothing.
97 *
98 * @inheritDoc
99 */
100 @Override
101 public void filterRow(List<KeyValue> ignored) throws IOException {
102 }
103
104 /**
105 * Fitlers that never filter by modifying the returned List of KeyValues can
106 * inherit this implementation that does nothing.
107 *
108 * @inheritDoc
109 */
110 @Override
111 public boolean hasFilterRow() {
112 return false;
113 }
114
115 /**
116 * Filters that never filter by rows based on previously gathered state from
117 * {@link #filterKeyValue(KeyValue)} can inherit this implementation that
118 * never filters a row.
119 *
120 * @inheritDoc
121 */
122 @Override
123 public boolean filterRow() throws IOException {
124 return false;
125 }
126
127 /**
128 * Filters that are not sure which key must be next seeked to, can inherit
129 * this implementation that, by default, returns a null KeyValue.
130 *
131 * @inheritDoc
132 */
133 public KeyValue getNextKeyHint(KeyValue currentKV) throws IOException {
134 return null;
135 }
136
137 /**
138 * By default, we require all scan's column families to be present. Our
139 * subclasses may be more precise.
140 *
141 * @inheritDoc
142 */
143 public boolean isFamilyEssential(byte[] name) throws IOException {
144 return true;
145 }
146
147 /**
148 * Given the filter's arguments it constructs the filter
149 * <p>
150 * @param filterArguments the filter's arguments
151 * @return constructed filter object
152 */
153 public static Filter createFilterFromArguments(ArrayList<byte []> filterArguments) {
154 throw new IllegalArgumentException("This method has not been implemented");
155 }
156
157 /**
158 * Return filter's info for debugging and logging purpose.
159 */
160 public String toString() {
161 return this.getClass().getSimpleName();
162 }
163
164 /**
165 * Return length 0 byte array for Filters that don't require special serialization
166 */
167 public byte[] toByteArray() throws IOException {
168 return new byte[0];
169 }
170
171 /**
172 * Default implementation so that writers of custom filters aren't forced to implement.
173 *
174 * @param other
175 * @return true if and only if the fields of the filter that are serialized
176 * are equal to the corresponding fields in other. Used for testing.
177 */
178 boolean areSerializedFieldsEqual(Filter other) {
179 return true;
180 }
181 }