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 < 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] < 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] < cell <= 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] < cell <= 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 < 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] < 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 <= c[0] or true with scanner in position 'i' such 87 * that: c[i] < cell. Furthermore: there may be a c[i+1], such that 88 * c[i] < cell <= 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 the current key in the form of a cell. You must call 109 * {@link #seekTo(Cell)} before this method. 110 * @return gets the current key as a Cell. 111 */ 112 Cell getKey(); 113 /** 114 * Gets a buffer view to the current value. You must call 115 * {@link #seekTo(Cell)} before this method. 116 * 117 * @return byte buffer for the value. The limit is set to the value size, and 118 * the position is 0, the start of the buffer view. 119 */ 120 ByteBuffer getValue(); 121 /** 122 * @return Instance of {@link org.apache.hadoop.hbase.Cell}. 123 */ 124 Cell getCell(); 125 /** 126 * Convenience method to get a copy of the key as a string - interpreting the 127 * bytes as UTF8. You must call {@link #seekTo(Cell)} before this method. 128 * @return key as a string 129 */ 130 String getKeyString(); 131 /** 132 * Convenience method to get a copy of the value as a string - interpreting 133 * the bytes as UTF8. You must call {@link #seekTo(Cell)} before this method. 134 * @return value as a string 135 */ 136 String getValueString(); 137 /** 138 * @return Reader that underlies this Scanner instance. 139 */ 140 HFile.Reader getReader(); 141 /** 142 * @return True is scanner has had one of the seek calls invoked; i.e. 143 * {@link #seekBefore(Cell)} or {@link #seekTo()} or {@link #seekTo(Cell)}. 144 * Otherwise returns false. 145 */ 146 boolean isSeeked(); 147 148 /** 149 * @return the next key in the index (the key to seek to the next block) 150 */ 151 Cell getNextIndexedKey(); 152 153 /** 154 * Close this HFile scanner and do necessary cleanup. 155 */ 156 void close(); 157 }