View Javadoc

1   /**
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  package org.apache.hadoop.hbase.codec;
19  
20  import java.io.IOException;
21  
22  import org.apache.hadoop.classification.InterfaceAudience;
23  import org.apache.hadoop.classification.InterfaceStability;
24  import org.apache.hadoop.hbase.KeyValue;
25  
26  /**
27   * An interface for iterating through a sequence of KeyValues. Similar to Java's Iterator, but
28   * without the hasNext() or remove() methods. The hasNext() method is problematic because it may
29   * require actually loading the next object, which in turn requires storing the previous object
30   * somewhere.
31   * <p>
32   * The core data block decoder should be as fast as possible, so we push the complexity and
33   * performance expense of concurrently tracking multiple cells to layers above the {@link Decoder}.
34   * <p>
35   * The {@link #current()} method will return a reference to a the decodable type.
36   * <p/>
37   * Typical usage:
38   *
39   * <pre>
40   * while (scanner.next()) {
41   *   KeyValue kv = scanner.get();
42   *   // do something
43   * }
44   * </pre>
45   */
46  @InterfaceAudience.Private
47  @InterfaceStability.Unstable
48  public interface Decoder {
49    /**
50     * @return the current object which may be mutable
51     */
52    KeyValue current();
53  
54    /**
55     * Advance the scanner 1 object
56     * @return true if the next cell is found and {@link #current()} will return a valid object
57     * @throws IOException if there is an error reading the next entry
58     */
59    boolean advance() throws IOException;
60  }