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  
19  package org.apache.hadoop.hbase;
20  
21  import java.io.IOException;
22  
23  import org.apache.hadoop.classification.InterfaceAudience;
24  import org.apache.hadoop.classification.InterfaceStability;
25  import org.apache.hadoop.hbase.Cell;
26  
27  /**
28   * An interface for iterating through a sequence of cells. Similar to Java's Iterator, but without
29   * the hasNext() or remove() methods. The hasNext() method is problematic because it may require
30   * actually loading the next object, which in turn requires storing the previous object somewhere.
31   *
32   * <p>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 CellScanner.
34   * <p>
35   * The {@link #current()} method will return a reference to a Cell implementation. This reference
36   * may or may not point to a reusable cell implementation, so users of the CellScanner should not,
37   * for example, accumulate a List of Cells. All of the references may point to the same object,
38   * which would be the latest state of the underlying Cell. In short, the Cell is mutable.
39   * <p/>
40   * Typical usage:
41   *
42   * <pre>
43   * while (scanner.advance()) {
44   *   Cell cell = scanner.current();
45   *   // do something
46   * }
47   * </pre>
48   * <p>Often used reading {@link org.apache.hadoop.hbase.Cell}s written by
49   * {@link org.apache.hadoop.hbase.io.CellOutputStream}.
50   */
51  @InterfaceAudience.Private
52  @InterfaceStability.Unstable
53  public interface CellScanner {
54    /**
55     * @return the current Cell which may be mutable
56     */
57    Cell current();
58  
59    /**
60     * Advance the scanner 1 cell.
61     * @return true if the next cell is found and {@link #current()} will return a valid Cell
62     * @throws IOException
63     */
64    boolean advance() throws IOException;
65  }