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                                                                       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 }