1 /** 2 * Copyright 2009 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.io.hfile; 21 22 import java.io.IOException; 23 import java.nio.ByteBuffer; 24 import java.util.SortedSet; 25 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 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 * Furthermore, there may be a k[i+1], such that k[i] < key < k[i+1] 51 * but there may not be a k[i+1], and next() will return false (EOF). 52 * @throws IOException 53 */ 54 public int seekTo(byte[] key) throws IOException; 55 public int seekTo(byte[] key, int offset, int length) throws IOException; 56 /** 57 * Consider the key stream of all the keys in the file, 58 * <code>k[0] .. k[n]</code>, where there are n keys in the file. 59 * @param key Key to find 60 * @return false if key <= k[0] or true with scanner in position 'i' such 61 * that: k[i] < key. Furthermore: there may be a k[i+1], such that 62 * k[i] < key <= k[i+1] but there may also NOT be a k[i+1], and next() will 63 * return false (EOF). 64 * @throws IOException 65 */ 66 public boolean seekBefore(byte [] key) throws IOException; 67 public boolean seekBefore(byte []key, int offset, int length) throws IOException; 68 /** 69 * Positions this scanner at the start of the file. 70 * @return False if empty file; i.e. a call to next would return false and 71 * the current key and value are undefined. 72 * @throws IOException 73 */ 74 public boolean seekTo() throws IOException; 75 /** 76 * Scans to the next entry in the file. 77 * @return Returns false if you are at the end otherwise true if more in file. 78 * @throws IOException 79 */ 80 public boolean next() throws IOException; 81 /** 82 * Gets a buffer view to the current key. You must call 83 * {@link #seekTo(byte[])} before this method. 84 * @return byte buffer for the key. The limit is set to the key size, and the 85 * position is 0, the start of the buffer view. 86 */ 87 public ByteBuffer getKey(); 88 /** 89 * Gets a buffer view to the current value. You must call 90 * {@link #seekTo(byte[])} before this method. 91 * 92 * @return byte buffer for the value. The limit is set to the value size, and 93 * the position is 0, the start of the buffer view. 94 */ 95 public ByteBuffer getValue(); 96 /** 97 * @return Instance of {@link KeyValue}. 98 */ 99 public KeyValue getKeyValue(); 100 /** 101 * Convenience method to get a copy of the key as a string - interpreting the 102 * bytes as UTF8. You must call {@link #seekTo(byte[])} before this method. 103 * @return key as a string 104 */ 105 public String getKeyString(); 106 /** 107 * Convenience method to get a copy of the value as a string - interpreting 108 * the bytes as UTF8. You must call {@link #seekTo(byte[])} before this method. 109 * @return value as a string 110 */ 111 public String getValueString(); 112 /** 113 * @return Reader that underlies this Scanner instance. 114 */ 115 public HFile.Reader getReader(); 116 /** 117 * @return True is scanner has had one of the seek calls invoked; i.e. 118 * {@link #seekBefore(byte[])} or {@link #seekTo()} or {@link #seekTo(byte[])}. 119 * Otherwise returns false. 120 */ 121 public boolean isSeeked(); 122 }