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  package org.apache.hadoop.hbase.regionserver;
20  
21  import java.io.IOException;
22  
23  import org.apache.hadoop.hbase.Cell;
24  import org.apache.hadoop.hbase.classification.InterfaceAudience;
25  import org.apache.hadoop.hbase.regionserver.ScanQueryMatcher.MatchCode;
26  
27  /**
28   * Implementing classes of this interface will be used for the tracking
29   * and enforcement of columns and numbers of versions and timeToLive during
30   * the course of a Get or Scan operation.
31   * <p>
32   * Currently there are two different types of Store/Family-level queries.
33   * <ul><li>{@link ExplicitColumnTracker} is used when the query specifies
34   * one or more column qualifiers to return in the family.</li>
35   * <li>{@link ScanWildcardColumnTracker} is used when no columns are
36   * explicitly specified.</li>
37   * </ul>
38   * <p>
39   * This class is utilized by {@link ScanQueryMatcher} mainly through two methods:
40   * <ul><li>{@link #checkColumn} is called when a Put satisfies all other
41   * conditions of the query.</li>
42   * <li>{@link #getNextRowOrNextColumn} is called whenever ScanQueryMatcher
43   * believes that the current column should be skipped (by timestamp, filter etc.)</li>
44   * </ul>
45   * <p>
46   * These two methods returns a 
47   * {@link org.apache.hadoop.hbase.regionserver.ScanQueryMatcher.MatchCode}
48   * to define what action should be taken.
49   * <p>
50   * This class is NOT thread-safe as queries are never multi-threaded
51   */
52  @InterfaceAudience.Private
53  public interface ColumnTracker {
54  
55    /**
56     * Checks if the column is present in the list of requested columns by returning the match code
57     * instance. It does not check against the number of versions for the columns asked for. To do the
58     * version check, one has to call {@link #checkVersions(Cell, long, byte, boolean)}
59     * method based on the return type (INCLUDE) of this method. The values that can be returned by
60     * this method are {@link MatchCode#INCLUDE}, {@link MatchCode#SEEK_NEXT_COL} and
61     * {@link MatchCode#SEEK_NEXT_ROW}.
62     * @param cell
63     * @param type The type of the KeyValue
64     * @return The match code instance.
65     * @throws IOException in case there is an internal consistency problem caused by a data
66     *           corruption.
67     */
68    ScanQueryMatcher.MatchCode checkColumn(Cell cell, byte type) throws IOException;
69  
70    /**
71     * Keeps track of the number of versions for the columns asked for. It assumes that the user has
72     * already checked if the keyvalue needs to be included by calling the
73     * {@link #checkColumn(Cell, byte)} method. The enum values returned by this method
74     * are {@link MatchCode#SKIP}, {@link MatchCode#INCLUDE},
75     * {@link MatchCode#INCLUDE_AND_SEEK_NEXT_COL} and {@link MatchCode#INCLUDE_AND_SEEK_NEXT_ROW}.
76     * Implementations which include all the columns could just return {@link MatchCode#INCLUDE} in
77     * the {@link #checkColumn(Cell, byte)} method and perform all the operations in this
78     * checkVersions method.
79     * @param cell
80     * @param ttl The timeToLive to enforce.
81     * @param type the type of the key value (Put/Delete)
82     * @param ignoreCount indicates if the KV needs to be excluded while counting (used during
83     *          compactions. We only count KV's that are older than all the scanners' read points.)
84     * @return the scan query matcher match code instance
85     * @throws IOException in case there is an internal consistency problem caused by a data
86     *           corruption.
87     */
88    ScanQueryMatcher.MatchCode checkVersions(Cell cell, long ttl, byte type, boolean ignoreCount)
89        throws IOException;
90    /**
91     * Resets the Matcher
92     */
93    void reset();
94  
95    /**
96     *
97     * @return <code>true</code> when done.
98     */
99    boolean done();
100 
101   /**
102    * Used by matcher and scan/get to get a hint of the next column
103    * to seek to after checkColumn() returns SKIP.  Returns the next interesting
104    * column we want, or NULL there is none (wildcard scanner).
105    *
106    * Implementations aren't required to return anything useful unless the most recent
107    * call was to checkColumn() and the return code was SKIP.  This is pretty implementation
108    * detail-y, but optimizations are like that.
109    *
110    * @return null, or a ColumnCount that we should seek to
111    */
112   ColumnCount getColumnHint();
113 
114   /**
115    * Retrieve the MatchCode for the next row or column
116    * @param cell
117    */
118   MatchCode getNextRowOrNextColumn(Cell cell);
119 
120   /**
121    * Give the tracker a chance to declare it's done based on only the timestamp
122    * to allow an early out.
123    *
124    * @param timestamp
125    * @return <code>true</code> to early out based on timestamp.
126    */
127   boolean isDone(long timestamp);
128 }