001/*
002 *
003 * Licensed to the Apache Software Foundation (ASF) under one
004 * or more contributor license agreements.  See the NOTICE file
005 * distributed with this work for additional information
006 * regarding copyright ownership.  The ASF licenses this file
007 * to you under the Apache License, Version 2.0 (the
008 * "License"); you may not use this file except in compliance
009 * with the License.  You may obtain a copy of the License at
010 *
011 *     http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing, software
014 * distributed under the License is distributed on an "AS IS" BASIS,
015 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016 * See the License for the specific language governing permissions and
017 * limitations under the License.
018 */
019
020package org.apache.hadoop.hbase.client;
021
022import java.io.IOException;
023import java.util.ArrayList;
024import java.util.Arrays;
025import java.util.HashMap;
026import java.util.List;
027import java.util.Map;
028import java.util.NavigableSet;
029import java.util.TreeMap;
030import java.util.TreeSet;
031import org.apache.hadoop.hbase.HConstants;
032import org.apache.hadoop.hbase.client.metrics.ScanMetrics;
033import org.apache.hadoop.hbase.filter.Filter;
034import org.apache.hadoop.hbase.filter.IncompatibleFilterException;
035import org.apache.hadoop.hbase.io.TimeRange;
036import org.apache.hadoop.hbase.security.access.Permission;
037import org.apache.hadoop.hbase.security.visibility.Authorizations;
038import org.apache.hadoop.hbase.util.Bytes;
039import org.apache.yetus.audience.InterfaceAudience;
040import org.slf4j.Logger;
041import org.slf4j.LoggerFactory;
042
043/**
044 * Used to perform Scan operations.
045 * <p>
046 * All operations are identical to {@link Get} with the exception of instantiation. Rather than
047 * specifying a single row, an optional startRow and stopRow may be defined. If rows are not
048 * specified, the Scanner will iterate over all rows.
049 * <p>
050 * To get all columns from all rows of a Table, create an instance with no constraints; use the
051 * {@link #Scan()} constructor. To constrain the scan to specific column families, call
052 * {@link #addFamily(byte[]) addFamily} for each family to retrieve on your Scan instance.
053 * <p>
054 * To get specific columns, call {@link #addColumn(byte[], byte[]) addColumn} for each column to
055 * retrieve.
056 * <p>
057 * To only retrieve columns within a specific range of version timestamps, call
058 * {@link #setTimeRange(long, long) setTimeRange}.
059 * <p>
060 * To only retrieve columns with a specific timestamp, call {@link #setTimestamp(long) setTimestamp}
061 * .
062 * <p>
063 * To limit the number of versions of each column to be returned, call {@link #setMaxVersions(int)
064 * setMaxVersions}.
065 * <p>
066 * To limit the maximum number of values returned for each call to next(), call
067 * {@link #setBatch(int) setBatch}.
068 * <p>
069 * To add a filter, call {@link #setFilter(org.apache.hadoop.hbase.filter.Filter) setFilter}.
070 * <p>
071 * For small scan, it is deprecated in 2.0.0. Now we have a {@link #setLimit(int)} method in Scan
072 * object which is used to tell RS how many rows we want. If the rows return reaches the limit, the
073 * RS will close the RegionScanner automatically. And we will also fetch data when openScanner in
074 * the new implementation, this means we can also finish a scan operation in one rpc call. And we
075 * have also introduced a {@link #setReadType(ReadType)} method. You can use this method to tell RS
076 * to use pread explicitly.
077 * <p>
078 * Expert: To explicitly disable server-side block caching for this scan, execute
079 * {@link #setCacheBlocks(boolean)}.
080 * <p>
081 * <em>Note:</em> Usage alters Scan instances. Internally, attributes are updated as the Scan runs
082 * and if enabled, metrics accumulate in the Scan instance. Be aware this is the case when you go to
083 * clone a Scan instance or if you go to reuse a created Scan instance; safer is create a Scan
084 * instance per usage.
085 */
086@InterfaceAudience.Public
087public class Scan extends Query {
088  private static final Logger LOG = LoggerFactory.getLogger(Scan.class);
089
090  private static final String RAW_ATTR = "_raw_";
091
092  private byte[] startRow = HConstants.EMPTY_START_ROW;
093  private boolean includeStartRow = true;
094  private byte[] stopRow  = HConstants.EMPTY_END_ROW;
095  private boolean includeStopRow = false;
096  private int maxVersions = 1;
097  private int batch = -1;
098
099  /**
100   * Partial {@link Result}s are {@link Result}s must be combined to form a complete {@link Result}.
101   * The {@link Result}s had to be returned in fragments (i.e. as partials) because the size of the
102   * cells in the row exceeded max result size on the server. Typically partial results will be
103   * combined client side into complete results before being delivered to the caller. However, if
104   * this flag is set, the caller is indicating that they do not mind seeing partial results (i.e.
105   * they understand that the results returned from the Scanner may only represent part of a
106   * particular row). In such a case, any attempt to combine the partials into a complete result on
107   * the client side will be skipped, and the caller will be able to see the exact results returned
108   * from the server.
109   */
110  private boolean allowPartialResults = false;
111
112  private int storeLimit = -1;
113  private int storeOffset = 0;
114
115  private static final String SCAN_ATTRIBUTES_METRICS_ENABLE = "scan.attributes.metrics.enable";
116
117  // If an application wants to use multiple scans over different tables each scan must
118  // define this attribute with the appropriate table name by calling
119  // scan.setAttribute(Scan.SCAN_ATTRIBUTES_TABLE_NAME, Bytes.toBytes(tableName))
120  static public final String SCAN_ATTRIBUTES_TABLE_NAME = "scan.attributes.table.name";
121
122  /**
123   * -1 means no caching specified and the value of {@link HConstants#HBASE_CLIENT_SCANNER_CACHING}
124   * (default to {@link HConstants#DEFAULT_HBASE_CLIENT_SCANNER_CACHING}) will be used
125   */
126  private int caching = -1;
127  private long maxResultSize = -1;
128  private boolean cacheBlocks = true;
129  private boolean reversed = false;
130  private TimeRange tr = TimeRange.allTime();
131  private Map<byte [], NavigableSet<byte []>> familyMap =
132    new TreeMap<byte [], NavigableSet<byte []>>(Bytes.BYTES_COMPARATOR);
133  private Boolean asyncPrefetch = null;
134
135  /**
136   * Parameter name for client scanner sync/async prefetch toggle.
137   * When using async scanner, prefetching data from the server is done at the background.
138   * The parameter currently won't have any effect in the case that the user has set
139   * Scan#setSmall or Scan#setReversed
140   */
141  public static final String HBASE_CLIENT_SCANNER_ASYNC_PREFETCH =
142      "hbase.client.scanner.async.prefetch";
143
144  /**
145   * Default value of {@link #HBASE_CLIENT_SCANNER_ASYNC_PREFETCH}.
146   */
147  public static final boolean DEFAULT_HBASE_CLIENT_SCANNER_ASYNC_PREFETCH = false;
148
149  /**
150   * Set it true for small scan to get better performance Small scan should use pread and big scan
151   * can use seek + read seek + read is fast but can cause two problem (1) resource contention (2)
152   * cause too much network io [89-fb] Using pread for non-compaction read request
153   * https://issues.apache.org/jira/browse/HBASE-7266 On the other hand, if setting it true, we
154   * would do openScanner,next,closeScanner in one RPC call. It means the better performance for
155   * small scan. [HBASE-9488]. Generally, if the scan range is within one data block(64KB), it could
156   * be considered as a small scan.
157   */
158  private boolean small = false;
159
160  /**
161   * The mvcc read point to use when open a scanner. Remember to clear it after switching regions as
162   * the mvcc is only valid within region scope.
163   */
164  private long mvccReadPoint = -1L;
165
166  /**
167   * The number of rows we want for this scan. We will terminate the scan if the number of return
168   * rows reaches this value.
169   */
170  private int limit = -1;
171
172  /**
173   * Control whether to use pread at server side.
174   */
175  private ReadType readType = ReadType.DEFAULT;
176
177  private boolean needCursorResult = false;
178
179  /**
180   * Create a Scan operation across all rows.
181   */
182  public Scan() {}
183
184  /**
185   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use
186   *   {@code new Scan().withStartRow(startRow).setFilter(filter)} instead.
187   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17320">HBASE-17320</a>
188   */
189  @Deprecated
190  public Scan(byte[] startRow, Filter filter) {
191    this(startRow);
192    this.filter = filter;
193  }
194
195  /**
196   * Create a Scan operation starting at the specified row.
197   * <p>
198   * If the specified row does not exist, the Scanner will start from the next closest row after the
199   * specified row.
200   * @param startRow row to start scanner at or after
201   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use
202   *   {@code new Scan().withStartRow(startRow)} instead.
203   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17320">HBASE-17320</a>
204   */
205  @Deprecated
206  public Scan(byte[] startRow) {
207    setStartRow(startRow);
208  }
209
210  /**
211   * Create a Scan operation for the range of rows specified.
212   * @param startRow row to start scanner at or after (inclusive)
213   * @param stopRow row to stop scanner before (exclusive)
214   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use
215   *   {@code new Scan().withStartRow(startRow).withStopRow(stopRow)} instead.
216   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17320">HBASE-17320</a>
217   */
218  @Deprecated
219  public Scan(byte[] startRow, byte[] stopRow) {
220    setStartRow(startRow);
221    setStopRow(stopRow);
222  }
223
224  /**
225   * Creates a new instance of this class while copying all values.
226   *
227   * @param scan  The scan instance to copy from.
228   * @throws IOException When copying the values fails.
229   */
230  public Scan(Scan scan) throws IOException {
231    startRow = scan.getStartRow();
232    includeStartRow = scan.includeStartRow();
233    stopRow  = scan.getStopRow();
234    includeStopRow = scan.includeStopRow();
235    maxVersions = scan.getMaxVersions();
236    batch = scan.getBatch();
237    storeLimit = scan.getMaxResultsPerColumnFamily();
238    storeOffset = scan.getRowOffsetPerColumnFamily();
239    caching = scan.getCaching();
240    maxResultSize = scan.getMaxResultSize();
241    cacheBlocks = scan.getCacheBlocks();
242    filter = scan.getFilter(); // clone?
243    loadColumnFamiliesOnDemand = scan.getLoadColumnFamiliesOnDemandValue();
244    consistency = scan.getConsistency();
245    this.setIsolationLevel(scan.getIsolationLevel());
246    reversed = scan.isReversed();
247    asyncPrefetch = scan.isAsyncPrefetch();
248    small = scan.isSmall();
249    allowPartialResults = scan.getAllowPartialResults();
250    tr = scan.getTimeRange(); // TimeRange is immutable
251    Map<byte[], NavigableSet<byte[]>> fams = scan.getFamilyMap();
252    for (Map.Entry<byte[],NavigableSet<byte[]>> entry : fams.entrySet()) {
253      byte [] fam = entry.getKey();
254      NavigableSet<byte[]> cols = entry.getValue();
255      if (cols != null && cols.size() > 0) {
256        for (byte[] col : cols) {
257          addColumn(fam, col);
258        }
259      } else {
260        addFamily(fam);
261      }
262    }
263    for (Map.Entry<String, byte[]> attr : scan.getAttributesMap().entrySet()) {
264      setAttribute(attr.getKey(), attr.getValue());
265    }
266    for (Map.Entry<byte[], TimeRange> entry : scan.getColumnFamilyTimeRange().entrySet()) {
267      TimeRange tr = entry.getValue();
268      setColumnFamilyTimeRange(entry.getKey(), tr.getMin(), tr.getMax());
269    }
270    this.mvccReadPoint = scan.getMvccReadPoint();
271    this.limit = scan.getLimit();
272    this.needCursorResult = scan.isNeedCursorResult();
273    setPriority(scan.getPriority());
274    readType = scan.getReadType();
275    super.setReplicaId(scan.getReplicaId());
276  }
277
278  /**
279   * Builds a scan object with the same specs as get.
280   * @param get get to model scan after
281   */
282  public Scan(Get get) {
283    this.startRow = get.getRow();
284    this.includeStartRow = true;
285    this.stopRow = get.getRow();
286    this.includeStopRow = true;
287    this.filter = get.getFilter();
288    this.cacheBlocks = get.getCacheBlocks();
289    this.maxVersions = get.getMaxVersions();
290    this.storeLimit = get.getMaxResultsPerColumnFamily();
291    this.storeOffset = get.getRowOffsetPerColumnFamily();
292    this.tr = get.getTimeRange();
293    this.familyMap = get.getFamilyMap();
294    this.asyncPrefetch = false;
295    this.consistency = get.getConsistency();
296    this.setIsolationLevel(get.getIsolationLevel());
297    this.loadColumnFamiliesOnDemand = get.getLoadColumnFamiliesOnDemandValue();
298    for (Map.Entry<String, byte[]> attr : get.getAttributesMap().entrySet()) {
299      setAttribute(attr.getKey(), attr.getValue());
300    }
301    for (Map.Entry<byte[], TimeRange> entry : get.getColumnFamilyTimeRange().entrySet()) {
302      TimeRange tr = entry.getValue();
303      setColumnFamilyTimeRange(entry.getKey(), tr.getMin(), tr.getMax());
304    }
305    this.mvccReadPoint = -1L;
306    setPriority(get.getPriority());
307    super.setReplicaId(get.getReplicaId());
308  }
309
310  public boolean isGetScan() {
311    return includeStartRow && includeStopRow
312        && ClientUtil.areScanStartRowAndStopRowEqual(this.startRow, this.stopRow);
313  }
314
315  /**
316   * Get all columns from the specified family.
317   * <p>
318   * Overrides previous calls to addColumn for this family.
319   * @param family family name
320   * @return this
321   */
322  public Scan addFamily(byte [] family) {
323    familyMap.remove(family);
324    familyMap.put(family, null);
325    return this;
326  }
327
328  /**
329   * Get the column from the specified family with the specified qualifier.
330   * <p>
331   * Overrides previous calls to addFamily for this family.
332   * @param family family name
333   * @param qualifier column qualifier
334   * @return this
335   */
336  public Scan addColumn(byte [] family, byte [] qualifier) {
337    NavigableSet<byte []> set = familyMap.get(family);
338    if(set == null) {
339      set = new TreeSet<>(Bytes.BYTES_COMPARATOR);
340      familyMap.put(family, set);
341    }
342    if (qualifier == null) {
343      qualifier = HConstants.EMPTY_BYTE_ARRAY;
344    }
345    set.add(qualifier);
346    return this;
347  }
348
349  /**
350   * Get versions of columns only within the specified timestamp range,
351   * [minStamp, maxStamp).  Note, default maximum versions to return is 1.  If
352   * your time range spans more than one version and you want all versions
353   * returned, up the number of versions beyond the default.
354   * @param minStamp minimum timestamp value, inclusive
355   * @param maxStamp maximum timestamp value, exclusive
356   * @see #setMaxVersions()
357   * @see #setMaxVersions(int)
358   * @return this
359   */
360  public Scan setTimeRange(long minStamp, long maxStamp) throws IOException {
361    tr = new TimeRange(minStamp, maxStamp);
362    return this;
363  }
364
365  /**
366   * Get versions of columns with the specified timestamp. Note, default maximum
367   * versions to return is 1.  If your time range spans more than one version
368   * and you want all versions returned, up the number of versions beyond the
369   * defaut.
370   * @param timestamp version timestamp
371   * @see #setMaxVersions()
372   * @see #setMaxVersions(int)
373   * @return this
374   * @deprecated As of release 2.0.0, this will be removed in HBase 3.0.0.
375   *             Use {@link #setTimestamp(long)} instead
376   */
377  @Deprecated
378  public Scan setTimeStamp(long timestamp)
379  throws IOException {
380    return this.setTimestamp(timestamp);
381  }
382
383  /**
384   * Get versions of columns with the specified timestamp. Note, default maximum
385   * versions to return is 1.  If your time range spans more than one version
386   * and you want all versions returned, up the number of versions beyond the
387   * defaut.
388   * @param timestamp version timestamp
389   * @see #setMaxVersions()
390   * @see #setMaxVersions(int)
391   * @return this
392   */
393  public Scan setTimestamp(long timestamp) {
394    try {
395      tr = new TimeRange(timestamp, timestamp + 1);
396    } catch(Exception e) {
397      // This should never happen, unless integer overflow or something extremely wrong...
398      LOG.error("TimeRange failed, likely caused by integer overflow. ", e);
399      throw e;
400    }
401
402    return this;
403  }
404
405  @Override public Scan setColumnFamilyTimeRange(byte[] cf, long minStamp, long maxStamp) {
406    return (Scan) super.setColumnFamilyTimeRange(cf, minStamp, maxStamp);
407  }
408
409  /**
410   * Set the start row of the scan.
411   * <p>
412   * If the specified row does not exist, the Scanner will start from the next closest row after the
413   * specified row.
414   * @param startRow row to start scanner at or after
415   * @return this
416   * @throws IllegalArgumentException if startRow does not meet criteria for a row key (when length
417   *           exceeds {@link HConstants#MAX_ROW_LENGTH})
418   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use {@link #withStartRow(byte[])}
419   *   instead. This method may change the inclusive of the stop row to keep compatible with the old
420   *   behavior.
421   * @see #withStartRow(byte[])
422   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17320">HBASE-17320</a>
423   */
424  @Deprecated
425  public Scan setStartRow(byte[] startRow) {
426    withStartRow(startRow);
427    if (ClientUtil.areScanStartRowAndStopRowEqual(this.startRow, this.stopRow)) {
428      // for keeping the old behavior that a scan with the same start and stop row is a get scan.
429      this.includeStopRow = true;
430    }
431    return this;
432  }
433
434  /**
435   * Set the start row of the scan.
436   * <p>
437   * If the specified row does not exist, the Scanner will start from the next closest row after the
438   * specified row.
439   * @param startRow row to start scanner at or after
440   * @return this
441   * @throws IllegalArgumentException if startRow does not meet criteria for a row key (when length
442   *           exceeds {@link HConstants#MAX_ROW_LENGTH})
443   */
444  public Scan withStartRow(byte[] startRow) {
445    return withStartRow(startRow, true);
446  }
447
448  /**
449   * Set the start row of the scan.
450   * <p>
451   * If the specified row does not exist, or the {@code inclusive} is {@code false}, the Scanner
452   * will start from the next closest row after the specified row.
453   * @param startRow row to start scanner at or after
454   * @param inclusive whether we should include the start row when scan
455   * @return this
456   * @throws IllegalArgumentException if startRow does not meet criteria for a row key (when length
457   *           exceeds {@link HConstants#MAX_ROW_LENGTH})
458   */
459  public Scan withStartRow(byte[] startRow, boolean inclusive) {
460    if (Bytes.len(startRow) > HConstants.MAX_ROW_LENGTH) {
461      throw new IllegalArgumentException("startRow's length must be less than or equal to "
462          + HConstants.MAX_ROW_LENGTH + " to meet the criteria" + " for a row key.");
463    }
464    this.startRow = startRow;
465    this.includeStartRow = inclusive;
466    return this;
467  }
468
469  /**
470   * Set the stop row of the scan.
471   * <p>
472   * The scan will include rows that are lexicographically less than the provided stopRow.
473   * <p>
474   * <b>Note:</b> When doing a filter for a rowKey <u>Prefix</u> use
475   * {@link #setRowPrefixFilter(byte[])}. The 'trailing 0' will not yield the desired result.
476   * </p>
477   * @param stopRow row to end at (exclusive)
478   * @return this
479   * @throws IllegalArgumentException if stopRow does not meet criteria for a row key (when length
480   *           exceeds {@link HConstants#MAX_ROW_LENGTH})
481   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use {@link #withStopRow(byte[])} instead.
482   *   This method may change the inclusive of the stop row to keep compatible with the old
483   *   behavior.
484   * @see #withStopRow(byte[])
485   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17320">HBASE-17320</a>
486   */
487  @Deprecated
488  public Scan setStopRow(byte[] stopRow) {
489    withStopRow(stopRow);
490    if (ClientUtil.areScanStartRowAndStopRowEqual(this.startRow, this.stopRow)) {
491      // for keeping the old behavior that a scan with the same start and stop row is a get scan.
492      this.includeStopRow = true;
493    }
494    return this;
495  }
496
497  /**
498   * Set the stop row of the scan.
499   * <p>
500   * The scan will include rows that are lexicographically less than the provided stopRow.
501   * <p>
502   * <b>Note:</b> When doing a filter for a rowKey <u>Prefix</u> use
503   * {@link #setRowPrefixFilter(byte[])}. The 'trailing 0' will not yield the desired result.
504   * </p>
505   * @param stopRow row to end at (exclusive)
506   * @return this
507   * @throws IllegalArgumentException if stopRow does not meet criteria for a row key (when length
508   *           exceeds {@link HConstants#MAX_ROW_LENGTH})
509   */
510  public Scan withStopRow(byte[] stopRow) {
511    return withStopRow(stopRow, false);
512  }
513
514  /**
515   * Set the stop row of the scan.
516   * <p>
517   * The scan will include rows that are lexicographically less than (or equal to if
518   * {@code inclusive} is {@code true}) the provided stopRow.
519   * @param stopRow row to end at
520   * @param inclusive whether we should include the stop row when scan
521   * @return this
522   * @throws IllegalArgumentException if stopRow does not meet criteria for a row key (when length
523   *           exceeds {@link HConstants#MAX_ROW_LENGTH})
524   */
525  public Scan withStopRow(byte[] stopRow, boolean inclusive) {
526    if (Bytes.len(stopRow) > HConstants.MAX_ROW_LENGTH) {
527      throw new IllegalArgumentException("stopRow's length must be less than or equal to "
528          + HConstants.MAX_ROW_LENGTH + " to meet the criteria" + " for a row key.");
529    }
530    this.stopRow = stopRow;
531    this.includeStopRow = inclusive;
532    return this;
533  }
534
535  /**
536   * <p>Set a filter (using stopRow and startRow) so the result set only contains rows where the
537   * rowKey starts with the specified prefix.</p>
538   * <p>This is a utility method that converts the desired rowPrefix into the appropriate values
539   * for the startRow and stopRow to achieve the desired result.</p>
540   * <p>This can safely be used in combination with setFilter.</p>
541   * <p><b>NOTE: Doing a {@link #setStartRow(byte[])} and/or {@link #setStopRow(byte[])}
542   * after this method will yield undefined results.</b></p>
543   * @param rowPrefix the prefix all rows must start with. (Set <i>null</i> to remove the filter.)
544   * @return this
545   */
546  public Scan setRowPrefixFilter(byte[] rowPrefix) {
547    if (rowPrefix == null) {
548      setStartRow(HConstants.EMPTY_START_ROW);
549      setStopRow(HConstants.EMPTY_END_ROW);
550    } else {
551      this.setStartRow(rowPrefix);
552      this.setStopRow(calculateTheClosestNextRowKeyForPrefix(rowPrefix));
553    }
554    return this;
555  }
556
557  /**
558   * <p>When scanning for a prefix the scan should stop immediately after the the last row that
559   * has the specified prefix. This method calculates the closest next rowKey immediately following
560   * the given rowKeyPrefix.</p>
561   * <p><b>IMPORTANT: This converts a rowKey<u>Prefix</u> into a rowKey</b>.</p>
562   * <p>If the prefix is an 'ASCII' string put into a byte[] then this is easy because you can
563   * simply increment the last byte of the array.
564   * But if your application uses real binary rowids you may run into the scenario that your
565   * prefix is something like:</p>
566   * &nbsp;&nbsp;&nbsp;<b>{ 0x12, 0x23, 0xFF, 0xFF }</b><br/>
567   * Then this stopRow needs to be fed into the actual scan<br/>
568   * &nbsp;&nbsp;&nbsp;<b>{ 0x12, 0x24 }</b> (Notice that it is shorter now)<br/>
569   * This method calculates the correct stop row value for this usecase.
570   *
571   * @param rowKeyPrefix the rowKey<u>Prefix</u>.
572   * @return the closest next rowKey immediately following the given rowKeyPrefix.
573   */
574  private byte[] calculateTheClosestNextRowKeyForPrefix(byte[] rowKeyPrefix) {
575    // Essentially we are treating it like an 'unsigned very very long' and doing +1 manually.
576    // Search for the place where the trailing 0xFFs start
577    int offset = rowKeyPrefix.length;
578    while (offset > 0) {
579      if (rowKeyPrefix[offset - 1] != (byte) 0xFF) {
580        break;
581      }
582      offset--;
583    }
584
585    if (offset == 0) {
586      // We got an 0xFFFF... (only FFs) stopRow value which is
587      // the last possible prefix before the end of the table.
588      // So set it to stop at the 'end of the table'
589      return HConstants.EMPTY_END_ROW;
590    }
591
592    // Copy the right length of the original
593    byte[] newStopRow = Arrays.copyOfRange(rowKeyPrefix, 0, offset);
594    // And increment the last one
595    newStopRow[newStopRow.length - 1]++;
596    return newStopRow;
597  }
598
599  /**
600   * Get all available versions.
601   * @return this
602   * @deprecated since 2.0.0 and will be removed in 3.0.0. It is easy to misunderstand with column
603   *   family's max versions, so use {@link #readAllVersions()} instead.
604   * @see #readAllVersions()
605   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17125">HBASE-17125</a>
606   */
607  @Deprecated
608  public Scan setMaxVersions() {
609    return readAllVersions();
610  }
611
612  /**
613   * Get up to the specified number of versions of each column.
614   * @param maxVersions maximum versions for each column
615   * @return this
616   * @deprecated since 2.0.0 and will be removed in 3.0.0. It is easy to misunderstand with column
617   *   family's max versions, so use {@link #readVersions(int)} instead.
618   * @see #readVersions(int)
619   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17125">HBASE-17125</a>
620   */
621  @Deprecated
622  public Scan setMaxVersions(int maxVersions) {
623    return readVersions(maxVersions);
624  }
625
626  /**
627   * Get all available versions.
628   * @return this
629   */
630  public Scan readAllVersions() {
631    this.maxVersions = Integer.MAX_VALUE;
632    return this;
633  }
634
635  /**
636   * Get up to the specified number of versions of each column.
637   * @param versions specified number of versions for each column
638   * @return this
639   */
640  public Scan readVersions(int versions) {
641    this.maxVersions = versions;
642    return this;
643  }
644
645  /**
646   * Set the maximum number of cells to return for each call to next(). Callers should be aware
647   * that this is not equivalent to calling {@link #setAllowPartialResults(boolean)}.
648   * If you don't allow partial results, the number of cells in each Result must equal to your
649   * batch setting unless it is the last Result for current row. So this method is helpful in paging
650   * queries. If you just want to prevent OOM at client, use setAllowPartialResults(true) is better.
651   * @param batch the maximum number of values
652   * @see Result#mayHaveMoreCellsInRow()
653   */
654  public Scan setBatch(int batch) {
655    if (this.hasFilter() && this.filter.hasFilterRow()) {
656      throw new IncompatibleFilterException(
657        "Cannot set batch on a scan using a filter" +
658        " that returns true for filter.hasFilterRow");
659    }
660    this.batch = batch;
661    return this;
662  }
663
664  /**
665   * Set the maximum number of values to return per row per Column Family
666   * @param limit the maximum number of values returned / row / CF
667   */
668  public Scan setMaxResultsPerColumnFamily(int limit) {
669    this.storeLimit = limit;
670    return this;
671  }
672
673  /**
674   * Set offset for the row per Column Family.
675   * @param offset is the number of kvs that will be skipped.
676   */
677  public Scan setRowOffsetPerColumnFamily(int offset) {
678    this.storeOffset = offset;
679    return this;
680  }
681
682  /**
683   * Set the number of rows for caching that will be passed to scanners.
684   * If not set, the Configuration setting {@link HConstants#HBASE_CLIENT_SCANNER_CACHING} will
685   * apply.
686   * Higher caching values will enable faster scanners but will use more memory.
687   * @param caching the number of rows for caching
688   */
689  public Scan setCaching(int caching) {
690    this.caching = caching;
691    return this;
692  }
693
694  /**
695   * @return the maximum result size in bytes. See {@link #setMaxResultSize(long)}
696   */
697  public long getMaxResultSize() {
698    return maxResultSize;
699  }
700
701  /**
702   * Set the maximum result size. The default is -1; this means that no specific
703   * maximum result size will be set for this scan, and the global configured
704   * value will be used instead. (Defaults to unlimited).
705   *
706   * @param maxResultSize The maximum result size in bytes.
707   */
708  public Scan setMaxResultSize(long maxResultSize) {
709    this.maxResultSize = maxResultSize;
710    return this;
711  }
712
713  @Override
714  public Scan setFilter(Filter filter) {
715    super.setFilter(filter);
716    return this;
717  }
718
719  /**
720   * Setting the familyMap
721   * @param familyMap map of family to qualifier
722   * @return this
723   */
724  public Scan setFamilyMap(Map<byte [], NavigableSet<byte []>> familyMap) {
725    this.familyMap = familyMap;
726    return this;
727  }
728
729  /**
730   * Getting the familyMap
731   * @return familyMap
732   */
733  public Map<byte [], NavigableSet<byte []>> getFamilyMap() {
734    return this.familyMap;
735  }
736
737  /**
738   * @return the number of families in familyMap
739   */
740  public int numFamilies() {
741    if(hasFamilies()) {
742      return this.familyMap.size();
743    }
744    return 0;
745  }
746
747  /**
748   * @return true if familyMap is non empty, false otherwise
749   */
750  public boolean hasFamilies() {
751    return !this.familyMap.isEmpty();
752  }
753
754  /**
755   * @return the keys of the familyMap
756   */
757  public byte[][] getFamilies() {
758    if(hasFamilies()) {
759      return this.familyMap.keySet().toArray(new byte[0][0]);
760    }
761    return null;
762  }
763
764  /**
765   * @return the startrow
766   */
767  public byte [] getStartRow() {
768    return this.startRow;
769  }
770
771  /**
772   * @return if we should include start row when scan
773   */
774  public boolean includeStartRow() {
775    return includeStartRow;
776  }
777
778  /**
779   * @return the stoprow
780   */
781  public byte[] getStopRow() {
782    return this.stopRow;
783  }
784
785  /**
786   * @return if we should include stop row when scan
787   */
788  public boolean includeStopRow() {
789    return includeStopRow;
790  }
791
792  /**
793   * @return the max number of versions to fetch
794   */
795  public int getMaxVersions() {
796    return this.maxVersions;
797  }
798
799  /**
800   * @return maximum number of values to return for a single call to next()
801   */
802  public int getBatch() {
803    return this.batch;
804  }
805
806  /**
807   * @return maximum number of values to return per row per CF
808   */
809  public int getMaxResultsPerColumnFamily() {
810    return this.storeLimit;
811  }
812
813  /**
814   * Method for retrieving the scan's offset per row per column
815   * family (#kvs to be skipped)
816   * @return row offset
817   */
818  public int getRowOffsetPerColumnFamily() {
819    return this.storeOffset;
820  }
821
822  /**
823   * @return caching the number of rows fetched when calling next on a scanner
824   */
825  public int getCaching() {
826    return this.caching;
827  }
828
829  /**
830   * @return TimeRange
831   */
832  public TimeRange getTimeRange() {
833    return this.tr;
834  }
835
836  /**
837   * @return RowFilter
838   */
839  @Override
840  public Filter getFilter() {
841    return filter;
842  }
843
844  /**
845   * @return true is a filter has been specified, false if not
846   */
847  public boolean hasFilter() {
848    return filter != null;
849  }
850
851  /**
852   * Set whether blocks should be cached for this Scan.
853   * <p>
854   * This is true by default.  When true, default settings of the table and
855   * family are used (this will never override caching blocks if the block
856   * cache is disabled for that family or entirely).
857   *
858   * @param cacheBlocks if false, default settings are overridden and blocks
859   * will not be cached
860   */
861  public Scan setCacheBlocks(boolean cacheBlocks) {
862    this.cacheBlocks = cacheBlocks;
863    return this;
864  }
865
866  /**
867   * Get whether blocks should be cached for this Scan.
868   * @return true if default caching should be used, false if blocks should not
869   * be cached
870   */
871  public boolean getCacheBlocks() {
872    return cacheBlocks;
873  }
874
875  /**
876   * Set whether this scan is a reversed one
877   * <p>
878   * This is false by default which means forward(normal) scan.
879   *
880   * @param reversed if true, scan will be backward order
881   * @return this
882   */
883  public Scan setReversed(boolean reversed) {
884    this.reversed = reversed;
885    return this;
886  }
887
888  /**
889   * Get whether this scan is a reversed one.
890   * @return true if backward scan, false if forward(default) scan
891   */
892  public boolean isReversed() {
893    return reversed;
894  }
895
896  /**
897   * Setting whether the caller wants to see the partial results when server returns
898   * less-than-expected cells. It is helpful while scanning a huge row to prevent OOM at client.
899   * By default this value is false and the complete results will be assembled client side
900   * before being delivered to the caller.
901   * @param allowPartialResults
902   * @return this
903   * @see Result#mayHaveMoreCellsInRow()
904   * @see #setBatch(int)
905   */
906  public Scan setAllowPartialResults(final boolean allowPartialResults) {
907    this.allowPartialResults = allowPartialResults;
908    return this;
909  }
910
911  /**
912   * @return true when the constructor of this scan understands that the results they will see may
913   *         only represent a partial portion of a row. The entire row would be retrieved by
914   *         subsequent calls to {@link ResultScanner#next()}
915   */
916  public boolean getAllowPartialResults() {
917    return allowPartialResults;
918  }
919
920  @Override
921  public Scan setLoadColumnFamiliesOnDemand(boolean value) {
922    return (Scan) super.setLoadColumnFamiliesOnDemand(value);
923  }
924
925  /**
926   * Compile the table and column family (i.e. schema) information
927   * into a String. Useful for parsing and aggregation by debugging,
928   * logging, and administration tools.
929   * @return Map
930   */
931  @Override
932  public Map<String, Object> getFingerprint() {
933    Map<String, Object> map = new HashMap<>();
934    List<String> families = new ArrayList<>();
935    if(this.familyMap.isEmpty()) {
936      map.put("families", "ALL");
937      return map;
938    } else {
939      map.put("families", families);
940    }
941    for (Map.Entry<byte [], NavigableSet<byte[]>> entry :
942        this.familyMap.entrySet()) {
943      families.add(Bytes.toStringBinary(entry.getKey()));
944    }
945    return map;
946  }
947
948  /**
949   * Compile the details beyond the scope of getFingerprint (row, columns,
950   * timestamps, etc.) into a Map along with the fingerprinted information.
951   * Useful for debugging, logging, and administration tools.
952   * @param maxCols a limit on the number of columns output prior to truncation
953   * @return Map
954   */
955  @Override
956  public Map<String, Object> toMap(int maxCols) {
957    // start with the fingerpring map and build on top of it
958    Map<String, Object> map = getFingerprint();
959    // map from families to column list replaces fingerprint's list of families
960    Map<String, List<String>> familyColumns = new HashMap<>();
961    map.put("families", familyColumns);
962    // add scalar information first
963    map.put("startRow", Bytes.toStringBinary(this.startRow));
964    map.put("stopRow", Bytes.toStringBinary(this.stopRow));
965    map.put("maxVersions", this.maxVersions);
966    map.put("batch", this.batch);
967    map.put("caching", this.caching);
968    map.put("maxResultSize", this.maxResultSize);
969    map.put("cacheBlocks", this.cacheBlocks);
970    map.put("loadColumnFamiliesOnDemand", this.loadColumnFamiliesOnDemand);
971    List<Long> timeRange = new ArrayList<>(2);
972    timeRange.add(this.tr.getMin());
973    timeRange.add(this.tr.getMax());
974    map.put("timeRange", timeRange);
975    int colCount = 0;
976    // iterate through affected families and list out up to maxCols columns
977    for (Map.Entry<byte [], NavigableSet<byte[]>> entry :
978      this.familyMap.entrySet()) {
979      List<String> columns = new ArrayList<>();
980      familyColumns.put(Bytes.toStringBinary(entry.getKey()), columns);
981      if(entry.getValue() == null) {
982        colCount++;
983        --maxCols;
984        columns.add("ALL");
985      } else {
986        colCount += entry.getValue().size();
987        if (maxCols <= 0) {
988          continue;
989        }
990        for (byte [] column : entry.getValue()) {
991          if (--maxCols <= 0) {
992            continue;
993          }
994          columns.add(Bytes.toStringBinary(column));
995        }
996      }
997    }
998    map.put("totalColumns", colCount);
999    if (this.filter != null) {
1000      map.put("filter", this.filter.toString());
1001    }
1002    // add the id if set
1003    if (getId() != null) {
1004      map.put("id", getId());
1005    }
1006    return map;
1007  }
1008
1009  /**
1010   * Enable/disable "raw" mode for this scan.
1011   * If "raw" is enabled the scan will return all
1012   * delete marker and deleted rows that have not
1013   * been collected, yet.
1014   * This is mostly useful for Scan on column families
1015   * that have KEEP_DELETED_ROWS enabled.
1016   * It is an error to specify any column when "raw" is set.
1017   * @param raw True/False to enable/disable "raw" mode.
1018   */
1019  public Scan setRaw(boolean raw) {
1020    setAttribute(RAW_ATTR, Bytes.toBytes(raw));
1021    return this;
1022  }
1023
1024  /**
1025   * @return True if this Scan is in "raw" mode.
1026   */
1027  public boolean isRaw() {
1028    byte[] attr = getAttribute(RAW_ATTR);
1029    return attr == null ? false : Bytes.toBoolean(attr);
1030  }
1031
1032  /**
1033   * Set whether this scan is a small scan
1034   * <p>
1035   * Small scan should use pread and big scan can use seek + read seek + read is fast but can cause
1036   * two problem (1) resource contention (2) cause too much network io [89-fb] Using pread for
1037   * non-compaction read request https://issues.apache.org/jira/browse/HBASE-7266 On the other hand,
1038   * if setting it true, we would do openScanner,next,closeScanner in one RPC call. It means the
1039   * better performance for small scan. [HBASE-9488]. Generally, if the scan range is within one
1040   * data block(64KB), it could be considered as a small scan.
1041   * @param small
1042   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use {@link #setLimit(int)} and
1043   *   {@link #setReadType(ReadType)} instead. And for the one rpc optimization, now we will also
1044   *   fetch data when openScanner, and if the number of rows reaches the limit then we will close
1045   *   the scanner automatically which means we will fall back to one rpc.
1046   * @see #setLimit(int)
1047   * @see #setReadType(ReadType)
1048   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17045">HBASE-17045</a>
1049   */
1050  @Deprecated
1051  public Scan setSmall(boolean small) {
1052    this.small = small;
1053    this.readType = ReadType.PREAD;
1054    return this;
1055  }
1056
1057  /**
1058   * Get whether this scan is a small scan
1059   * @return true if small scan
1060   * @deprecated since 2.0.0 and will be removed in 3.0.0. See the comment of
1061   *   {@link #setSmall(boolean)}
1062   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17045">HBASE-17045</a>
1063   */
1064  @Deprecated
1065  public boolean isSmall() {
1066    return small;
1067  }
1068
1069  @Override
1070  public Scan setAttribute(String name, byte[] value) {
1071    return (Scan) super.setAttribute(name, value);
1072  }
1073
1074  @Override
1075  public Scan setId(String id) {
1076    return (Scan) super.setId(id);
1077  }
1078
1079  @Override
1080  public Scan setAuthorizations(Authorizations authorizations) {
1081    return (Scan) super.setAuthorizations(authorizations);
1082  }
1083
1084  @Override
1085  public Scan setACL(Map<String, Permission> perms) {
1086    return (Scan) super.setACL(perms);
1087  }
1088
1089  @Override
1090  public Scan setACL(String user, Permission perms) {
1091    return (Scan) super.setACL(user, perms);
1092  }
1093
1094  @Override
1095  public Scan setConsistency(Consistency consistency) {
1096    return (Scan) super.setConsistency(consistency);
1097  }
1098
1099  @Override
1100  public Scan setReplicaId(int Id) {
1101    return (Scan) super.setReplicaId(Id);
1102  }
1103
1104  @Override
1105  public Scan setIsolationLevel(IsolationLevel level) {
1106    return (Scan) super.setIsolationLevel(level);
1107  }
1108
1109  @Override
1110  public Scan setPriority(int priority) {
1111    return (Scan) super.setPriority(priority);
1112  }
1113
1114  /**
1115   * Enable collection of {@link ScanMetrics}. For advanced users.
1116   * @param enabled Set to true to enable accumulating scan metrics
1117   */
1118  public Scan setScanMetricsEnabled(final boolean enabled) {
1119    setAttribute(Scan.SCAN_ATTRIBUTES_METRICS_ENABLE, Bytes.toBytes(Boolean.valueOf(enabled)));
1120    return this;
1121  }
1122
1123  /**
1124   * @return True if collection of scan metrics is enabled. For advanced users.
1125   */
1126  public boolean isScanMetricsEnabled() {
1127    byte[] attr = getAttribute(Scan.SCAN_ATTRIBUTES_METRICS_ENABLE);
1128    return attr == null ? false : Bytes.toBoolean(attr);
1129  }
1130
1131  public Boolean isAsyncPrefetch() {
1132    return asyncPrefetch;
1133  }
1134
1135  /**
1136   * @deprecated Since 3.0.0, will be removed in 4.0.0. After building sync client upon async
1137   *             client, the implementation is always 'async prefetch', so this flag is useless now.
1138   */
1139  @Deprecated
1140  public Scan setAsyncPrefetch(boolean asyncPrefetch) {
1141    this.asyncPrefetch = asyncPrefetch;
1142    return this;
1143  }
1144
1145  /**
1146   * @return the limit of rows for this scan
1147   */
1148  public int getLimit() {
1149    return limit;
1150  }
1151
1152  /**
1153   * Set the limit of rows for this scan. We will terminate the scan if the number of returned rows
1154   * reaches this value.
1155   * <p>
1156   * This condition will be tested at last, after all other conditions such as stopRow, filter, etc.
1157   * @param limit the limit of rows for this scan
1158   * @return this
1159   */
1160  public Scan setLimit(int limit) {
1161    this.limit = limit;
1162    return this;
1163  }
1164
1165  /**
1166   * Call this when you only want to get one row. It will set {@code limit} to {@code 1}, and also
1167   * set {@code readType} to {@link ReadType#PREAD}.
1168   * @return this
1169   */
1170  public Scan setOneRowLimit() {
1171    return setLimit(1).setReadType(ReadType.PREAD);
1172  }
1173
1174  @InterfaceAudience.Public
1175  public enum ReadType {
1176    DEFAULT, STREAM, PREAD
1177  }
1178
1179  /**
1180   * @return the read type for this scan
1181   */
1182  public ReadType getReadType() {
1183    return readType;
1184  }
1185
1186  /**
1187   * Set the read type for this scan.
1188   * <p>
1189   * Notice that we may choose to use pread even if you specific {@link ReadType#STREAM} here. For
1190   * example, we will always use pread if this is a get scan.
1191   * @return this
1192   */
1193  public Scan setReadType(ReadType readType) {
1194    this.readType = readType;
1195    return this;
1196  }
1197
1198  /**
1199   * Get the mvcc read point used to open a scanner.
1200   */
1201  long getMvccReadPoint() {
1202    return mvccReadPoint;
1203  }
1204
1205  /**
1206   * Set the mvcc read point used to open a scanner.
1207   */
1208  Scan setMvccReadPoint(long mvccReadPoint) {
1209    this.mvccReadPoint = mvccReadPoint;
1210    return this;
1211  }
1212
1213  /**
1214   * Set the mvcc read point to -1 which means do not use it.
1215   */
1216  Scan resetMvccReadPoint() {
1217    return setMvccReadPoint(-1L);
1218  }
1219
1220  /**
1221   * When the server is slow or we scan a table with many deleted data or we use a sparse filter,
1222   * the server will response heartbeat to prevent timeout. However the scanner will return a Result
1223   * only when client can do it. So if there are many heartbeats, the blocking time on
1224   * ResultScanner#next() may be very long, which is not friendly to online services.
1225   *
1226   * Set this to true then you can get a special Result whose #isCursor() returns true and is not
1227   * contains any real data. It only tells you where the server has scanned. You can call next
1228   * to continue scanning or open a new scanner with this row key as start row whenever you want.
1229   *
1230   * Users can get a cursor when and only when there is a response from the server but we can not
1231   * return a Result to users, for example, this response is a heartbeat or there are partial cells
1232   * but users do not allow partial result.
1233   *
1234   * Now the cursor is in row level which means the special Result will only contains a row key.
1235   * {@link Result#isCursor()}
1236   * {@link Result#getCursor()}
1237   * {@link Cursor}
1238   */
1239  public Scan setNeedCursorResult(boolean needCursorResult) {
1240    this.needCursorResult = needCursorResult;
1241    return this;
1242  }
1243
1244  public boolean isNeedCursorResult() {
1245    return needCursorResult;
1246  }
1247
1248  /**
1249   * Create a new Scan with a cursor. It only set the position information like start row key.
1250   * The others (like cfs, stop row, limit) should still be filled in by the user.
1251   * {@link Result#isCursor()}
1252   * {@link Result#getCursor()}
1253   * {@link Cursor}
1254   */
1255  public static Scan createScanFromCursor(Cursor cursor) {
1256    return new Scan().withStartRow(cursor.getRow());
1257  }
1258}