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.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 }