001/*
002 *
003 * Licensed to the Apache Software Foundation (ASF) under one
004 * or more contributor license agreements.  See the NOTICE file
005 * distributed with this work for additional information
006 * regarding copyright ownership.  The ASF licenses this file
007 * to you under the Apache License, Version 2.0 (the
008 * "License"); you may not use this file except in compliance
009 * with the License.  You may obtain a copy of the License at
010 *
011 *     http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing, software
014 * distributed under the License is distributed on an "AS IS" BASIS,
015 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016 * See the License for the specific language governing permissions and
017 * limitations under the License.
018 */
019
020package org.apache.hadoop.hbase.filter;
021
022import java.io.IOException;
023import java.util.ArrayList;
024import java.util.List;
025
026import org.apache.hadoop.hbase.Cell;
027import org.apache.yetus.audience.InterfaceAudience;
028
029/**
030 * Abstract base class to help you implement new Filters.  Common "ignore" or NOOP type
031 * methods can go here, helping to reduce boiler plate in an ever-expanding filter
032 * library.
033 *
034 * If you could instantiate FilterBase, it would end up being a "null" filter -
035 * that is one that never filters anything.
036 */
037@InterfaceAudience.Private // TODO add filter limited private level
038public abstract class FilterBase extends Filter {
039
040  /**
041   * Filters that are purely stateless and do nothing in their reset() methods can inherit
042   * this null/empty implementation.
043   *
044   * {@inheritDoc}
045   */
046  @Override
047  public void reset() throws IOException {
048  }
049
050  /**
051   * Filters that do not filter by row key can inherit this implementation that
052   * never filters anything. (ie: returns false).
053   *
054   * {@inheritDoc}
055   * @deprecated As of release 2.0.0, this will be removed in HBase 3.0.0.
056   *             Instead use {@link #filterRowKey(Cell)}
057   */
058  @Override
059  @Deprecated
060  public boolean filterRowKey(byte[] buffer, int offset, int length) throws IOException {
061    if (filterAllRemaining()) return true;
062    return false;
063  }
064
065  @Override
066  public boolean filterRowKey(Cell cell) throws IOException {
067    if (filterAllRemaining()) return true;
068    return filterRowKey(cell.getRowArray(), cell.getRowOffset(), cell.getRowLength());
069  }
070
071  /**
072   * Filters that never filter all remaining can inherit this implementation that
073   * never stops the filter early.
074   *
075   * {@inheritDoc}
076   */
077  @Override
078  public boolean filterAllRemaining() throws IOException {
079    return false;
080  }
081
082  /**
083   * By default no transformation takes place
084   *
085   * {@inheritDoc}
086   */
087  @Override
088  public Cell transformCell(Cell v) throws IOException {
089    return v;
090  }
091
092  /**
093   * Filters that never filter by modifying the returned List of Cells can
094   * inherit this implementation that does nothing.
095   *
096   * {@inheritDoc}
097   */
098  @Override
099  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 #filterCell(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  @Override
132  public Cell getNextCellHint(Cell currentCell) throws IOException {
133    return null;
134  }
135
136  /**
137   * By default, we require all scan's column families to be present. Our
138   * subclasses may be more precise.
139   *
140   * {@inheritDoc}
141   */
142  @Override
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  @Override
161  public String toString() {
162    return this.getClass().getSimpleName();
163  }
164
165  /**
166   * Return length 0 byte array for Filters that don't require special serialization
167   */
168  @Override
169  public byte[] toByteArray() throws IOException {
170    return new byte[0];
171  }
172
173  /**
174   * Default implementation so that writers of custom filters aren't forced to implement.
175   *
176   * @param other
177   * @return true if and only if the fields of the filter that are serialized
178   * are equal to the corresponding fields in other.  Used for testing.
179   */
180  @Override
181  boolean areSerializedFieldsEqual(Filter other) {
182    return true;
183  }
184}