View Javadoc

1   /**
2    *
3    * Licensed to the Apache Software Foundation (ASF) under one
4    * or more contributor license agreements.  See the NOTICE file
5    * distributed with this work for additional information
6    * regarding copyright ownership.  The ASF licenses this file
7    * to you under the Apache License, Version 2.0 (the
8    * "License"); you may not use this file except in compliance
9    * with the License.  You may obtain a copy of the License at
10   *
11   *     http://www.apache.org/licenses/LICENSE-2.0
12   *
13   * Unless required by applicable law or agreed to in writing, software
14   * distributed under the License is distributed on an "AS IS" BASIS,
15   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16   * See the License for the specific language governing permissions and
17   * limitations under the License.
18   */
19  package org.apache.hadoop.hbase.io.hfile;
20  
21  import java.io.Closeable;
22  import java.io.IOException;
23  import java.nio.ByteBuffer;
24  
25  import org.apache.hadoop.hbase.classification.InterfaceAudience;
26  import org.apache.hadoop.hbase.regionserver.Shipper;
27  import org.apache.hadoop.hbase.Cell;
28  
29  /**
30   * A scanner allows you to position yourself within a HFile and
31   * scan through it.  It allows you to reposition yourself as well.
32   *
33   * <p>A scanner doesn't always have a key/value that it is pointing to
34   * when it is first created and before
35   * {@link #seekTo()}/{@link #seekTo(Cell)} are called.
36   * In this case, {@link #getKey()}/{@link #getValue()} returns null.  At most
37   * other times, a key and value will be available.  The general pattern is that
38   * you position the Scanner using the seekTo variants and then getKey and
39   * getValue.
40   */
41  @InterfaceAudience.Private
42  public interface HFileScanner extends Shipper, Closeable {
43    /**
44     * SeekTo or just before the passed <code>cell</code>.  Examine the return
45     * code to figure whether we found the cell or not.
46     * Consider the cell stream of all the cells in the file,
47     * <code>c[0] .. c[n]</code>, where there are n cells in the file.
48     * @param cell
49     * @return -1, if cell &lt; c[0], no position;
50     * 0, such that c[i] = cell and scanner is left in position i; and
51     * 1, such that c[i] &lt; cell, and scanner is left in position i.
52     * The scanner will position itself between c[i] and c[i+1] where
53     * c[i] &lt; cell &lt;= c[i+1].
54     * If there is no cell c[i+1] greater than or equal to the input cell, then the
55     * scanner will position itself at the end of the file and next() will return
56     * false when it is called.
57     * @throws IOException
58     */
59    int seekTo(Cell cell) throws IOException;
60  
61    /**
62     * Reseek to or just before the passed <code>cell</code>. Similar to seekTo
63     * except that this can be called even if the scanner is not at the beginning
64     * of a file.
65     * This can be used to seek only to cells which come after the current position
66     * of the scanner.
67     * Consider the cell stream of all the cells in the file,
68     * <code>c[0] .. c[n]</code>, where there are n cellc in the file after
69     * current position of HFileScanner.
70     * The scanner will position itself between c[i] and c[i+1] where
71     * c[i] &lt; cell &lt;= c[i+1].
72     * If there is no cell c[i+1] greater than or equal to the input cell, then the
73     * scanner will position itself at the end of the file and next() will return
74     * false when it is called.
75     * @param cell Cell to find (should be non-null)
76     * @return -1, if cell &lt; c[0], no position;
77     * 0, such that c[i] = cell and scanner is left in position i; and
78     * 1, such that c[i] &lt; cell, and scanner is left in position i.
79     * @throws IOException
80     */
81    int reseekTo(Cell cell) throws IOException;
82  
83    /**
84     * Consider the cell stream of all the cells in the file,
85     * <code>c[0] .. c[n]</code>, where there are n cells in the file.
86     * @param cell Cell to find
87     * @return false if cell &lt;= c[0] or true with scanner in position 'i' such
88     * that: c[i] &lt; cell.  Furthermore: there may be a c[i+1], such that
89     * c[i] &lt; cell &lt;= c[i+1] but there may also NOT be a c[i+1], and next() will
90     * return false (EOF).
91     * @throws IOException
92     */
93    boolean seekBefore(Cell cell) throws IOException;
94  
95    /**
96     * Positions this scanner at the start of the file.
97     * @return False if empty file; i.e. a call to next would return false and
98     * the current key and value are undefined.
99     * @throws IOException
100    */
101   boolean seekTo() throws IOException;
102 
103   /**
104    * Scans to the next entry in the file.
105    * @return Returns false if you are at the end otherwise true if more in file.
106    * @throws IOException
107    */
108   boolean next() throws IOException;
109 
110   /**
111    * Gets the current key in the form of a cell. You must call
112    * {@link #seekTo(Cell)} before this method.
113    * @return gets the current key as a Cell.
114    */
115   Cell getKey();
116 
117   /**
118    * Gets a buffer view to the current value.  You must call
119    * {@link #seekTo(Cell)} before this method.
120    *
121    * @return byte buffer for the value. The limit is set to the value size, and
122    * the position is 0, the start of the buffer view.
123    */
124   ByteBuffer getValue();
125 
126   /**
127    * @return Instance of {@link org.apache.hadoop.hbase.Cell}.
128    */
129   Cell getCell();
130 
131   /**
132    * Convenience method to get a copy of the key as a string - interpreting the
133    * bytes as UTF8. You must call {@link #seekTo(Cell)} before this method.
134    * @return key as a string
135    * @deprecated Since hbase-2.0.0
136    */
137   @Deprecated
138   String getKeyString();
139 
140   /**
141    * Convenience method to get a copy of the value as a string - interpreting
142    * the bytes as UTF8. You must call {@link #seekTo(Cell)} before this method.
143    * @return value as a string
144    * @deprecated Since hbase-2.0.0
145    */
146   @Deprecated
147   String getValueString();
148 
149   /**
150    * @return Reader that underlies this Scanner instance.
151    */
152   HFile.Reader getReader();
153 
154   /**
155    * @return True is scanner has had one of the seek calls invoked; i.e.
156    * {@link #seekBefore(Cell)} or {@link #seekTo()} or {@link #seekTo(Cell)}.
157    * Otherwise returns false.
158    */
159   boolean isSeeked();
160 
161   /**
162    * @return the next key in the index (the key to seek to the next block)
163    */
164   Cell getNextIndexedKey();
165 
166   /**
167    * Close this HFile scanner and do necessary cleanup.
168    */
169   void close();
170 }