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      // TODO when cell is backed by DirectByteBuffer, we would need to copy row bytes to temp byte[]
67      // and call old method for BC.
68      return filterRowKey(cell.getRowArray(), cell.getRowOffset(), cell.getRowLength());
69    }
70  
71    /**
72     * Filters that never filter all remaining can inherit this implementation that
73     * never stops the filter early.
74     *
75     * {@inheritDoc}
76     */
77    @Override
78    public boolean filterAllRemaining() throws IOException {
79      return false;
80    }
81  
82    /**
83     * By default no transformation takes place
84     *
85     * {@inheritDoc}
86     */
87    @Override
88    public Cell transformCell(Cell v) throws IOException {
89      return v;
90    }
91  
92    /**
93     * Filters that never filter by modifying the returned List of Cells can
94     * inherit this implementation that does nothing.
95     *
96     * {@inheritDoc}
97     */
98    @Override
99    public void filterRowCells(List<Cell> ignored) throws IOException {
100   }
101 
102   /**
103    * Fitlers that never filter by modifying the returned List of Cells can
104    * inherit this implementation that does nothing.
105    *
106    * {@inheritDoc}
107    */
108   @Override
109   public boolean hasFilterRow() {
110     return false;
111   }
112 
113   /**
114    * Filters that never filter by rows based on previously gathered state from
115    * {@link #filterKeyValue(Cell)} can inherit this implementation that
116    * never filters a row.
117    *
118    * {@inheritDoc}
119    */
120   @Override
121   public boolean filterRow() throws IOException {
122     return false;
123   }
124 
125   /**
126    * Filters that are not sure which key must be next seeked to, can inherit
127    * this implementation that, by default, returns a null Cell.
128    *
129    * {@inheritDoc}
130    */
131   public Cell getNextCellHint(Cell currentCell) throws IOException {
132     return null;
133   }
134 
135   /**
136    * By default, we require all scan's column families to be present. Our
137    * subclasses may be more precise.
138    *
139    * {@inheritDoc}
140    */
141   public boolean isFamilyEssential(byte[] name) throws IOException {
142     return true;
143   }
144 
145   /**
146    * Given the filter's arguments it constructs the filter
147    * <p>
148    * @param filterArguments the filter's arguments
149    * @return constructed filter object
150    */
151   public static Filter createFilterFromArguments(ArrayList<byte []> filterArguments) {
152     throw new IllegalArgumentException("This method has not been implemented");
153   }
154 
155   /**
156    * Return filter's info for debugging and logging purpose.
157    */
158   public String toString() {
159     return this.getClass().getSimpleName();
160   }
161 
162   /**
163    * Return length 0 byte array for Filters that don't require special serialization
164    */
165   public byte[] toByteArray() throws IOException {
166     return new byte[0];
167   }
168 
169   /**
170    * Default implementation so that writers of custom filters aren't forced to implement.
171    *
172    * @param other
173    * @return true if and only if the fields of the filter that are serialized
174    * are equal to the corresponding fields in other.  Used for testing.
175    */
176   boolean areSerializedFieldsEqual(Filter other) {
177     return true;
178   }
179 }