001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.apache.hadoop.hbase.io.hfile;
019
020import java.io.Closeable;
021import java.io.IOException;
022import java.nio.ByteBuffer;
023import org.apache.hadoop.hbase.Cell;
024import org.apache.hadoop.hbase.regionserver.Shipper;
025import org.apache.yetus.audience.InterfaceAudience;
026
027/**
028 * A scanner allows you to position yourself within a HFile and scan through it. It allows you to
029 * reposition yourself as well.
030 * <p>
031 * A scanner doesn't always have a key/value that it is pointing to when it is first created and
032 * before {@link #seekTo()}/{@link #seekTo(Cell)} are called. In this case,
033 * {@link #getKey()}/{@link #getValue()} returns null. At most other times, a key and value will be
034 * available. The general pattern is that you position the Scanner using the seekTo variants and
035 * then getKey and getValue.
036 */
037@InterfaceAudience.Private
038public interface HFileScanner extends Shipper, Closeable {
039  /**
040   * SeekTo or just before the passed <code>cell</code>. Examine the return code to figure whether
041   * we found the cell or not. Consider the cell stream of all the cells in the file,
042   * <code>c[0] .. c[n]</code>, where there are n cells in the file. n * @return -1, if cell &lt;
043   * c[0], no position; 0, such that c[i] = cell and scanner is left in position i; and 1, such that
044   * c[i] &lt; cell, and scanner is left in position i. The scanner will position itself between
045   * c[i] and c[i+1] where c[i] &lt; cell &lt;= c[i+1]. If there is no cell c[i+1] greater than or
046   * equal to the input cell, then the scanner will position itself at the end of the file and
047   * next() will return false when it is called. n
048   */
049  int seekTo(Cell cell) throws IOException;
050
051  /**
052   * Reseek to or just before the passed <code>cell</code>. Similar to seekTo except that this can
053   * be called even if the scanner is not at the beginning of a file. This can be used to seek only
054   * to cells which come after the current position of the scanner. Consider the cell stream of all
055   * the cells in the file, <code>c[0] .. c[n]</code>, where there are n cellc in the file after
056   * current position of HFileScanner. The scanner will position itself between c[i] and c[i+1]
057   * where c[i] &lt; cell &lt;= c[i+1]. If there is no cell c[i+1] greater than or equal to the
058   * input cell, then the scanner will position itself at the end of the file and next() will return
059   * false when it is called.
060   * @param cell Cell to find (should be non-null)
061   * @return -1, if cell &lt; c[0], no position; 0, such that c[i] = cell and scanner is left in
062   *         position i; and 1, such that c[i] &lt; cell, and scanner is left in position i. n
063   */
064  int reseekTo(Cell cell) throws IOException;
065
066  /**
067   * Consider the cell stream of all the cells in the file, <code>c[0] .. c[n]</code>, where there
068   * are n cells in the file.
069   * @param cell Cell to find
070   * @return false if cell &lt;= c[0] or true with scanner in position 'i' such that: c[i] &lt;
071   *         cell. Furthermore: there may be a c[i+1], such that c[i] &lt; cell &lt;= c[i+1] but
072   *         there may also NOT be a c[i+1], and next() will return false (EOF). n
073   */
074  boolean seekBefore(Cell cell) throws IOException;
075
076  /**
077   * Positions this scanner at the start of the file.
078   * @return False if empty file; i.e. a call to next would return false and the current key and
079   *         value are undefined. n
080   */
081  boolean seekTo() throws IOException;
082
083  /**
084   * Scans to the next entry in the file.
085   * @return Returns false if you are at the end otherwise true if more in file. n
086   */
087  boolean next() throws IOException;
088
089  /**
090   * Gets the current key in the form of a cell. You must call {@link #seekTo(Cell)} before this
091   * method.
092   * @return gets the current key as a Cell.
093   */
094  Cell getKey();
095
096  /**
097   * Gets a buffer view to the current value. You must call {@link #seekTo(Cell)} before this
098   * method.
099   * @return byte buffer for the value. The limit is set to the value size, and the position is 0,
100   *         the start of the buffer view.
101   */
102  ByteBuffer getValue();
103
104  /**
105   * @return Instance of {@link org.apache.hadoop.hbase.Cell}.
106   */
107  Cell getCell();
108
109  /**
110   * Convenience method to get a copy of the key as a string - interpreting the bytes as UTF8. You
111   * must call {@link #seekTo(Cell)} before this method.
112   * @return key as a string
113   * @deprecated Since hbase-2.0.0
114   */
115  @Deprecated
116  String getKeyString();
117
118  /**
119   * Convenience method to get a copy of the value as a string - interpreting the bytes as UTF8. You
120   * must call {@link #seekTo(Cell)} before this method.
121   * @return value as a string
122   * @deprecated Since hbase-2.0.0
123   */
124  @Deprecated
125  String getValueString();
126
127  /**
128   * @return Reader that underlies this Scanner instance.
129   */
130  HFile.Reader getReader();
131
132  /**
133   * @return True is scanner has had one of the seek calls invoked; i.e. {@link #seekBefore(Cell)}
134   *         or {@link #seekTo()} or {@link #seekTo(Cell)}. Otherwise returns false.
135   */
136  boolean isSeeked();
137
138  /**
139   * @return the next key in the index (the key to seek to the next block)
140   */
141  Cell getNextIndexedKey();
142
143  /**
144   * Close this HFile scanner and do necessary cleanup.
145   */
146  @Override
147  void close();
148}