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 }