View Javadoc

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 }