1 /** 2 * Copyright 2010 The Apache Software Foundation 3 * 4 * Licensed to the Apache Software Foundation (ASF) under one 5 * or more contributor license agreements. See the NOTICE file 6 * distributed with this work for additional information 7 * regarding copyright ownership. The ASF licenses this file 8 * to you under the Apache License, Version 2.0 (the 9 * "License"); you may not use this file except in compliance 10 * with the License. You may obtain a copy of the License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 14 * Unless required by applicable law or agreed to in writing, software 15 * distributed under the License is distributed on an "AS IS" BASIS, 16 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 17 * See the License for the specific language governing permissions and 18 * limitations under the License. 19 */ 20 package org.apache.hadoop.hbase.regionserver; 21 22 import java.io.IOException; 23 import java.util.SortedSet; 24 25 import org.apache.hadoop.hbase.KeyValue; 26 import org.apache.hadoop.hbase.client.Scan; 27 28 /** 29 * Scanner that returns the next KeyValue. 30 */ 31 public interface KeyValueScanner { 32 /** 33 * Look at the next KeyValue in this scanner, but do not iterate scanner. 34 * @return the next KeyValue 35 */ 36 public KeyValue peek(); 37 38 /** 39 * Return the next KeyValue in this scanner, iterating the scanner 40 * @return the next KeyValue 41 */ 42 public KeyValue next() throws IOException; 43 44 /** 45 * Seek the scanner at or after the specified KeyValue. 46 * @param key seek value 47 * @return true if scanner has values left, false if end of scanner 48 */ 49 public boolean seek(KeyValue key) throws IOException; 50 51 /** 52 * Reseek the scanner at or after the specified KeyValue. 53 * This method is guaranteed to seek at or after the required key only if the 54 * key comes after the current position of the scanner. Should not be used 55 * to seek to a key which may come before the current position. 56 * @param key seek value (should be non-null) 57 * @return true if scanner has values left, false if end of scanner 58 */ 59 public boolean reseek(KeyValue key) throws IOException; 60 61 /** 62 * Get the sequence id associated with this KeyValueScanner. This is required 63 * for comparing multiple files to find out which one has the latest data. 64 * The default implementation for this would be to return 0. A file having 65 * lower sequence id will be considered to be the older one. 66 */ 67 public long getSequenceID(); 68 69 /** 70 * Close the KeyValue scanner. 71 */ 72 public void close(); 73 74 /** 75 * Allows to filter out scanners (both StoreFile and memstore) that we don't 76 * want to use based on criteria such as Bloom filters and timestamp ranges. 77 * @param scan the scan that we are selecting scanners for 78 * @param columns the set of columns in the current column family, or null if 79 * not specified by the scan 80 * @param oldestUnexpiredTS the oldest timestamp we are interested in for 81 * this query, based on TTL 82 * @return true if the scanner should be included in the query 83 */ 84 public boolean shouldUseScanner(Scan scan, SortedSet<byte[]> columns, 85 long oldestUnexpiredTS); 86 87 // "Lazy scanner" optimizations 88 89 /** 90 * Similar to {@link #seek} (or {@link #reseek} if forward is true) but only 91 * does a seek operation after checking that it is really necessary for the 92 * row/column combination specified by the kv parameter. This function was 93 * added to avoid unnecessary disk seeks by checking row-column Bloom filters 94 * before a seek on multi-column get/scan queries, and to optimize by looking 95 * up more recent files first. 96 * @param forward do a forward-only "reseek" instead of a random-access seek 97 * @param useBloom whether to enable multi-column Bloom filter optimization 98 */ 99 public boolean requestSeek(KeyValue kv, boolean forward, boolean useBloom) 100 throws IOException; 101 102 /** 103 * We optimize our store scanners by checking the most recent store file 104 * first, so we sometimes pretend we have done a seek but delay it until the 105 * store scanner bubbles up to the top of the key-value heap. This method is 106 * then used to ensure the top store file scanner has done a seek operation. 107 */ 108 public boolean realSeekDone(); 109 110 /** 111 * Does the real seek operation in case it was skipped by 112 * seekToRowCol(KeyValue, boolean) (TODO: Whats this?). Note that this function should 113 * be never called on scanners that always do real seek operations (i.e. most 114 * of the scanners). The easiest way to achieve this is to call 115 * {@link #realSeekDone()} first. 116 */ 117 public void enforceSeek() throws IOException; 118 119 /** 120 * @return true if this is a file scanner. Otherwise a memory scanner is 121 * assumed. 122 */ 123 public boolean isFileScanner(); 124 }