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.client; 019 020import java.io.Closeable; 021import java.io.IOException; 022import java.io.UncheckedIOException; 023import java.util.ArrayList; 024import java.util.Iterator; 025import java.util.List; 026import org.apache.hadoop.hbase.client.metrics.ScanMetrics; 027import org.apache.yetus.audience.InterfaceAudience; 028 029/** 030 * Interface for client-side scanning. Go to {@link Table} to obtain instances. 031 */ 032@InterfaceAudience.Public 033public interface ResultScanner extends Closeable, Iterable<Result> { 034 035 @Override 036 default Iterator<Result> iterator() { 037 return new Iterator<Result>() { 038 // The next RowResult, possibly pre-read 039 Result next = null; 040 041 // return true if there is another item pending, false if there isn't. 042 // this method is where the actual advancing takes place, but you need 043 // to call next() to consume it. hasNext() will only advance if there 044 // isn't a pending next(). 045 @Override 046 public boolean hasNext() { 047 if (next != null) { 048 return true; 049 } 050 try { 051 next = ResultScanner.this.next(); 052 return next != null; 053 } catch (IOException e) { 054 throw new UncheckedIOException(e); 055 } 056 } 057 058 // get the pending next item and advance the iterator. returns null if 059 // there is no next item. 060 @Override 061 public Result next() { 062 // since hasNext() does the real advancing, we call this to determine 063 // if there is a next before proceeding. 064 if (!hasNext()) { 065 return null; 066 } 067 068 // if we get to here, then hasNext() has given us an item to return. 069 // we want to return the item and then null out the next pointer, so 070 // we use a temporary variable. 071 Result temp = next; 072 next = null; 073 return temp; 074 } 075 }; 076 } 077 078 /** 079 * Grab the next row's worth of values. The scanner will return a Result. 080 * @return Result object if there is another row, null if the scanner is exhausted. 081 * @throws IOException e 082 */ 083 Result next() throws IOException; 084 085 /** 086 * Get nbRows rows. How many RPCs are made is determined by the {@link Scan#setCaching(int)} 087 * setting (or hbase.client.scanner.caching in hbase-site.xml). 088 * @param nbRows number of rows to return 089 * @return Between zero and nbRows rowResults. Scan is done if returned array is of zero-length 090 * (We never return null). 091 */ 092 default Result[] next(int nbRows) throws IOException { 093 List<Result> resultSets = new ArrayList<>(nbRows); 094 for (int i = 0; i < nbRows; i++) { 095 Result next = next(); 096 if (next != null) { 097 resultSets.add(next); 098 } else { 099 break; 100 } 101 } 102 return resultSets.toArray(new Result[0]); 103 } 104 105 /** 106 * Closes the scanner and releases any resources it has allocated 107 */ 108 @Override 109 void close(); 110 111 /** 112 * Allow the client to renew the scanner's lease on the server. 113 * @return true if the lease was successfully renewed, false otherwise. 114 */ 115 boolean renewLease(); 116 117 /** Returns the scan metrics, or {@code null} if we do not enable metrics. */ 118 ScanMetrics getScanMetrics(); 119}