001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.apache.hadoop.hbase.filter;
019
020import java.io.IOException;
021import java.util.ArrayList;
022import java.util.List;
023import org.apache.hadoop.hbase.Cell;
024import org.apache.yetus.audience.InterfaceAudience;
025
026/**
027 * Abstract base class to help you implement new Filters. Common "ignore" or NOOP type methods can
028 * go here, helping to reduce boiler plate in an ever-expanding filter library. If you could
029 * instantiate FilterBase, it would end up being a "null" filter - that is one that never filters
030 * anything.
031 */
032@InterfaceAudience.Private // TODO add filter limited private level
033public abstract class FilterBase extends Filter {
034
035  /**
036   * Filters that are purely stateless and do nothing in their reset() methods can inherit this
037   * null/empty implementation. {@inheritDoc}
038   */
039  @Override
040  public void reset() throws IOException {
041  }
042
043  @Override
044  public boolean filterRowKey(Cell cell) throws IOException {
045    return filterAllRemaining();
046  }
047
048  /**
049   * Filters that never filter all remaining can inherit this implementation that never stops the
050   * filter early. {@inheritDoc}
051   */
052  @Override
053  public boolean filterAllRemaining() throws IOException {
054    return false;
055  }
056
057  /**
058   * By default no transformation takes place {@inheritDoc}
059   */
060  @Override
061  public Cell transformCell(Cell v) throws IOException {
062    return v;
063  }
064
065  /**
066   * Filters that never filter by modifying the returned List of Cells can inherit this
067   * implementation that does nothing. {@inheritDoc}
068   */
069  @Override
070  public void filterRowCells(List<Cell> ignored) throws IOException {
071  }
072
073  /**
074   * Filters that never filter by modifying the returned List of Cells can inherit this
075   * implementation that does nothing. {@inheritDoc}
076   */
077  @Override
078  public boolean hasFilterRow() {
079    return false;
080  }
081
082  /**
083   * Filters that never filter by rows based on previously gathered state from
084   * {@link #filterCell(Cell)} can inherit this implementation that never filters a row.
085   * {@inheritDoc}
086   */
087  @Override
088  public boolean filterRow() throws IOException {
089    return false;
090  }
091
092  /**
093   * Filters that are not sure which key must be next seeked to, can inherit this implementation
094   * that, by default, returns a null Cell. {@inheritDoc}
095   */
096  @Override
097  public Cell getNextCellHint(Cell currentCell) throws IOException {
098    return null;
099  }
100
101  /**
102   * Filters that cannot provide a seek hint after row-key rejection can inherit this no-op
103   * implementation. Subclasses whose row-key logic (e.g. a range pointer advanced inside
104   * {@link #filterRowKey(Cell)}) makes a better seek target available should override this.
105   * {@inheritDoc}
106   */
107  @Override
108  public Cell getHintForRejectedRow(Cell firstRowCell) throws IOException {
109    return null;
110  }
111
112  /**
113   * Filters that cannot provide a structural-skip seek hint can inherit this no-op implementation.
114   * Subclasses with purely configuration-driven, stateless hint computation (e.g. a fixed column
115   * range or fuzzy-row pattern) may override this to avoid cell-by-cell advancement when the
116   * time-range, column, or version gate fires. {@inheritDoc}
117   */
118  @Override
119  public Cell getSkipHint(Cell skippedCell) throws IOException {
120    return null;
121  }
122
123  /**
124   * By default, we require all scan's column families to be present. Our subclasses may be more
125   * precise. {@inheritDoc}
126   */
127  @Override
128  public boolean isFamilyEssential(byte[] name) throws IOException {
129    return true;
130  }
131
132  /**
133   * Given the filter's arguments it constructs the filter
134   * <p>
135   * @param filterArguments the filter's arguments
136   * @return constructed filter object
137   */
138  public static Filter createFilterFromArguments(ArrayList<byte[]> filterArguments) {
139    throw new IllegalArgumentException("This method has not been implemented");
140  }
141
142  /**
143   * Return filter's info for debugging and logging purpose.
144   */
145  @Override
146  public String toString() {
147    return this.getClass().getSimpleName();
148  }
149
150  /**
151   * Return length 0 byte array for Filters that don't require special serialization
152   */
153  @Override
154  public byte[] toByteArray() throws IOException {
155    return new byte[0];
156  }
157
158  /**
159   * Default implementation so that writers of custom filters aren't forced to implement.
160   * @return true if and only if the fields of the filter that are serialized are equal to the
161   *         corresponding fields in other. Used for testing.
162   */
163  @Override
164  boolean areSerializedFieldsEqual(Filter other) {
165    return true;
166  }
167}