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.classification.InterfaceAudience;
25  import org.apache.hadoop.hbase.Cell;
26  import org.apache.hadoop.hbase.KeyValue;
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(byte[])} 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 {
42    /**
43     * SeekTo or just before the passed <code>key</code>.  Examine the return
44     * code to figure whether we found the key or not.
45     * Consider the key stream of all the keys in the file,
46     * <code>k[0] .. k[n]</code>, where there are n keys in the file.
47     * @param key Key to find.
48     * @return -1, if key < k[0], no position;
49     * 0, such that k[i] = key and scanner is left in position i; and
50     * 1, such that k[i] < key, and scanner is left in position i.
51     * The scanner will position itself between k[i] and k[i+1] where
52     * k[i] < key <= k[i+1].
53     * If there is no key k[i+1] greater than or equal to the input key, 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    @Deprecated
59    int seekTo(byte[] key) throws IOException;
60    @Deprecated
61    int seekTo(byte[] key, int offset, int length) throws IOException;
62  
63    int seekTo(Cell kv) throws IOException;
64    /**
65     * Reseek to or just before the passed <code>key</code>. Similar to seekTo
66     * except that this can be called even if the scanner is not at the beginning
67     * of a file.
68     * This can be used to seek only to keys which come after the current position
69     * of the scanner.
70     * Consider the key stream of all the keys in the file,
71     * <code>k[0] .. k[n]</code>, where there are n keys in the file after
72     * current position of HFileScanner.
73     * The scanner will position itself between k[i] and k[i+1] where
74     * k[i] < key <= k[i+1].
75     * If there is no key k[i+1] greater than or equal to the input key, then the
76     * scanner will position itself at the end of the file and next() will return
77     * false when it is called.
78     * @param key Key to find (should be non-null)
79     * @return -1, if key < k[0], no position;
80     * 0, such that k[i] = key and scanner is left in position i; and
81     * 1, such that k[i] < key, and scanner is left in position i.
82     * @throws IOException
83     */
84    @Deprecated
85    int reseekTo(byte[] key) throws IOException;
86    @Deprecated
87    int reseekTo(byte[] key, int offset, int length) throws IOException;
88  
89    int reseekTo(Cell kv) throws IOException;
90    /**
91     * Consider the key stream of all the keys in the file,
92     * <code>k[0] .. k[n]</code>, where there are n keys in the file.
93     * @param key Key to find
94     * @return false if key <= k[0] or true with scanner in position 'i' such
95     * that: k[i] < key.  Furthermore: there may be a k[i+1], such that
96     * k[i] < key <= k[i+1] but there may also NOT be a k[i+1], and next() will
97     * return false (EOF).
98     * @throws IOException
99     */
100   @Deprecated
101   boolean seekBefore(byte[] key) throws IOException;
102   @Deprecated
103   boolean seekBefore(byte[] key, int offset, int length) throws IOException;
104 
105   boolean seekBefore(Cell kv) throws IOException;
106   /**
107    * Positions this scanner at the start of the file.
108    * @return False if empty file; i.e. a call to next would return false and
109    * the current key and value are undefined.
110    * @throws IOException
111    */
112   boolean seekTo() throws IOException;
113   /**
114    * Scans to the next entry in the file.
115    * @return Returns false if you are at the end otherwise true if more in file.
116    * @throws IOException
117    */
118   boolean next() throws IOException;
119   /**
120    * Gets a buffer view to the current key. You must call
121    * {@link #seekTo(byte[])} before this method.
122    * @return byte buffer for the key. The limit is set to the key size, and the
123    * position is 0, the start of the buffer view.
124    */
125   ByteBuffer getKey();
126   /**
127    * Gets a buffer view to the current value.  You must call
128    * {@link #seekTo(byte[])} before this method.
129    *
130    * @return byte buffer for the value. The limit is set to the value size, and
131    * the position is 0, the start of the buffer view.
132    */
133   ByteBuffer getValue();
134   /**
135    * @return Instance of {@link KeyValue}.
136    */
137   Cell getKeyValue();
138   /**
139    * Convenience method to get a copy of the key as a string - interpreting the
140    * bytes as UTF8. You must call {@link #seekTo(byte[])} before this method.
141    * @return key as a string
142    */
143   String getKeyString();
144   /**
145    * Convenience method to get a copy of the value as a string - interpreting
146    * the bytes as UTF8. You must call {@link #seekTo(byte[])} before this method.
147    * @return value as a string
148    */
149   String getValueString();
150   /**
151    * @return Reader that underlies this Scanner instance.
152    */
153   HFile.Reader getReader();
154   /**
155    * @return True is scanner has had one of the seek calls invoked; i.e.
156    * {@link #seekBefore(byte[])} or {@link #seekTo()} or {@link #seekTo(byte[])}.
157    * Otherwise returns false.
158    */
159   boolean isSeeked();
160 }