org.rocksdb.ReadOptions Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of rocksdbjni Show documentation
Show all versions of rocksdbjni Show documentation
RocksDB fat jar that contains .so files for linux32 and linux64 (glibc and musl-libc), jnilib files
for Mac OSX, and a .dll for Windows x64.
// Copyright (c) 2011-present, Facebook, Inc. All rights reserved.
// This source code is licensed under both the GPLv2 (found in the
// COPYING file in the root directory) and Apache 2.0 License
// (found in the LICENSE.Apache file in the root directory).
package org.rocksdb;
/**
* The class that controls the get behavior.
*
* Note that dispose() must be called before an Options instance
* become out-of-scope to release the allocated memory in c++.
*/
public class ReadOptions extends RocksObject {
public ReadOptions() {
super(newReadOptions());
}
/**
* @param verifyChecksums verification will be performed on every read
* when set to true
* @param fillCache if true, then fill-cache behavior will be performed.
*/
public ReadOptions(final boolean verifyChecksums, final boolean fillCache) {
super(newReadOptions(verifyChecksums, fillCache));
}
/**
* Copy constructor.
*
* NOTE: This does a shallow copy, which means snapshot, iterate_upper_bound
* and other pointers will be cloned!
*
* @param other The ReadOptions to copy.
*/
public ReadOptions(ReadOptions other) {
super(copyReadOptions(other.nativeHandle_));
this.iterateLowerBoundSlice_ = other.iterateLowerBoundSlice_;
this.iterateUpperBoundSlice_ = other.iterateUpperBoundSlice_;
}
/**
* If true, all data read from underlying storage will be
* verified against corresponding checksums.
* Default: true
*
* @return true if checksum verification is on.
*/
public boolean verifyChecksums() {
assert(isOwningHandle());
return verifyChecksums(nativeHandle_);
}
/**
* If true, all data read from underlying storage will be
* verified against corresponding checksums.
* Default: true
*
* @param verifyChecksums if true, then checksum verification
* will be performed on every read.
* @return the reference to the current ReadOptions.
*/
public ReadOptions setVerifyChecksums(
final boolean verifyChecksums) {
assert(isOwningHandle());
setVerifyChecksums(nativeHandle_, verifyChecksums);
return this;
}
// TODO(yhchiang): this option seems to be block-based table only.
// move this to a better place?
/**
* Fill the cache when loading the block-based sst formated db.
* Callers may wish to set this field to false for bulk scans.
* Default: true
*
* @return true if the fill-cache behavior is on.
*/
public boolean fillCache() {
assert(isOwningHandle());
return fillCache(nativeHandle_);
}
/**
* Fill the cache when loading the block-based sst formatted db.
* Callers may wish to set this field to false for bulk scans.
* Default: true
*
* @param fillCache if true, then fill-cache behavior will be
* performed.
* @return the reference to the current ReadOptions.
*/
public ReadOptions setFillCache(final boolean fillCache) {
assert(isOwningHandle());
setFillCache(nativeHandle_, fillCache);
return this;
}
/**
* Returns the currently assigned Snapshot instance.
*
* @return the Snapshot assigned to this instance. If no Snapshot
* is assigned null.
*/
public Snapshot snapshot() {
assert(isOwningHandle());
long snapshotHandle = snapshot(nativeHandle_);
if (snapshotHandle != 0) {
return new Snapshot(snapshotHandle);
}
return null;
}
/**
* If "snapshot" is non-nullptr, read as of the supplied snapshot
* (which must belong to the DB that is being read and which must
* not have been released). If "snapshot" is nullptr, use an implicit
* snapshot of the state at the beginning of this read operation.
* Default: null
*
* @param snapshot {@link Snapshot} instance
* @return the reference to the current ReadOptions.
*/
public ReadOptions setSnapshot(final Snapshot snapshot) {
assert(isOwningHandle());
if (snapshot != null) {
setSnapshot(nativeHandle_, snapshot.nativeHandle_);
} else {
setSnapshot(nativeHandle_, 0l);
}
return this;
}
/**
* Returns the current read tier.
*
* @return the read tier in use, by default {@link ReadTier#READ_ALL_TIER}
*/
public ReadTier readTier() {
assert(isOwningHandle());
return ReadTier.getReadTier(readTier(nativeHandle_));
}
/**
* Specify if this read request should process data that ALREADY
* resides on a particular cache. If the required data is not
* found at the specified cache, then {@link RocksDBException} is thrown.
*
* @param readTier {@link ReadTier} instance
* @return the reference to the current ReadOptions.
*/
public ReadOptions setReadTier(final ReadTier readTier) {
assert(isOwningHandle());
setReadTier(nativeHandle_, readTier.getValue());
return this;
}
/**
* Specify to create a tailing iterator -- a special iterator that has a
* view of the complete database (i.e. it can also be used to read newly
* added data) and is optimized for sequential reads. It will return records
* that were inserted into the database after the creation of the iterator.
* Default: false
*
* Not supported in {@code ROCKSDB_LITE} mode!
*
* @return true if tailing iterator is enabled.
*/
public boolean tailing() {
assert(isOwningHandle());
return tailing(nativeHandle_);
}
/**
* Specify to create a tailing iterator -- a special iterator that has a
* view of the complete database (i.e. it can also be used to read newly
* added data) and is optimized for sequential reads. It will return records
* that were inserted into the database after the creation of the iterator.
* Default: false
* Not supported in ROCKSDB_LITE mode!
*
* @param tailing if true, then tailing iterator will be enabled.
* @return the reference to the current ReadOptions.
*/
public ReadOptions setTailing(final boolean tailing) {
assert(isOwningHandle());
setTailing(nativeHandle_, tailing);
return this;
}
/**
* Returns whether managed iterators will be used.
*
* @return the setting of whether managed iterators will be used,
* by default false
*
* @deprecated This options is not used anymore.
*/
@Deprecated
public boolean managed() {
assert(isOwningHandle());
return managed(nativeHandle_);
}
/**
* Specify to create a managed iterator -- a special iterator that
* uses less resources by having the ability to free its underlying
* resources on request.
*
* @param managed if true, then managed iterators will be enabled.
* @return the reference to the current ReadOptions.
*
* @deprecated This options is not used anymore.
*/
@Deprecated
public ReadOptions setManaged(final boolean managed) {
assert(isOwningHandle());
setManaged(nativeHandle_, managed);
return this;
}
/**
* Returns whether a total seek order will be used
*
* @return the setting of whether a total seek order will be used
*/
public boolean totalOrderSeek() {
assert(isOwningHandle());
return totalOrderSeek(nativeHandle_);
}
/**
* Enable a total order seek regardless of index format (e.g. hash index)
* used in the table. Some table format (e.g. plain table) may not support
* this option.
*
* @param totalOrderSeek if true, then total order seek will be enabled.
* @return the reference to the current ReadOptions.
*/
public ReadOptions setTotalOrderSeek(final boolean totalOrderSeek) {
assert(isOwningHandle());
setTotalOrderSeek(nativeHandle_, totalOrderSeek);
return this;
}
/**
* Returns whether the iterator only iterates over the same prefix as the seek
*
* @return the setting of whether the iterator only iterates over the same
* prefix as the seek, default is false
*/
public boolean prefixSameAsStart() {
assert(isOwningHandle());
return prefixSameAsStart(nativeHandle_);
}
/**
* Enforce that the iterator only iterates over the same prefix as the seek.
* This option is effective only for prefix seeks, i.e. prefix_extractor is
* non-null for the column family and {@link #totalOrderSeek()} is false.
* Unlike iterate_upper_bound, {@link #setPrefixSameAsStart(boolean)} only
* works within a prefix but in both directions.
*
* @param prefixSameAsStart if true, then the iterator only iterates over the
* same prefix as the seek
* @return the reference to the current ReadOptions.
*/
public ReadOptions setPrefixSameAsStart(final boolean prefixSameAsStart) {
assert(isOwningHandle());
setPrefixSameAsStart(nativeHandle_, prefixSameAsStart);
return this;
}
/**
* Returns whether the blocks loaded by the iterator will be pinned in memory
*
* @return the setting of whether the blocks loaded by the iterator will be
* pinned in memory
*/
public boolean pinData() {
assert(isOwningHandle());
return pinData(nativeHandle_);
}
/**
* Keep the blocks loaded by the iterator pinned in memory as long as the
* iterator is not deleted, If used when reading from tables created with
* BlockBasedTableOptions::use_delta_encoding = false,
* Iterator's property "rocksdb.iterator.is-key-pinned" is guaranteed to
* return 1.
*
* @param pinData if true, the blocks loaded by the iterator will be pinned
* @return the reference to the current ReadOptions.
*/
public ReadOptions setPinData(final boolean pinData) {
assert(isOwningHandle());
setPinData(nativeHandle_, pinData);
return this;
}
/**
* If true, when PurgeObsoleteFile is called in CleanupIteratorState, we
* schedule a background job in the flush job queue and delete obsolete files
* in background.
*
* Default: false
*
* @return true when PurgeObsoleteFile is called in CleanupIteratorState
*/
public boolean backgroundPurgeOnIteratorCleanup() {
assert(isOwningHandle());
return backgroundPurgeOnIteratorCleanup(nativeHandle_);
}
/**
* If true, when PurgeObsoleteFile is called in CleanupIteratorState, we
* schedule a background job in the flush job queue and delete obsolete files
* in background.
*
* Default: false
*
* @param backgroundPurgeOnIteratorCleanup true when PurgeObsoleteFile is
* called in CleanupIteratorState
* @return the reference to the current ReadOptions.
*/
public ReadOptions setBackgroundPurgeOnIteratorCleanup(
final boolean backgroundPurgeOnIteratorCleanup) {
assert(isOwningHandle());
setBackgroundPurgeOnIteratorCleanup(nativeHandle_,
backgroundPurgeOnIteratorCleanup);
return this;
}
/**
* If non-zero, NewIterator will create a new table reader which
* performs reads of the given size. Using a large size (> 2MB) can
* improve the performance of forward iteration on spinning disks.
*
* Default: 0
*
* @return The readahead size is bytes
*/
public long readaheadSize() {
assert(isOwningHandle());
return readaheadSize(nativeHandle_);
}
/**
* If non-zero, NewIterator will create a new table reader which
* performs reads of the given size. Using a large size (> 2MB) can
* improve the performance of forward iteration on spinning disks.
*
* Default: 0
*
* @param readaheadSize The readahead size is bytes
* @return the reference to the current ReadOptions.
*/
public ReadOptions setReadaheadSize(final long readaheadSize) {
assert(isOwningHandle());
setReadaheadSize(nativeHandle_, readaheadSize);
return this;
}
/**
* A threshold for the number of keys that can be skipped before failing an
* iterator seek as incomplete.
*
* @return the number of keys that can be skipped
* before failing an iterator seek as incomplete.
*/
public long maxSkippableInternalKeys() {
assert(isOwningHandle());
return maxSkippableInternalKeys(nativeHandle_);
}
/**
* A threshold for the number of keys that can be skipped before failing an
* iterator seek as incomplete. The default value of 0 should be used to
* never fail a request as incomplete, even on skipping too many keys.
*
* Default: 0
*
* @param maxSkippableInternalKeys the number of keys that can be skipped
* before failing an iterator seek as incomplete.
*
* @return the reference to the current ReadOptions.
*/
public ReadOptions setMaxSkippableInternalKeys(
final long maxSkippableInternalKeys) {
assert(isOwningHandle());
setMaxSkippableInternalKeys(nativeHandle_, maxSkippableInternalKeys);
return this;
}
/**
* If true, keys deleted using the DeleteRange() API will be visible to
* readers until they are naturally deleted during compaction. This improves
* read performance in DBs with many range deletions.
*
* Default: false
*
* @return true if keys deleted using the DeleteRange() API will be visible
*/
public boolean ignoreRangeDeletions() {
assert(isOwningHandle());
return ignoreRangeDeletions(nativeHandle_);
}
/**
* If true, keys deleted using the DeleteRange() API will be visible to
* readers until they are naturally deleted during compaction. This improves
* read performance in DBs with many range deletions.
*
* Default: false
*
* @param ignoreRangeDeletions true if keys deleted using the DeleteRange()
* API should be visible
* @return the reference to the current ReadOptions.
*/
public ReadOptions setIgnoreRangeDeletions(final boolean ignoreRangeDeletions) {
assert(isOwningHandle());
setIgnoreRangeDeletions(nativeHandle_, ignoreRangeDeletions);
return this;
}
/**
* Defines the smallest key at which the backward
* iterator can return an entry. Once the bound is passed,
* {@link RocksIterator#isValid()} will be false.
*
* The lower bound is inclusive i.e. the bound value is a valid
* entry.
*
* If prefix_extractor is not null, the Seek target and `iterate_lower_bound`
* need to have the same prefix. This is because ordering is not guaranteed
* outside of prefix domain.
*
* Default: null
*
* @param iterateLowerBound Slice representing the upper bound
* @return the reference to the current ReadOptions.
*/
public ReadOptions setIterateLowerBound(final AbstractSlice iterateLowerBound) {
assert(isOwningHandle());
setIterateLowerBound(
nativeHandle_, iterateLowerBound == null ? 0 : iterateLowerBound.getNativeHandle());
// Hold onto a reference so it doesn't get garbage collected out from under us.
iterateLowerBoundSlice_ = iterateLowerBound;
return this;
}
/**
* Returns the smallest key at which the backward
* iterator can return an entry.
*
* The lower bound is inclusive i.e. the bound value is a valid entry.
*
* @return the smallest key, or null if there is no lower bound defined.
*/
public Slice iterateLowerBound() {
assert(isOwningHandle());
final long lowerBoundSliceHandle = iterateLowerBound(nativeHandle_);
if (lowerBoundSliceHandle != 0) {
// Disown the new slice - it's owned by the C++ side of the JNI boundary
// from the perspective of this method.
return new Slice(lowerBoundSliceHandle, false);
}
return null;
}
/**
* Defines the extent up to which the forward iterator
* can returns entries. Once the bound is reached,
* {@link RocksIterator#isValid()} will be false.
*
* The upper bound is exclusive i.e. the bound value is not a valid entry.
*
* If prefix_extractor is not null, the Seek target and iterate_upper_bound
* need to have the same prefix. This is because ordering is not guaranteed
* outside of prefix domain.
*
* Default: null
*
* @param iterateUpperBound Slice representing the upper bound
* @return the reference to the current ReadOptions.
*/
public ReadOptions setIterateUpperBound(final AbstractSlice iterateUpperBound) {
assert(isOwningHandle());
setIterateUpperBound(
nativeHandle_, iterateUpperBound == null ? 0 : iterateUpperBound.getNativeHandle());
// Hold onto a reference so it doesn't get garbage collected out from under us.
iterateUpperBoundSlice_ = iterateUpperBound;
return this;
}
/**
* Returns the largest key at which the forward
* iterator can return an entry.
*
* The upper bound is exclusive i.e. the bound value is not a valid entry.
*
* @return the largest key, or null if there is no upper bound defined.
*/
public Slice iterateUpperBound() {
assert(isOwningHandle());
final long upperBoundSliceHandle = iterateUpperBound(nativeHandle_);
if (upperBoundSliceHandle != 0) {
// Disown the new slice - it's owned by the C++ side of the JNI boundary
// from the perspective of this method.
return new Slice(upperBoundSliceHandle, false);
}
return null;
}
/**
* A callback to determine whether relevant keys for this scan exist in a
* given table based on the table's properties. The callback is passed the
* properties of each table during iteration. If the callback returns false,
* the table will not be scanned. This option only affects Iterators and has
* no impact on point lookups.
*
* Default: null (every table will be scanned)
*
* @param tableFilter the table filter for the callback.
*
* @return the reference to the current ReadOptions.
*/
public ReadOptions setTableFilter(final AbstractTableFilter tableFilter) {
assert(isOwningHandle());
setTableFilter(nativeHandle_, tableFilter.nativeHandle_);
return this;
}
/**
* Needed to support differential snapshots. Has 2 effects:
* 1) Iterator will skip all internal keys with seqnum < iter_start_seqnum
* 2) if this param > 0 iterator will return INTERNAL keys instead of user
* keys; e.g. return tombstones as well.
*
* Default: 0 (don't filter by seqnum, return user keys)
*
* @param startSeqnum the starting sequence number.
*
* @return the reference to the current ReadOptions.
*/
public ReadOptions setIterStartSeqnum(final long startSeqnum) {
assert(isOwningHandle());
setIterStartSeqnum(nativeHandle_, startSeqnum);
return this;
}
/**
* Returns the starting Sequence Number of any iterator.
* See {@link #setIterStartSeqnum(long)}.
*
* @return the starting sequence number of any iterator.
*/
public long iterStartSeqnum() {
assert(isOwningHandle());
return iterStartSeqnum(nativeHandle_);
}
// instance variables
// NOTE: If you add new member variables, please update the copy constructor above!
//
// Hold a reference to any iterate lower or upper bound that was set on this
// object until we're destroyed or it's overwritten. That way the caller can
// freely leave scope without us losing the Java Slice object, which during
// close() would also reap its associated rocksdb::Slice native object since
// it's possibly (likely) to be an owning handle.
private AbstractSlice iterateLowerBoundSlice_;
private AbstractSlice iterateUpperBoundSlice_;
private native static long newReadOptions();
private native static long newReadOptions(final boolean verifyChecksums,
final boolean fillCache);
private native static long copyReadOptions(long handle);
@Override protected final native void disposeInternal(final long handle);
private native boolean verifyChecksums(long handle);
private native void setVerifyChecksums(long handle, boolean verifyChecksums);
private native boolean fillCache(long handle);
private native void setFillCache(long handle, boolean fillCache);
private native long snapshot(long handle);
private native void setSnapshot(long handle, long snapshotHandle);
private native byte readTier(long handle);
private native void setReadTier(long handle, byte readTierValue);
private native boolean tailing(long handle);
private native void setTailing(long handle, boolean tailing);
private native boolean managed(long handle);
private native void setManaged(long handle, boolean managed);
private native boolean totalOrderSeek(long handle);
private native void setTotalOrderSeek(long handle, boolean totalOrderSeek);
private native boolean prefixSameAsStart(long handle);
private native void setPrefixSameAsStart(long handle, boolean prefixSameAsStart);
private native boolean pinData(long handle);
private native void setPinData(long handle, boolean pinData);
private native boolean backgroundPurgeOnIteratorCleanup(final long handle);
private native void setBackgroundPurgeOnIteratorCleanup(final long handle,
final boolean backgroundPurgeOnIteratorCleanup);
private native long readaheadSize(final long handle);
private native void setReadaheadSize(final long handle,
final long readaheadSize);
private native long maxSkippableInternalKeys(final long handle);
private native void setMaxSkippableInternalKeys(final long handle,
final long maxSkippableInternalKeys);
private native boolean ignoreRangeDeletions(final long handle);
private native void setIgnoreRangeDeletions(final long handle,
final boolean ignoreRangeDeletions);
private native void setIterateUpperBound(final long handle,
final long upperBoundSliceHandle);
private native long iterateUpperBound(final long handle);
private native void setIterateLowerBound(final long handle,
final long lowerBoundSliceHandle);
private native long iterateLowerBound(final long handle);
private native void setTableFilter(final long handle,
final long tableFilterHandle);
private native void setIterStartSeqnum(final long handle, final long seqNum);
private native long iterStartSeqnum(final long handle);
}
© 2015 - 2024 Weber Informatics LLC | Privacy Policy