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 */
019package org.apache.hadoop.hbase.regionserver.querymatcher;
020
021import java.io.IOException;
022
023import org.apache.hadoop.hbase.Cell;
024import org.apache.yetus.audience.InterfaceAudience;
025import org.apache.hadoop.hbase.regionserver.ShipperListener;
026import org.apache.hadoop.hbase.regionserver.querymatcher.ScanQueryMatcher.MatchCode;
027
028/**
029 * Implementing classes of this interface will be used for the tracking
030 * and enforcement of columns and numbers of versions and timeToLive during
031 * the course of a Get or Scan operation.
032 * <p>
033 * Currently there are two different types of Store/Family-level queries.
034 * <ul><li>{@link ExplicitColumnTracker} is used when the query specifies
035 * one or more column qualifiers to return in the family.</li>
036 * <li>{@link ScanWildcardColumnTracker} is used when no columns are
037 * explicitly specified.</li>
038 * </ul>
039 * <p>
040 * This class is utilized by {@link ScanQueryMatcher} mainly through two methods:
041 * <ul><li>{@link #checkColumn} is called when a Put satisfies all other
042 * conditions of the query.</li>
043 * <li>{@link #getNextRowOrNextColumn} is called whenever ScanQueryMatcher
044 * believes that the current column should be skipped (by timestamp, filter etc.)</li>
045 * </ul>
046 * <p>
047 * These two methods returns a
048 * {@link org.apache.hadoop.hbase.regionserver.querymatcher.ScanQueryMatcher.MatchCode}
049 * to define what action should be taken.
050 * <p>
051 * This class is NOT thread-safe as queries are never multi-threaded
052 */
053@InterfaceAudience.Private
054public interface ColumnTracker extends ShipperListener {
055
056  /**
057   * Checks if the column is present in the list of requested columns by returning the match code
058   * instance. It does not check against the number of versions for the columns asked for. To do the
059   * version check, one has to call {@link #checkVersions(Cell, long, byte, boolean)}
060   * method based on the return type (INCLUDE) of this method. The values that can be returned by
061   * this method are {@link MatchCode#INCLUDE}, {@link MatchCode#SEEK_NEXT_COL} and
062   * {@link MatchCode#SEEK_NEXT_ROW}.
063   * @param cell a cell with the column to match against
064   * @param type The type of the Cell
065   * @return The match code instance.
066   * @throws IOException in case there is an internal consistency problem caused by a data
067   *           corruption.
068   */
069  ScanQueryMatcher.MatchCode checkColumn(Cell cell, byte type) throws IOException;
070
071  /**
072   * Keeps track of the number of versions for the columns asked for. It assumes that the user has
073   * already checked if the cell needs to be included by calling the
074   * {@link #checkColumn(Cell, byte)} method. The enum values returned by this method
075   * are {@link MatchCode#SKIP}, {@link MatchCode#INCLUDE},
076   * {@link MatchCode#INCLUDE_AND_SEEK_NEXT_COL} and {@link MatchCode#INCLUDE_AND_SEEK_NEXT_ROW}.
077   * Implementations which include all the columns could just return {@link MatchCode#INCLUDE} in
078   * the {@link #checkColumn(Cell, byte)} method and perform all the operations in this
079   * checkVersions method.
080   * @param cell a cell with the column to match against
081   * @param timestamp The timestamp of the cell.
082   * @param type the type of the key value (Put/Delete)
083   * @param ignoreCount indicates if the KV needs to be excluded while counting (used during
084   *          compactions. We only count KV's that are older than all the scanners' read points.)
085   * @return the scan query matcher match code instance
086   * @throws IOException in case there is an internal consistency problem caused by a data
087   *           corruption.
088   */
089  ScanQueryMatcher.MatchCode checkVersions(Cell cell, long timestamp, byte type,
090      boolean ignoreCount) throws IOException;
091  /**
092   * Resets the Matcher
093   */
094  void reset();
095
096  /**
097   *
098   * @return <code>true</code> when done.
099   */
100  boolean done();
101
102  /**
103   * Used by matcher and scan/get to get a hint of the next column
104   * to seek to after checkColumn() returns SKIP.  Returns the next interesting
105   * column we want, or NULL there is none (wildcard scanner).
106   *
107   * Implementations aren't required to return anything useful unless the most recent
108   * call was to checkColumn() and the return code was SKIP.  This is pretty implementation
109   * detail-y, but optimizations are like that.
110   *
111   * @return null, or a ColumnCount that we should seek to
112   */
113  ColumnCount getColumnHint();
114
115  /**
116   * Retrieve the MatchCode for the next row or column
117   * @param cell
118   */
119  MatchCode getNextRowOrNextColumn(Cell cell);
120
121  /**
122   * Give the tracker a chance to declare it's done based on only the timestamp
123   * to allow an early out.
124   *
125   * @param timestamp
126   * @return <code>true</code> to early out based on timestamp.
127   */
128  boolean isDone(long timestamp);
129
130  /**
131   * This method is used to inform the column tracker that we are done with this column. We may get
132   * this information from external filters or timestamp range and we then need to indicate this
133   * information to tracker. It is currently implemented for ExplicitColumnTracker.
134   * @param cell
135   */
136  default void doneWithColumn(Cell cell) {
137  }
138}