/** * Sets whether or not the server should populate its block cache. * @param populate_blockcache if {@code false}, the block cache of the server * will not be populated as the rows are being scanned. If {@code true} (the * default), the blocks loaded by the server in order to feed the scanner * <em>may</em> be added to the block cache, which will make subsequent read * accesses to the same rows and other neighbouring rows faster. Whether or * not blocks will be added to the cache depend on the table's configuration. * <p> * If you scan a sequence of keys that is unlikely to be accessed again in * the near future, you can help the server improve its cache efficiency by * setting this to {@code false}. * @throws IllegalStateException if scanning already started. */ public void setServerBlockCache(final boolean populate_blockcache) { checkScanningNotStarted(); this.populate_blockcache = populate_blockcache; }
/** * Specifies if the scan will be in reverse or not * @param reversed Indication of scan direction. If this is not * invoked, scanning will default to not being reversed. * * In a reversed scan, the first Scanner opened is opened on the region * that the Scanner start key is in (the same as forward scan). But * subsequent scanners are opened via the overloaded * {@link OpenScannerRequest} and the region to be opened on is * found through a META lookup using * {@link HBaseClient#locateRegionClosestBeforeKey}. * */ public void setReversed(boolean reversed){ checkScanningNotStarted(); is_reversed = reversed; }
/** * Sets the maximum number of bytes returned at once by the scanner. * <p> * HBase may actually return more than this many bytes because it will not * truncate a row in the middle. * <p> * This value is only used when communicating with HBase 0.95 and newer. * For older versions of HBase this value is silently ignored. * @param max_num_bytes A strictly positive number of bytes. * @since 1.5 * @throws IllegalStateException if scanning already started. * @throws IllegalArgumentException if {@code max_num_bytes <= 0} */ public void setMaxNumBytes(final long max_num_bytes) { if (max_num_bytes <= 0) { throw new IllegalArgumentException("Need a strictly positive number of" + " bytes, got " + max_num_bytes); } checkScanningNotStarted(); this.max_num_bytes = max_num_bytes; }
/** * Sets the maximum number of versions to return for each cell scanned. * <p> * By default a scanner will only return the most recent version of * each cell. If you want to get all possible versions available, * pass {@link Integer#MAX_VALUE} in argument. * @param versions A strictly positive number of versions to return. * @since 1.4 * @throws IllegalStateException if scanning already started. * @throws IllegalArgumentException if {@code versions <= 0} */ public void setMaxVersions(final int versions) { if (versions <= 0) { throw new IllegalArgumentException("Need a strictly positive number: " + versions); } checkScanningNotStarted(); this.versions = versions; }
/** * Specifies from which row key to start scanning (inclusive). * @param start_key The row key to start scanning from. If you don't invoke * this method, scanning will begin from the first row key in the table. * <strong>This byte array will NOT be copied.</strong> * @throws IllegalStateException if scanning already started. */ public void setStartKey(final byte[] start_key) { KeyValue.checkKey(start_key); checkScanningNotStarted(); this.start_key = start_key; }
/** * Sets the maximum number of {@link KeyValue}s the server is allowed to * return in a single RPC response. * <p> * If you're dealing with wide rows, in which you have many cells, you may * want to limit the number of cells ({@code KeyValue}s) that the server * returns in a single RPC response. * <p> * The default is {@link #DEFAULT_MAX_NUM_KVS}, unlike in HBase's client * where the default is {@code -1}. If you set this to a negative value, * the server will always return full rows, no matter how wide they are. If * you request really wide rows, this may cause increased memory consumption * on the server side as the server has to build a large RPC response, even * if it tries to avoid copying data. On the client side, the consequences * on memory usage are worse due to the lack of framing in RPC responses. * The client will have to buffer a large RPC response and will have to do * several memory copies to dynamically grow the size of the buffer as more * and more data comes in. * @param max_num_kvs A non-zero value. * @throws IllegalArgumentException if the argument is zero. * @throws IllegalStateException if scanning already started. */ public void setMaxNumKeyValues(final int max_num_kvs) { if (max_num_kvs == 0) { throw new IllegalArgumentException("batch size can't be zero"); } checkScanningNotStarted(); this.max_num_kvs = max_num_kvs; }
/** * Specifies a particular column family to scan. * @param family The column family. * <strong>This byte array will NOT be copied.</strong> * @throws IllegalStateException if scanning already started. */ public void setFamily(final byte[] family) { KeyValue.checkFamily(family); checkScanningNotStarted(); families = new byte[][] { family }; }
/** * Sets the maximum timestamp to scan (exclusive). * <p> * {@link KeyValue}s that have a timestamp greater than or equal to this one * will not be returned by the scanner. HBase has internal optimizations to * avoid loading in memory data filtered out in some cases. * @param timestamp The maximum timestamp to scan (exclusive). * @throws IllegalArgumentException if {@code timestamp < 0}. * @throws IllegalArgumentException if {@code timestamp < getMinTimestamp()}. * @see #setTimeRange * @since 1.3 */ public void setMaxTimestamp(final long timestamp) { if (timestamp < 0) { throw new IllegalArgumentException("Negative timestamp: " + timestamp); } else if (timestamp < min_timestamp) { throw new IllegalArgumentException("New maximum timestamp (" + timestamp + ") is greater than the minimum" + " timestamp: " + min_timestamp); } checkScanningNotStarted(); max_timestamp = timestamp; }
/** * Specifies a particular column qualifier to scan. * <p> * Note that specifying a qualifier without a family has no effect. * You need to call {@link #setFamily(byte[])} too. * @param qualifier The column qualifier. * <strong>This byte array will NOT be copied.</strong> * @throws IllegalStateException if scanning already started. */ public void setQualifier(final byte[] qualifier) { KeyValue.checkQualifier(qualifier); checkScanningNotStarted(); this.qualifiers = new byte[][][] { { qualifier } }; }
/** * Sets the time range to scan. * <p> * {@link KeyValue}s that have a timestamp that do not fall in the range * {@code [min_timestamp; max_timestamp[} will not be returned by the * scanner. HBase has internal optimizations to avoid loading in memory * data filtered out in some cases. * @param min_timestamp The minimum timestamp to scan (inclusive). * @param max_timestamp The maximum timestamp to scan (exclusive). * @throws IllegalArgumentException if {@code min_timestamp < 0} * @throws IllegalArgumentException if {@code max_timestamp < 0} * @throws IllegalArgumentException if {@code min_timestamp > max_timestamp} * @since 1.3 */ public void setTimeRange(final long min_timestamp, final long max_timestamp) { if (min_timestamp > max_timestamp) { throw new IllegalArgumentException("New minimum timestamp (" + min_timestamp + ") is greater than the new maximum" + " timestamp: " + max_timestamp); } else if (min_timestamp < 0) { throw new IllegalArgumentException("Negative minimum timestamp: " + min_timestamp); } checkScanningNotStarted(); // We now have the guarantee that max_timestamp >= 0, no need to check it. this.min_timestamp = min_timestamp; this.max_timestamp = max_timestamp; }
/** * Sets the minimum timestamp to scan (inclusive). * <p> * {@link KeyValue}s that have a timestamp strictly less than this one * will not be returned by the scanner. HBase has internal optimizations to * avoid loading in memory data filtered out in some cases. * @param timestamp The minimum timestamp to scan (inclusive). * @throws IllegalArgumentException if {@code timestamp < 0}. * @throws IllegalArgumentException if {@code timestamp > getMaxTimestamp()}. * @see #setTimeRange * @since 1.3 */ public void setMinTimestamp(final long timestamp) { if (timestamp < 0) { throw new IllegalArgumentException("Negative timestamp: " + timestamp); } else if (timestamp > max_timestamp) { throw new IllegalArgumentException("New minimum timestamp (" + timestamp + ") is greater than the maximum" + " timestamp: " + max_timestamp); } checkScanningNotStarted(); min_timestamp = timestamp; }
/** * Specifies up to which row key to scan (exclusive). * @param stop_key The row key to scan up to. If you don't invoke * this method, or if the array is empty ({@code stop_key.length == 0}), * every row up to and including the last one will be scanned. * <strong>This byte array will NOT be copied.</strong> * @throws IllegalStateException if scanning already started. */ public void setStopKey(final byte[] stop_key) { KeyValue.checkKey(stop_key); checkScanningNotStarted(); this.stop_key = stop_key; }
/** * Specifies multiple column families to scan. * <p> * NOTE: This will null out the qualifiers list if it was set previously as * well as replace any families that were already set. * @param families A list of one or more family names. * @throws IllegalStateException if scanning already started. * @since 1.5 */ public void setFamilies(final String... families) { checkScanningNotStarted(); this.families = new byte[families.length][]; for (int i = 0; i < families.length; i++) { this.families[i] = families[i].getBytes(); KeyValue.checkFamily(this.families[i]); } qualifiers = null; }
/** * Specifies one or more column qualifiers to scan. * <p> * Note that specifying qualifiers without a family has no effect. * You need to call {@link #setFamily(byte[])} too. * @param qualifiers The column qualifiers. * <strong>These byte arrays will NOT be copied.</strong> * @throws IllegalStateException if scanning already started. * @since 1.4 */ public void setQualifiers(final byte[][] qualifiers) { checkScanningNotStarted(); for (final byte[] qualifier : qualifiers) { KeyValue.checkQualifier(qualifier); } this.qualifiers = new byte[][][] { qualifiers }; }
/** * Specifies multiple column families to scan. * <p> * If {@code qualifiers} is not {@code null}, then {@code qualifiers[i]} * is assumed to be the list of qualifiers to scan in the family * {@code families[i]}. If {@code qualifiers[i]} is {@code null}, then * all the columns in the family {@code families[i]} will be scanned. * @param families Array of column families names. * @param qualifiers Array of column qualifiers. Can be {@code null}. * <strong>This array of byte arrays will NOT be copied.</strong> * @throws IllegalStateException if scanning already started. * @since 1.5 */ public void setFamilies(byte[][] families, byte[][][] qualifiers) { checkScanningNotStarted(); for (int i = 0; i < families.length; i++) { KeyValue.checkFamily(families[i]); if (qualifiers != null && qualifiers[i] != null) { for (byte[] qualifier : qualifiers[i]) { KeyValue.checkQualifier(qualifier); } } } this.families = families; this.qualifiers = qualifiers; }