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 }