hbase-client/src/main/java/org/apache/hadoop/hbase/client/ResultScanner.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.client;
  20
  21 import java.io.Closeable;
  22 import java.io.IOException;
  23 import java.io.UncheckedIOException;
  24 import java.util.ArrayList;
  25 import java.util.Iterator;
  26 import java.util.List;
  27
  28 import org.apache.hadoop.hbase.classification.InterfaceAudience;
  29 import org.apache.hadoop.hbase.client.metrics.ScanMetrics;
  30
  31 /**
  32  * Interface for client-side scanning. Go to {@link Table} to obtain instances.
  33  */
  34 @InterfaceAudience.Public
  35 public interface ResultScanner extends Closeable, Iterable<Result> {
  36
  37   @Override
  38   default Iterator<Result> iterator() {
  39     return new Iterator<Result>() {
  40       // The next RowResult, possibly pre-read
  41       Result next = null;
  42
  43       // return true if there is another item pending, false if there isn't.
  44       // this method is where the actual advancing takes place, but you need
  45       // to call next() to consume it. hasNext() will only advance if there
  46       // isn't a pending next().
  47       @Override
  48       public boolean hasNext() {
  49         if (next != null) {
  50           return true;
  51         }
  52         try {
  53           return (next = ResultScanner.this.next()) != null;
  54         } catch (IOException e) {
  55           throw new UncheckedIOException(e);
  56         }
  57       }
  58
  59       // get the pending next item and advance the iterator. returns null if
  60       // there is no next item.
  61       @Override
  62       public Result next() {
  63         // since hasNext() does the real advancing, we call this to determine
  64         // if there is a next before proceeding.
  65         if (!hasNext()) {
  66           return null;
  67         }
  68
  69         // if we get to here, then hasNext() has given us an item to return.
  70         // we want to return the item and then null out the next pointer, so
  71         // we use a temporary variable.
  72         Result temp = next;
  73         next = null;
  74         return temp;
  75       }
  76     };
  77   }
  78
  79   /**
  80    * Grab the next row's worth of values. The scanner will return a Result.
  81    * @return Result object if there is another row, null if the scanner is exhausted.
  82    * @throws IOException e
  83    */
  84   Result next() throws IOException;
  85
  86   /**
  87    * Get nbRows rows. How many RPCs are made is determined by the {@link Scan#setCaching(int)}
  88    * setting (or hbase.client.scanner.caching in hbase-site.xml).
  89    * @param nbRows number of rows to return
  90    * @return Between zero and nbRows rowResults. Scan is done if returned array is of zero-length
  91    *         (We never return null).
  92    * @throws IOException
  93    */
  94   default Result[] next(int nbRows) throws IOException {
  95     List<Result> resultSets = new ArrayList<>(nbRows);
  96     for (int i = 0; i < nbRows; i++) {
  97       Result next = next();
  98       if (next != null) {
  99         resultSets.add(next);
 100       } else {
 101         break;
 102       }
 103     }
 104     return resultSets.toArray(new Result[0]);
 105   }
 106
 107   /**
 108    * Closes the scanner and releases any resources it has allocated
 109    */
 110   @Override
 111   void close();
 112
 113   /**
 114    * Allow the client to renew the scanner's lease on the server.
 115    * @return true if the lease was successfully renewed, false otherwise.
 116    */
 117   boolean renewLease();
 118
 119   /**
 120    * @return the scan metrics, or {@code null} if we do not enable metrics.
 121    */
 122   ScanMetrics getScanMetrics();
 123 }