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  @Override
051  public boolean filterRowKey(Cell cell) throws IOException {
052    return filterAllRemaining();
053  }
054
055  /**
056   * Filters that never filter all remaining can inherit this implementation that
057   * never stops the filter early.
058   *
059   * {@inheritDoc}
060   */
061  @Override
062  public boolean filterAllRemaining() throws IOException {
063    return false;
064  }
065
066  /**
067   * By default no transformation takes place
068   *
069   * {@inheritDoc}
070   */
071  @Override
072  public Cell transformCell(Cell v) throws IOException {
073    return v;
074  }
075
076  /**
077   * Filters that never filter by modifying the returned List of Cells can
078   * inherit this implementation that does nothing.
079   *
080   * {@inheritDoc}
081   */
082  @Override
083  public void filterRowCells(List<Cell> ignored) throws IOException {
084  }
085
086  /**
087   * Fitlers that never filter by modifying the returned List of Cells can
088   * inherit this implementation that does nothing.
089   *
090   * {@inheritDoc}
091   */
092  @Override
093  public boolean hasFilterRow() {
094    return false;
095  }
096
097  /**
098   * Filters that never filter by rows based on previously gathered state from
099   * {@link #filterCell(Cell)} can inherit this implementation that
100   * never filters a row.
101   *
102   * {@inheritDoc}
103   */
104  @Override
105  public boolean filterRow() throws IOException {
106    return false;
107  }
108
109  /**
110   * Filters that are not sure which key must be next seeked to, can inherit
111   * this implementation that, by default, returns a null Cell.
112   *
113   * {@inheritDoc}
114   */
115  @Override
116  public Cell getNextCellHint(Cell currentCell) throws IOException {
117    return null;
118  }
119
120  /**
121   * By default, we require all scan's column families to be present. Our
122   * subclasses may be more precise.
123   *
124   * {@inheritDoc}
125   */
126  @Override
127  public boolean isFamilyEssential(byte[] name) throws IOException {
128    return true;
129  }
130
131  /**
132   * Given the filter's arguments it constructs the filter
133   * <p>
134   * @param filterArguments the filter's arguments
135   * @return constructed filter object
136   */
137  public static Filter createFilterFromArguments(ArrayList<byte []> filterArguments) {
138    throw new IllegalArgumentException("This method has not been implemented");
139  }
140
141  /**
142   * Return filter's info for debugging and logging purpose.
143   */
144  @Override
145  public String toString() {
146    return this.getClass().getSimpleName();
147  }
148
149  /**
150   * Return length 0 byte array for Filters that don't require special serialization
151   */
152  @Override
153  public byte[] toByteArray() throws IOException {
154    return new byte[0];
155  }
156
157  /**
158   * Default implementation so that writers of custom filters aren't forced to implement.
159   *
160   * @param other
161   * @return true if and only if the fields of the filter that are serialized
162   * are equal to the corresponding fields in other.  Used for testing.
163   */
164  @Override
165  boolean areSerializedFieldsEqual(Filter other) {
166    return true;
167  }
168}