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