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.HRegionInfo;
27 import org.apache.hadoop.hbase.classification.InterfaceAudience;
28 import org.apache.hadoop.hbase.classification.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 HRegionInfo 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 * Grab the next row's worth of values. This is a special internal method to be called from
78 * coprocessor hooks to avoid expensive setup. Caller must set the thread's readpoint, start and
79 * close a region operation, an synchronize on the scanner object. Caller should maintain and
80 * update metrics. See {@link #nextRaw(List, ScannerContext)}
81 * @param result return output array
82 * @return true if more rows exist after this one, false if scanner is done
83 * @throws IOException e
84 */
85 boolean nextRaw(List<Cell> result) throws IOException;
86
87 /**
88 * Grab the next row's worth of values. The {@link ScannerContext} is used to enforce and track
89 * any limits associated with this call. Any progress that exists in the {@link ScannerContext}
90 * prior to calling this method will be LOST if {@link ScannerContext#getKeepProgress()} is false.
91 * Upon returning from this method, the {@link ScannerContext} will contain information about the
92 * progress made towards the limits. This is a special internal method to be called from
93 * coprocessor hooks to avoid expensive setup. Caller must set the thread's readpoint, start and
94 * close a region operation, an synchronize on the scanner object. Example: <code>
95 * HRegion region = ...;
96 * RegionScanner scanner = ...
97 * MultiVersionConcurrencyControl.setThreadReadPoint(scanner.getMvccReadPoint());
98 * region.startRegionOperation();
99 * try {
100 * synchronized(scanner) {
101 * ...
102 * boolean moreRows = scanner.nextRaw(values);
103 * ...
104 * }
105 * } finally {
106 * region.closeRegionOperation();
107 * }
108 * </code>
109 * @param result return output array
110 * @param scannerContext The {@link ScannerContext} instance encapsulating all limits that should
111 * be tracked during calls to this method. The progress towards these limits can be
112 * tracked within this instance.
113 * @return true if more rows exist after this one, false if scanner is done
114 * @throws IOException e
115 */
116 boolean nextRaw(List<Cell> result, ScannerContext scannerContext)
117 throws IOException;
118 }