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