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.hbase.Cell;
27  import org.apache.hadoop.hbase.classification.InterfaceAudience;
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.Private // TODO add filter limited private level
38  public abstract class FilterBase extends Filter {
39  
40    /**
41     * Filters that are purely stateless and do nothing in their reset() methods can inherit
42     * this null/empty implementation.
43     *
44     * {@inheritDoc}
45     */
46    @Override
47    public void reset() throws IOException {
48    }
49  
50    /**
51     * Filters that do not filter by row key can inherit this implementation that
52     * never filters anything. (ie: returns false).
53     *
54     * {@inheritDoc}
55     * @deprecated As of release 2.0.0, this will be removed in HBase 3.0.0.
56     *             Instead use {@link #filterRowKey(Cell)}
57     */
58    @Override
59    @Deprecated
60    public boolean filterRowKey(byte[] buffer, int offset, int length) throws IOException {
61      return false;
62    }
63  
64    @Override
65    public boolean filterRowKey(Cell cell) throws IOException {
66      return filterRowKey(cell.getRowArray(), cell.getRowOffset(), cell.getRowLength());
67    }
68  
69    /**
70     * Filters that never filter all remaining can inherit this implementation that
71     * never stops the filter early.
72     *
73     * {@inheritDoc}
74     */
75    @Override
76    public boolean filterAllRemaining() throws IOException {
77      return false;
78    }
79  
80    /**
81     * By default no transformation takes place
82     *
83     * {@inheritDoc}
84     */
85    @Override
86    public Cell transformCell(Cell v) throws IOException {
87      return v;
88    }
89  
90    /**
91     * Filters that never filter by modifying the returned List of Cells can
92     * inherit this implementation that does nothing.
93     *
94     * {@inheritDoc}
95     */
96    @Override
97    public void filterRowCells(List<Cell> ignored) throws IOException {
98    }
99  
100   /**
101    * Fitlers that never filter by modifying the returned List of Cells can
102    * inherit this implementation that does nothing.
103    *
104    * {@inheritDoc}
105    */
106   @Override
107   public boolean hasFilterRow() {
108     return false;
109   }
110 
111   /**
112    * Filters that never filter by rows based on previously gathered state from
113    * {@link #filterKeyValue(Cell)} can inherit this implementation that
114    * never filters a row.
115    *
116    * {@inheritDoc}
117    */
118   @Override
119   public boolean filterRow() throws IOException {
120     return false;
121   }
122 
123   /**
124    * Filters that are not sure which key must be next seeked to, can inherit
125    * this implementation that, by default, returns a null Cell.
126    *
127    * {@inheritDoc}
128    */
129   public Cell getNextCellHint(Cell currentCell) throws IOException {
130     return null;
131   }
132 
133   /**
134    * By default, we require all scan's column families to be present. Our
135    * subclasses may be more precise.
136    *
137    * {@inheritDoc}
138    */
139   public boolean isFamilyEssential(byte[] name) throws IOException {
140     return true;
141   }
142 
143   /**
144    * Given the filter's arguments it constructs the filter
145    * <p>
146    * @param filterArguments the filter's arguments
147    * @return constructed filter object
148    */
149   public static Filter createFilterFromArguments(ArrayList<byte []> filterArguments) {
150     throw new IllegalArgumentException("This method has not been implemented");
151   }
152 
153   /**
154    * Return filter's info for debugging and logging purpose.
155    */
156   public String toString() {
157     return this.getClass().getSimpleName();
158   }
159 
160   /**
161    * Return length 0 byte array for Filters that don't require special serialization
162    */
163   public byte[] toByteArray() throws IOException {
164     return new byte[0];
165   }
166 
167   /**
168    * Default implementation so that writers of custom filters aren't forced to implement.
169    *
170    * @param other
171    * @return true if and only if the fields of the filter that are serialized
172    * are equal to the corresponding fields in other.  Used for testing.
173    */
174   boolean areSerializedFieldsEqual(Filter other) {
175     return true;
176   }
177 }