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