org.rocksdb.BackupableDBOptions Maven / Gradle / Ivy
// 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;
import java.io.File;
/**
* BackupableDBOptions to control the behavior of a backupable database.
* It will be used during the creation of a {@link org.rocksdb.BackupEngine}.
*
* Note that dispose() must be called before an Options instance
* become out-of-scope to release the allocated memory in c++.
*
* @see org.rocksdb.BackupEngine
*/
public class BackupableDBOptions extends RocksObject {
private Env backupEnv = null;
private Logger infoLog = null;
private RateLimiter backupRateLimiter = null;
private RateLimiter restoreRateLimiter = null;
/**
* BackupableDBOptions constructor.
*
* @param path Where to keep the backup files. Has to be different than db
* name. Best to set this to {@code db name_ + "/backups"}
* @throws java.lang.IllegalArgumentException if illegal path is used.
*/
public BackupableDBOptions(final String path) {
super(newBackupableDBOptions(ensureWritableFile(path)));
}
private static String ensureWritableFile(final String path) {
final File backupPath = path == null ? null : new File(path);
if (backupPath == null || !backupPath.isDirectory() ||
!backupPath.canWrite()) {
throw new IllegalArgumentException("Illegal path provided.");
} else {
return path;
}
}
/**
* Returns the path to the BackupableDB directory.
*
* @return the path to the BackupableDB directory.
*/
public String backupDir() {
assert(isOwningHandle());
return backupDir(nativeHandle_);
}
/**
* Backup Env object. It will be used for backup file I/O. If it's
* null, backups will be written out using DBs Env. Otherwise
* backup's I/O will be performed using this object.
*
* If you want to have backups on HDFS, use HDFS Env here!
*
* Default: null
*
* @param env The environment to use
* @return instance of current BackupableDBOptions.
*/
public BackupableDBOptions setBackupEnv(final Env env) {
assert(isOwningHandle());
setBackupEnv(nativeHandle_, env.nativeHandle_);
this.backupEnv = env;
return this;
}
/**
* Backup Env object. It will be used for backup file I/O. If it's
* null, backups will be written out using DBs Env. Otherwise
* backup's I/O will be performed using this object.
*
* If you want to have backups on HDFS, use HDFS Env here!
*
* Default: null
*
* @return The environment in use
*/
public Env backupEnv() {
return this.backupEnv;
}
/**
* Share table files between backups.
*
* @param shareTableFiles If {@code share_table_files == true}, backup will
* assume that table files with same name have the same contents. This
* enables incremental backups and avoids unnecessary data copies. If
* {@code share_table_files == false}, each backup will be on its own and
* will not share any data with other backups.
*
* Default: true
*
* @return instance of current BackupableDBOptions.
*/
public BackupableDBOptions setShareTableFiles(final boolean shareTableFiles) {
assert(isOwningHandle());
setShareTableFiles(nativeHandle_, shareTableFiles);
return this;
}
/**
* Share table files between backups.
*
* @return boolean value indicating if SST files will be shared between
* backups.
*/
public boolean shareTableFiles() {
assert(isOwningHandle());
return shareTableFiles(nativeHandle_);
}
/**
* Set the logger to use for Backup info and error messages
*
* @param logger The logger to use for the backup
* @return instance of current BackupableDBOptions.
*/
public BackupableDBOptions setInfoLog(final Logger logger) {
assert(isOwningHandle());
setInfoLog(nativeHandle_, logger.nativeHandle_);
this.infoLog = logger;
return this;
}
/**
* Set the logger to use for Backup info and error messages
*
* Default: null
*
* @return The logger in use for the backup
*/
public Logger infoLog() {
return this.infoLog;
}
/**
* Set synchronous backups.
*
* @param sync If {@code sync == true}, we can guarantee you'll get consistent
* backup even on a machine crash/reboot. Backup process is slower with sync
* enabled. If {@code sync == false}, we don't guarantee anything on machine
* reboot. However, chances are some of the backups are consistent.
*
* Default: true
*
* @return instance of current BackupableDBOptions.
*/
public BackupableDBOptions setSync(final boolean sync) {
assert(isOwningHandle());
setSync(nativeHandle_, sync);
return this;
}
/**
* Are synchronous backups activated.
*
* @return boolean value if synchronous backups are configured.
*/
public boolean sync() {
assert(isOwningHandle());
return sync(nativeHandle_);
}
/**
* Set if old data will be destroyed.
*
* @param destroyOldData If true, it will delete whatever backups there are
* already.
*
* Default: false
*
* @return instance of current BackupableDBOptions.
*/
public BackupableDBOptions setDestroyOldData(final boolean destroyOldData) {
assert(isOwningHandle());
setDestroyOldData(nativeHandle_, destroyOldData);
return this;
}
/**
* Returns if old data will be destroyed will performing new backups.
*
* @return boolean value indicating if old data will be destroyed.
*/
public boolean destroyOldData() {
assert(isOwningHandle());
return destroyOldData(nativeHandle_);
}
/**
* Set if log files shall be persisted.
*
* @param backupLogFiles If false, we won't backup log files. This option can
* be useful for backing up in-memory databases where log file are
* persisted, but table files are in memory.
*
* Default: true
*
* @return instance of current BackupableDBOptions.
*/
public BackupableDBOptions setBackupLogFiles(final boolean backupLogFiles) {
assert(isOwningHandle());
setBackupLogFiles(nativeHandle_, backupLogFiles);
return this;
}
/**
* Return information if log files shall be persisted.
*
* @return boolean value indicating if log files will be persisted.
*/
public boolean backupLogFiles() {
assert(isOwningHandle());
return backupLogFiles(nativeHandle_);
}
/**
* Set backup rate limit.
*
* @param backupRateLimit Max bytes that can be transferred in a second during
* backup. If 0 or negative, then go as fast as you can.
*
* Default: 0
*
* @return instance of current BackupableDBOptions.
*/
public BackupableDBOptions setBackupRateLimit(long backupRateLimit) {
assert(isOwningHandle());
backupRateLimit = (backupRateLimit <= 0) ? 0 : backupRateLimit;
setBackupRateLimit(nativeHandle_, backupRateLimit);
return this;
}
/**
* Return backup rate limit which described the max bytes that can be
* transferred in a second during backup.
*
* @return numerical value describing the backup transfer limit in bytes per
* second.
*/
public long backupRateLimit() {
assert(isOwningHandle());
return backupRateLimit(nativeHandle_);
}
/**
* Backup rate limiter. Used to control transfer speed for backup. If this is
* not null, {@link #backupRateLimit()} is ignored.
*
* Default: null
*
* @param backupRateLimiter The rate limiter to use for the backup
* @return instance of current BackupableDBOptions.
*/
public BackupableDBOptions setBackupRateLimiter(final RateLimiter backupRateLimiter) {
assert(isOwningHandle());
setBackupRateLimiter(nativeHandle_, backupRateLimiter.nativeHandle_);
this.backupRateLimiter = backupRateLimiter;
return this;
}
/**
* Backup rate limiter. Used to control transfer speed for backup. If this is
* not null, {@link #backupRateLimit()} is ignored.
*
* Default: null
*
* @return The rate limiter in use for the backup
*/
public RateLimiter backupRateLimiter() {
assert(isOwningHandle());
return this.backupRateLimiter;
}
/**
* Set restore rate limit.
*
* @param restoreRateLimit Max bytes that can be transferred in a second
* during restore. If 0 or negative, then go as fast as you can.
*
* Default: 0
*
* @return instance of current BackupableDBOptions.
*/
public BackupableDBOptions setRestoreRateLimit(long restoreRateLimit) {
assert(isOwningHandle());
restoreRateLimit = (restoreRateLimit <= 0) ? 0 : restoreRateLimit;
setRestoreRateLimit(nativeHandle_, restoreRateLimit);
return this;
}
/**
* Return restore rate limit which described the max bytes that can be
* transferred in a second during restore.
*
* @return numerical value describing the restore transfer limit in bytes per
* second.
*/
public long restoreRateLimit() {
assert(isOwningHandle());
return restoreRateLimit(nativeHandle_);
}
/**
* Restore rate limiter. Used to control transfer speed during restore. If
* this is not null, {@link #restoreRateLimit()} is ignored.
*
* Default: null
*
* @param restoreRateLimiter The rate limiter to use during restore
* @return instance of current BackupableDBOptions.
*/
public BackupableDBOptions setRestoreRateLimiter(final RateLimiter restoreRateLimiter) {
assert(isOwningHandle());
setRestoreRateLimiter(nativeHandle_, restoreRateLimiter.nativeHandle_);
this.restoreRateLimiter = restoreRateLimiter;
return this;
}
/**
* Restore rate limiter. Used to control transfer speed during restore. If
* this is not null, {@link #restoreRateLimit()} is ignored.
*
* Default: null
*
* @return The rate limiter in use during restore
*/
public RateLimiter restoreRateLimiter() {
assert(isOwningHandle());
return this.restoreRateLimiter;
}
/**
* Only used if share_table_files is set to true. If true, will consider
* that backups can come from different databases, hence a sst is not uniquely
* identified by its name, but by the triple (file name, crc32, file length)
*
*
* @param shareFilesWithChecksum boolean value indicating if SST files are
* stored using the triple (file name, crc32, file length) and not its name.
*
* Note: this is an experimental option, and you'll need to set it manually
* turn it on only if you know what you're doing*
*
* Default: false
*
* @return instance of current BackupableDBOptions.
*/
public BackupableDBOptions setShareFilesWithChecksum(
final boolean shareFilesWithChecksum) {
assert(isOwningHandle());
setShareFilesWithChecksum(nativeHandle_, shareFilesWithChecksum);
return this;
}
/**
* Return of share files with checksum is active.
*
* @return boolean value indicating if share files with checksum
* is active.
*/
public boolean shareFilesWithChecksum() {
assert(isOwningHandle());
return shareFilesWithChecksum(nativeHandle_);
}
/**
* Up to this many background threads will copy files for
* {@link BackupEngine#createNewBackup(RocksDB, boolean)} and
* {@link BackupEngine#restoreDbFromBackup(int, String, String, RestoreOptions)}
*
* Default: 1
*
* @param maxBackgroundOperations The maximum number of background threads
* @return instance of current BackupableDBOptions.
*/
public BackupableDBOptions setMaxBackgroundOperations(
final int maxBackgroundOperations) {
assert(isOwningHandle());
setMaxBackgroundOperations(nativeHandle_, maxBackgroundOperations);
return this;
}
/**
* Up to this many background threads will copy files for
* {@link BackupEngine#createNewBackup(RocksDB, boolean)} and
* {@link BackupEngine#restoreDbFromBackup(int, String, String, RestoreOptions)}
*
* Default: 1
*
* @return The maximum number of background threads
*/
public int maxBackgroundOperations() {
assert(isOwningHandle());
return maxBackgroundOperations(nativeHandle_);
}
/**
* During backup user can get callback every time next
* {@link #callbackTriggerIntervalSize()} bytes being copied.
*
* Default: 4194304
*
* @param callbackTriggerIntervalSize The interval size for the
* callback trigger
* @return instance of current BackupableDBOptions.
*/
public BackupableDBOptions setCallbackTriggerIntervalSize(
final long callbackTriggerIntervalSize) {
assert(isOwningHandle());
setCallbackTriggerIntervalSize(nativeHandle_, callbackTriggerIntervalSize);
return this;
}
/**
* During backup user can get callback every time next
* {@link #callbackTriggerIntervalSize()} bytes being copied.
*
* Default: 4194304
*
* @return The interval size for the callback trigger
*/
public long callbackTriggerIntervalSize() {
assert(isOwningHandle());
return callbackTriggerIntervalSize(nativeHandle_);
}
private native static long newBackupableDBOptions(final String path);
private native String backupDir(long handle);
private native void setBackupEnv(final long handle, final long envHandle);
private native void setShareTableFiles(long handle, boolean flag);
private native boolean shareTableFiles(long handle);
private native void setInfoLog(final long handle, final long infoLogHandle);
private native void setSync(long handle, boolean flag);
private native boolean sync(long handle);
private native void setDestroyOldData(long handle, boolean flag);
private native boolean destroyOldData(long handle);
private native void setBackupLogFiles(long handle, boolean flag);
private native boolean backupLogFiles(long handle);
private native void setBackupRateLimit(long handle, long rateLimit);
private native long backupRateLimit(long handle);
private native void setBackupRateLimiter(long handle, long rateLimiterHandle);
private native void setRestoreRateLimit(long handle, long rateLimit);
private native long restoreRateLimit(long handle);
private native void setRestoreRateLimiter(final long handle,
final long rateLimiterHandle);
private native void setShareFilesWithChecksum(long handle, boolean flag);
private native boolean shareFilesWithChecksum(long handle);
private native void setMaxBackgroundOperations(final long handle,
final int maxBackgroundOperations);
private native int maxBackgroundOperations(final long handle);
private native void setCallbackTriggerIntervalSize(final long handle,
long callbackTriggerIntervalSize);
private native long callbackTriggerIntervalSize(final long handle);
@Override protected final native void disposeInternal(final long handle);
}