View Javadoc

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 }