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 * Do everything within this scanner's power to find the key. Look forward and backwards.
37 * <p/>
38 * Abort as soon as we know it can't be found, possibly leaving the Searcher in an invalid state.
39 * <p/>
40 * @param key position the CellScanner exactly on this key
41 * @return true if the cell existed and getCurrentCell() holds a valid cell
42 */
43 boolean positionAt(Cell key);
44
45 /**
46 * Same as positionAt(..), but go to the extra effort of finding the previous key if there's no
47 * exact match.
48 * <p/>
49 * @param key position the CellScanner on this key or the closest cell before
50 * @return AT if exact match<br/>
51 * BEFORE if on last cell before key<br/>
52 * BEFORE_FIRST if key was before the first cell in this scanner's scope
53 */
54 CellScannerPosition positionAtOrBefore(Cell key);
55
56 /**
57 * Same as positionAt(..), but go to the extra effort of finding the next key if there's no exact
58 * match.
59 * <p/>
60 * @param key position the CellScanner on this key or the closest cell after
61 * @return AT if exact match<br/>
62 * AFTER if on first cell after key<br/>
63 * AFTER_LAST if key was after the last cell in this scanner's scope
64 */
65 CellScannerPosition positionAtOrAfter(Cell key);
66
67 /**
68 * Note: Added for backwards compatibility with
69 * {@link org.apache.hadoop.hbase.regionserver.KeyValueScanner#reseek}
70 * <p/>
71 * Look for the key, but only look after the current position. Probably not needed for an
72 * efficient tree implementation, but is important for implementations without random access such
73 * as unencoded KeyValue blocks.
74 * <p/>
75 * @param key position the CellScanner exactly on this key
76 * @return true if getCurrent() holds a valid cell
77 */
78 boolean seekForwardTo(Cell key);
79
80 /**
81 * Same as seekForwardTo(..), but go to the extra effort of finding the next key if there's no
82 * exact match.
83 * <p/>
84 * @param key
85 * @return AT if exact match<br/>
86 * AFTER if on first cell after key<br/>
87 * AFTER_LAST if key was after the last cell in this scanner's scope
88 */
89 CellScannerPosition seekForwardToOrBefore(Cell key);
90
91 /**
92 * Same as seekForwardTo(..), but go to the extra effort of finding the next key if there's no
93 * exact match.
94 * <p/>
95 * @param key
96 * @return AT if exact match<br/>
97 * AFTER if on first cell after key<br/>
98 * AFTER_LAST if key was after the last cell in this scanner's scope
99 */
100 CellScannerPosition seekForwardToOrAfter(Cell key);
101
102 /**
103 * Note: This may not be appropriate to have in the interface. Need to investigate.
104 * <p/>
105 * Position the scanner in an invalid state after the last cell: CellScannerPosition.AFTER_LAST.
106 * This is used by tests and for handling certain edge cases.
107 */
108 void positionAfterLastCell();
109
110 }