hbase-server/src/main/java/org/apache/hadoop/hbase/regionserver/RegionScanner.java

   1 /**
   2  *
   3  * Licensed to the Apache Software Foundation (ASF) under one
   4  * or more contributor license agreements.  See the NOTICE file
   5  * distributed with this work for additional information
   6  * regarding copyright ownership.  The ASF licenses this file
   7  * to you under the Apache License, Version 2.0 (the
   8  * "License"); you may not use this file except in compliance
   9  * with the License.  You may obtain a copy of the License at
  10  *
  11  *     http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  */
  19 package org.apache.hadoop.hbase.regionserver;
  20
  21 import java.io.IOException;
  22 import java.util.List;
  23
  24 import org.apache.hadoop.hbase.Cell;
  25 import org.apache.hadoop.hbase.HBaseInterfaceAudience;
  26 import org.apache.hadoop.hbase.client.RegionInfo;
  27 import org.apache.yetus.audience.InterfaceAudience;
  28 import org.apache.yetus.audience.InterfaceStability;
  29
  30 /**
  31  * RegionScanner describes iterators over rows in an HRegion.
  32  */
  33 @InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.COPROC)
  34 @InterfaceStability.Evolving
  35 public interface RegionScanner extends InternalScanner {
  36   /**
  37    * @return The RegionInfo for this scanner.
  38    */
  39   RegionInfo getRegionInfo();
  40
  41   /**
  42    * @return True if a filter indicates that this scanner will return no further rows.
  43    * @throws IOException in case of I/O failure on a filter.
  44    */
  45   boolean isFilterDone() throws IOException;
  46
  47   /**
  48    * Do a reseek to the required row. Should not be used to seek to a key which
  49    * may come before the current position. Always seeks to the beginning of a
  50    * row boundary.
  51    *
  52    * @throws IOException
  53    * @throws IllegalArgumentException
  54    *           if row is null
  55    *
  56    */
  57   boolean reseek(byte[] row) throws IOException;
  58
  59   /**
  60    * @return The preferred max buffersize. See
  61    * {@link org.apache.hadoop.hbase.client.Scan#setMaxResultSize(long)}
  62    */
  63   long getMaxResultSize();
  64
  65   /**
  66    * @return The Scanner's MVCC readPt see {@link MultiVersionConcurrencyControl}
  67    */
  68   long getMvccReadPoint();
  69
  70   /**
  71    * @return The limit on the number of cells to retrieve on each call to next(). See
  72    *         {@link org.apache.hadoop.hbase.client.Scan#setBatch(int)}
  73    */
  74   int getBatch();
  75
  76   /**
  77    * @return The Scanner's {@link org.apache.hadoop.hbase.client.Scan#ID_ATRIBUTE} value,
  78    *         or null if not set.
  79    */
  80   default String getOperationId() {
  81     return null;
  82   }
  83
  84   /**
  85    * Grab the next row's worth of values. This is a special internal method to be called from
  86    * coprocessor hooks to avoid expensive setup. Caller must set the thread's readpoint, start and
  87    * close a region operation, an synchronize on the scanner object. Caller should maintain and
  88    * update metrics. See {@link #nextRaw(List, ScannerContext)}
  89    * @param result return output array
  90    * @return true if more rows exist after this one, false if scanner is done
  91    * @throws IOException e
  92    */
  93   boolean nextRaw(List<Cell> result) throws IOException;
  94
  95   /**
  96    * Grab the next row's worth of values. The {@link ScannerContext} is used to enforce and track
  97    * any limits associated with this call. Any progress that exists in the {@link ScannerContext}
  98    * prior to calling this method will be LOST if {@link ScannerContext#getKeepProgress()} is false.
  99    * Upon returning from this method, the {@link ScannerContext} will contain information about the
 100    * progress made towards the limits. This is a special internal method to be called from
 101    * coprocessor hooks to avoid expensive setup. Caller must set the thread's readpoint, start and
 102    * close a region operation, an synchronize on the scanner object. Example: <code>
 103    * HRegion region = ...;
 104    * RegionScanner scanner = ...
 105    * MultiVersionConcurrencyControl.setThreadReadPoint(scanner.getMvccReadPoint());
 106    * region.startRegionOperation();
 107    * try {
 108    *   synchronized(scanner) {
 109    *     ...
 110    *     boolean moreRows = scanner.nextRaw(values);
 111    *     ...
 112    *   }
 113    * } finally {
 114    *   region.closeRegionOperation();
 115    * }
 116    * </code>
 117    * @param result return output array
 118    * @param scannerContext The {@link ScannerContext} instance encapsulating all limits that should
 119    *          be tracked during calls to this method. The progress towards these limits can be
 120    *          tracked within this instance.
 121    * @return true if more rows exist after this one, false if scanner is done
 122    * @throws IOException e
 123    */
 124   boolean nextRaw(List<Cell> result, ScannerContext scannerContext)
 125       throws IOException;
 126 }