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.regionserver; 20 21 import java.io.IOException; 22 import java.util.SortedSet; 23 24 import org.apache.hadoop.hbase.classification.InterfaceAudience; 25 import org.apache.hadoop.hbase.Cell; 26 import org.apache.hadoop.hbase.client.Scan; 27 28 /** 29 * Scanner that returns the next KeyValue. 30 */ 31 @InterfaceAudience.Private 32 public interface KeyValueScanner { 33 /** 34 * Look at the next Cell in this scanner, but do not iterate scanner. 35 * @return the next Cell 36 */ 37 Cell peek(); 38 39 /** 40 * Return the next Cell in this scanner, iterating the scanner 41 * @return the next Cell 42 */ 43 Cell next() throws IOException; 44 45 /** 46 * Seek the scanner at or after the specified KeyValue. 47 * @param key seek value 48 * @return true if scanner has values left, false if end of scanner 49 */ 50 boolean seek(Cell key) throws IOException; 51 52 /** 53 * Reseek the scanner at or after the specified KeyValue. 54 * This method is guaranteed to seek at or after the required key only if the 55 * key comes after the current position of the scanner. Should not be used 56 * to seek to a key which may come before the current position. 57 * @param key seek value (should be non-null) 58 * @return true if scanner has values left, false if end of scanner 59 */ 60 boolean reseek(Cell key) throws IOException; 61 62 /** 63 * Get the sequence id associated with this KeyValueScanner. This is required 64 * for comparing multiple files to find out which one has the latest data. 65 * The default implementation for this would be to return 0. A file having 66 * lower sequence id will be considered to be the older one. 67 */ 68 long getSequenceID(); 69 70 /** 71 * Close the KeyValue scanner. 72 */ 73 void close(); 74 75 /** 76 * Allows to filter out scanners (both StoreFile and memstore) that we don't 77 * want to use based on criteria such as Bloom filters and timestamp ranges. 78 * @param scan the scan that we are selecting scanners for 79 * @param columns the set of columns in the current column family, or null if 80 * not specified by the scan 81 * @param oldestUnexpiredTS the oldest timestamp we are interested in for 82 * this query, based on TTL 83 * @return true if the scanner should be included in the query 84 */ 85 boolean shouldUseScanner( 86 Scan scan, SortedSet<byte[]> columns, long oldestUnexpiredTS 87 ); 88 89 // "Lazy scanner" optimizations 90 91 /** 92 * Similar to {@link #seek} (or {@link #reseek} if forward is true) but only 93 * does a seek operation after checking that it is really necessary for the 94 * row/column combination specified by the kv parameter. This function was 95 * added to avoid unnecessary disk seeks by checking row-column Bloom filters 96 * before a seek on multi-column get/scan queries, and to optimize by looking 97 * up more recent files first. 98 * @param forward do a forward-only "reseek" instead of a random-access seek 99 * @param useBloom whether to enable multi-column Bloom filter optimization 100 */ 101 boolean requestSeek(Cell kv, boolean forward, boolean useBloom) 102 throws IOException; 103 104 /** 105 * We optimize our store scanners by checking the most recent store file 106 * first, so we sometimes pretend we have done a seek but delay it until the 107 * store scanner bubbles up to the top of the key-value heap. This method is 108 * then used to ensure the top store file scanner has done a seek operation. 109 */ 110 boolean realSeekDone(); 111 112 /** 113 * Does the real seek operation in case it was skipped by 114 * seekToRowCol(KeyValue, boolean) (TODO: Whats this?). Note that this function should 115 * be never called on scanners that always do real seek operations (i.e. most 116 * of the scanners). The easiest way to achieve this is to call 117 * {@link #realSeekDone()} first. 118 */ 119 void enforceSeek() throws IOException; 120 121 /** 122 * @return true if this is a file scanner. Otherwise a memory scanner is 123 * assumed. 124 */ 125 boolean isFileScanner(); 126 127 // Support for "Reversed Scanner" 128 /** 129 * Seek the scanner at or before the row of specified Cell, it firstly 130 * tries to seek the scanner at or after the specified Cell, return if 131 * peek KeyValue of scanner has the same row with specified Cell, 132 * otherwise seek the scanner at the first Cell of the row which is the 133 * previous row of specified KeyValue 134 * 135 * @param key seek KeyValue 136 * @return true if the scanner is at the valid KeyValue, false if such 137 * KeyValue does not exist 138 * 139 */ 140 public boolean backwardSeek(Cell key) throws IOException; 141 142 /** 143 * Seek the scanner at the first Cell of the row which is the previous row 144 * of specified key 145 * @param key seek value 146 * @return true if the scanner at the first valid Cell of previous row, 147 * false if not existing such Cell 148 */ 149 public boolean seekToPreviousRow(Cell key) throws IOException; 150 151 /** 152 * Seek the scanner at the first KeyValue of last row 153 * 154 * @return true if scanner has values left, false if the underlying data is 155 * empty 156 * @throws IOException 157 */ 158 public boolean seekToLastRow() throws IOException; 159 160 /** 161 * @return the next key in the index (the key to seek to the next block) 162 * if known, or null otherwise 163 */ 164 public Cell getNextIndexedKey(); 165 }