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