1 /**
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18
19 package org.apache.hadoop.hbase.codec.prefixtree.scanner;
20
21 import org.apache.hadoop.hbase.classification.InterfaceAudience;
22 import org.apache.hadoop.hbase.Cell;
23
24 /**
25 * Methods for seeking to a random {@link Cell} inside a sorted collection of cells. Indicates that
26 * the implementation is able to navigate between cells without iterating through every cell.
27 */
28 @InterfaceAudience.Private
29 public interface CellSearcher extends ReversibleCellScanner {
30 /**
31 * Reset any state in the scanner so it appears it was freshly opened.
32 */
33 void resetToBeforeFirstEntry();
34
35 /**
36 * <p>
37 * Do everything within this scanner's power to find the key. Look forward and backwards.
38 * </p>
39 * <p>
40 * Abort as soon as we know it can't be found, possibly leaving the Searcher in an invalid state.
41 * </p>
42 * @param key position the CellScanner exactly on this key
43 * @return true if the cell existed and getCurrentCell() holds a valid cell
44 */
45 boolean positionAt(Cell key);
46
47 /**
48 * <p>
49 * Same as positionAt(..), but go to the extra effort of finding the previous key if there's no
50 * exact match.
51 * </p>
52 * @param key position the CellScanner on this key or the closest cell before
53 * @return AT if exact match<br>
54 * BEFORE if on last cell before key<br>
55 * BEFORE_FIRST if key was before the first cell in this scanner's scope
56 */
57 CellScannerPosition positionAtOrBefore(Cell key);
58
59 /**
60 * <p>
61 * Same as positionAt(..), but go to the extra effort of finding the next key if there's no exact
62 * match.
63 * </p>
64 * @param key position the CellScanner on this key or the closest cell after
65 * @return AT if exact match<br>
66 * AFTER if on first cell after key<br>
67 * AFTER_LAST if key was after the last cell in this scanner's scope
68 */
69 CellScannerPosition positionAtOrAfter(Cell key);
70
71 /**
72 * <p>
73 * Note: Added for backwards compatibility with
74 * {@link org.apache.hadoop.hbase.regionserver.KeyValueScanner#reseek}
75 * </p><p>
76 * Look for the key, but only look after the current position. Probably not needed for an
77 * efficient tree implementation, but is important for implementations without random access such
78 * as unencoded KeyValue blocks.
79 * </p>
80 * @param key position the CellScanner exactly on this key
81 * @return true if getCurrent() holds a valid cell
82 */
83 boolean seekForwardTo(Cell key);
84
85 /**
86 * <p>
87 * Same as seekForwardTo(..), but go to the extra effort of finding the next key if there's no
88 * exact match.
89 * </p>
90 * @param key
91 * @return AT if exact match<br>
92 * AFTER if on first cell after key<br>
93 * AFTER_LAST if key was after the last cell in this scanner's scope
94 */
95 CellScannerPosition seekForwardToOrBefore(Cell key);
96
97 /**
98 * <p>
99 * Same as seekForwardTo(..), but go to the extra effort of finding the next key if there's no
100 * exact match.
101 * </p>
102 * @param key
103 * @return AT if exact match<br>
104 * AFTER if on first cell after key<br>
105 * AFTER_LAST if key was after the last cell in this scanner's scope
106 */
107 CellScannerPosition seekForwardToOrAfter(Cell key);
108
109 /**
110 * <p>
111 * Note: This may not be appropriate to have in the interface. Need to investigate.
112 * </p>
113 * Position the scanner in an invalid state after the last cell: CellScannerPosition.AFTER_LAST.
114 * This is used by tests and for handling certain edge cases.
115 */
116 void positionAfterLastCell();
117
118 }