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.
34 * <ul><li>{@link ScanWildcardColumnTracker} is used when no columns are
35 * explicitly specified.
36 * <p>
37 * This class is utilized by {@link ScanQueryMatcher} mainly through two methods:
38 * <ul><li>{@link #checkColumn} is called when a Put satisfies all other
39 * conditions of the query.
40 * <ul><li>{@link #getNextRowOrNextColumn} is called whenever ScanQueryMatcher
41 * believes that the current column should be skipped (by timestamp, filter etc.)
42 * <p>
43 * These two methods returns a
44 * {@link org.apache.hadoop.hbase.regionserver.ScanQueryMatcher.MatchCode}
45 * to define what action should be taken.
46 * <p>
47 * This class is NOT thread-safe as queries are never multi-threaded
48 */
49 @InterfaceAudience.Private
50 public interface ColumnTracker {
51
52 /**
53 * Checks if the column is present in the list of requested columns by returning the match code
54 * instance. It does not check against the number of versions for the columns asked for. To do the
55 * version check, one has to call {@link #checkVersions(byte[], int, int, long, byte, boolean)}
56 * method based on the return type (INCLUDE) of this method. The values that can be returned by
57 * this method are {@link MatchCode#INCLUDE}, {@link MatchCode#SEEK_NEXT_COL} and
58 * {@link MatchCode#SEEK_NEXT_ROW}.
59 * @param bytes
60 * @param offset
61 * @param length
62 * @param type The type of the KeyValue
63 * @return The match code instance.
64 * @throws IOException in case there is an internal consistency problem caused by a data
65 * corruption.
66 */
67 ScanQueryMatcher.MatchCode checkColumn(byte[] bytes, int offset, int length, byte type)
68 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(byte[], int, int, 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(byte[], int, int, byte)} method and perform all the operations in this
78 * checkVersions method.
79 * @param type the type of the key value (Put/Delete)
80 * @param ttl The timeToLive to enforce.
81 * @param ignoreCount indicates if the KV needs to be excluded while counting (used during
82 * compactions. We only count KV's that are older than all the scanners' read points.)
83 * @return the scan query matcher match code instance
84 * @throws IOException in case there is an internal consistency problem caused by a data
85 * corruption.
86 */
87 ScanQueryMatcher.MatchCode checkVersions(byte[] bytes, int offset, int length, long ttl,
88 byte type, boolean ignoreCount) throws IOException;
89 /**
90 * Resets the Matcher
91 */
92 void reset();
93
94 /**
95 *
96 * @return <code>true</code> when done.
97 */
98 boolean done();
99
100 /**
101 * Used by matcher and scan/get to get a hint of the next column
102 * to seek to after checkColumn() returns SKIP. Returns the next interesting
103 * column we want, or NULL there is none (wildcard scanner).
104 *
105 * Implementations aren't required to return anything useful unless the most recent
106 * call was to checkColumn() and the return code was SKIP. This is pretty implementation
107 * detail-y, but optimizations are like that.
108 *
109 * @return null, or a ColumnCount that we should seek to
110 */
111 ColumnCount getColumnHint();
112
113 /**
114 * Retrieve the MatchCode for the next row or column
115 */
116 MatchCode getNextRowOrNextColumn(
117 byte[] bytes, int offset, int qualLength
118 );
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 }