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.IOException;
22  import java.nio.ByteBuffer;
23  
24  import org.apache.hadoop.hbase.classification.InterfaceAudience;
25  import org.apache.hadoop.hbase.regionserver.Shipper;
26  import org.apache.hadoop.hbase.Cell;
27  
28  /**
29   * A scanner allows you to position yourself within a HFile and
30   * scan through it.  It allows you to reposition yourself as well.
31   *
32   * <p>A scanner doesn't always have a key/value that it is pointing to
33   * when it is first created and before
34   * {@link #seekTo()}/{@link #seekTo(Cell)} are called.
35   * In this case, {@link #getKey()}/{@link #getValue()} returns null.  At most
36   * other times, a key and value will be available.  The general pattern is that
37   * you position the Scanner using the seekTo variants and then getKey and
38   * getValue.
39   */
40  @InterfaceAudience.Private
41  public interface HFileScanner extends Shipper {
42    /**
43     * SeekTo or just before the passed <code>cell</code>.  Examine the return
44     * code to figure whether we found the cell or not.
45     * Consider the cell stream of all the cells in the file,
46     * <code>c[0] .. c[n]</code>, where there are n cells in the file.
47     * @param cell
48     * @return -1, if cell &lt; c[0], no position;
49     * 0, such that c[i] = cell and scanner is left in position i; and
50     * 1, such that c[i] &lt; cell, and scanner is left in position i.
51     * The scanner will position itself between c[i] and c[i+1] where
52     * c[i] &lt; cell &lt;= c[i+1].
53     * If there is no cell c[i+1] greater than or equal to the input cell, then the
54     * scanner will position itself at the end of the file and next() will return
55     * false when it is called.
56     * @throws IOException
57     */
58    int seekTo(Cell cell) throws IOException;
59  
60    /**
61     * Reseek to or just before the passed <code>cell</code>. Similar to seekTo
62     * except that this can be called even if the scanner is not at the beginning
63     * of a file.
64     * This can be used to seek only to cells which come after the current position
65     * of the scanner.
66     * Consider the cell stream of all the cells in the file,
67     * <code>c[0] .. c[n]</code>, where there are n cellc in the file after
68     * current position of HFileScanner.
69     * The scanner will position itself between c[i] and c[i+1] where
70     * c[i] &lt; cell &lt;= c[i+1].
71     * If there is no cell c[i+1] greater than or equal to the input cell, then the
72     * scanner will position itself at the end of the file and next() will return
73     * false when it is called.
74     * @param cell Cell to find (should be non-null)
75     * @return -1, if cell &lt; c[0], no position;
76     * 0, such that c[i] = cell and scanner is left in position i; and
77     * 1, such that c[i] &lt; cell, and scanner is left in position i.
78     * @throws IOException
79     */
80    int reseekTo(Cell cell) throws IOException;
81  
82    /**
83     * Consider the cell stream of all the cells in the file,
84     * <code>c[0] .. c[n]</code>, where there are n cells in the file.
85     * @param cell Cell to find
86     * @return false if cell &lt;= c[0] or true with scanner in position 'i' such
87     * that: c[i] &lt; cell.  Furthermore: there may be a c[i+1], such that
88     * c[i] &lt; cell &lt;= c[i+1] but there may also NOT be a c[i+1], and next() will
89     * return false (EOF).
90     * @throws IOException
91     */
92    boolean seekBefore(Cell cell) throws IOException;
93  
94    /**
95     * Positions this scanner at the start of the file.
96     * @return False if empty file; i.e. a call to next would return false and
97     * the current key and value are undefined.
98     * @throws IOException
99     */
100   boolean seekTo() throws IOException;
101   /**
102    * Scans to the next entry in the file.
103    * @return Returns false if you are at the end otherwise true if more in file.
104    * @throws IOException
105    */
106   boolean next() throws IOException;
107   /**
108    * Gets a buffer view to the current key. You must call
109    * {@link #seekTo(Cell)} before this method.
110    * @return byte buffer for the key. The limit is set to the key size, and the
111    * position is 0, the start of the buffer view.
112    */
113   ByteBuffer getKey();
114   /**
115    * Gets a buffer view to the current value.  You must call
116    * {@link #seekTo(Cell)} before this method.
117    *
118    * @return byte buffer for the value. The limit is set to the value size, and
119    * the position is 0, the start of the buffer view.
120    */
121   ByteBuffer getValue();
122   /**
123    * @return Instance of {@link org.apache.hadoop.hbase.KeyValue}.
124    */
125   Cell getKeyValue();
126   /**
127    * Convenience method to get a copy of the key as a string - interpreting the
128    * bytes as UTF8. You must call {@link #seekTo(Cell)} before this method.
129    * @return key as a string
130    */
131   String getKeyString();
132   /**
133    * Convenience method to get a copy of the value as a string - interpreting
134    * the bytes as UTF8. You must call {@link #seekTo(Cell)} before this method.
135    * @return value as a string
136    */
137   String getValueString();
138   /**
139    * @return Reader that underlies this Scanner instance.
140    */
141   HFile.Reader getReader();
142   /**
143    * @return True is scanner has had one of the seek calls invoked; i.e.
144    * {@link #seekBefore(Cell)} or {@link #seekTo()} or {@link #seekTo(Cell)}.
145    * Otherwise returns false.
146    */
147   boolean isSeeked();
148 
149   /**
150    * @return the next key in the index (the key to seek to the next block)
151    */
152   Cell getNextIndexedKey();
153 
154   /**
155    * Close this HFile scanner and do necessary cleanup.
156    */
157   void close();
158 }