View Javadoc

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 }