From a5757ff3c274215a97dee0de705c5b4220b23bc2 Mon Sep 17 00:00:00 2001 From: fyrz Date: Fri, 3 Oct 2014 11:50:40 +0200 Subject: [PATCH] Listing of changes - JavaDoc readability of RocksObject JavaDoc - JavaDoc improvements BlockBasedTableConfig, GenericRateLimiterConfig, RocksDB - JavaDoc improvements MemTableConfig - JavaDoc improvements RocksObject - JavaDoc improvements GenericRateLimiterConfig - JavaDoc improvements ReadOptions - JavaDoc improvements RateLimiterConfig - JavaDoc improvements RestoreOptions - JavaDoc improvements RestoreBackupableDB - JavaDoc improvements BlockBasedTableConfig - JavaDoc improvements Options - JavaDoc improvements BackupableDB and BackupableDBOptions --- java/org/rocksdb/BackupableDB.java | 23 +- java/org/rocksdb/BackupableDBOptions.java | 50 +++-- java/org/rocksdb/BlockBasedTableConfig.java | 23 +- .../org/rocksdb/GenericRateLimiterConfig.java | 34 ++- java/org/rocksdb/MemTableConfig.java | 2 +- java/org/rocksdb/Options.java | 204 +++++++++--------- java/org/rocksdb/RateLimiterConfig.java | 9 +- java/org/rocksdb/ReadOptions.java | 5 +- java/org/rocksdb/RestoreBackupableDB.java | 21 +- java/org/rocksdb/RestoreOptions.java | 14 +- java/org/rocksdb/RocksDB.java | 9 +- java/org/rocksdb/RocksObject.java | 77 ++++--- 12 files changed, 275 insertions(+), 196 deletions(-) diff --git a/java/org/rocksdb/BackupableDB.java b/java/org/rocksdb/BackupableDB.java index 108c4deb5..3ee29b347 100644 --- a/java/org/rocksdb/BackupableDB.java +++ b/java/org/rocksdb/BackupableDB.java @@ -8,19 +8,19 @@ package org.rocksdb; /** * A subclass of RocksDB which supports backup-related operations. * - * @see BackupableDBOptions + * @see org.rocksdb.BackupableDBOptions */ public class BackupableDB extends RocksDB { /** - * Open a BackupableDB under the specified path. + * Open a {@code BackupableDB} under the specified path. * Note that the backup path should be set properly in the * input BackupableDBOptions. * - * @param opt options for db. - * @param bopt backup related options. - * @param the db path for storing data. The path for storing - * backup should be specified in the BackupableDBOptions. - * @return reference to the opened BackupableDB. + * @param opt {@link org.rocksdb.Options} to set for the database. + * @param bopt {@link org.rocksdb.BackupableDBOptions} to use. + * @param db_path Path to store data to. The path for storing the backup should be + * specified in the {@link org.rocksdb.BackupableDBOptions}. + * @return BackupableDB reference to the opened database. */ public static BackupableDB open( Options opt, BackupableDBOptions bopt, String db_path) @@ -61,10 +61,9 @@ public class BackupableDB extends RocksDB { /** * Close the BackupableDB instance and release resource. * - * Internally, BackupableDB owns the rocksdb::DB pointer to its - * associated RocksDB. The release of that RocksDB pointer is - * handled in the destructor of the c++ rocksdb::BackupableDB and - * should be transparent to Java developers. + * Internally, BackupableDB owns the {@code rocksdb::DB} pointer to its associated + * {@link org.rocksdb.RocksDB}. The release of that RocksDB pointer is handled in the destructor + * of the c++ {@code rocksdb::BackupableDB} and should be transparent to Java developers. */ @Override public synchronized void close() { if (isInitialized()) { @@ -74,7 +73,7 @@ public class BackupableDB extends RocksDB { /** * A protected construction that will be used in the static factory - * method BackupableDB.open(). + * method {@link #open(Options, BackupableDBOptions, String)}. */ protected BackupableDB() { super(); diff --git a/java/org/rocksdb/BackupableDBOptions.java b/java/org/rocksdb/BackupableDBOptions.java index 2c5047f77..07751a64d 100644 --- a/java/org/rocksdb/BackupableDBOptions.java +++ b/java/org/rocksdb/BackupableDBOptions.java @@ -7,33 +7,41 @@ package org.rocksdb; /** * BackupableDBOptions to control the behavior of a backupable database. - * It will be used during the creation of a BackupableDB. + * It will be used during the creation of a {@link org.rocksdb.BackupableDB}. * * Note that dispose() must be called before an Options instance * become out-of-scope to release the allocated memory in c++. * - * @param path Where to keep the backup files. Has to be different than dbname. - Best to set this to dbname_ + "/backups" - * @param shareTableFiles If 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 - * share_table_files == false, each backup will be on its own and will not - * share any data with other backups. default: true - * @param sync If sync == true, we can guarantee you'll get consistent backup - * even on a machine crash/reboot. Backup process is slower with sync - * enabled. If sync == false, we don't guarantee anything on machine reboot. - * However, chances are some of the backups are consistent. Default: true - * @param destroyOldData If true, it will delete whatever backups there are - * already. Default: false - * @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 - * @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 - * @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 + * @see org.rocksdb.BackupableDB */ public class BackupableDBOptions extends RocksObject { + + /** + * 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"} + * @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 + * @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 + * @param destroyOldData If true, it will delete whatever backups there are already. + * Default: false + * @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 + * @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 + * @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 + */ public BackupableDBOptions(String path, boolean shareTableFiles, boolean sync, boolean destroyOldData, boolean backupLogFiles, long backupRateLimit, long restoreRateLimit) { diff --git a/java/org/rocksdb/BlockBasedTableConfig.java b/java/org/rocksdb/BlockBasedTableConfig.java index 9a6967a95..2f9f0ac64 100644 --- a/java/org/rocksdb/BlockBasedTableConfig.java +++ b/java/org/rocksdb/BlockBasedTableConfig.java @@ -27,7 +27,7 @@ public class BlockBasedTableConfig extends TableFormatConfig { /** * Disable block cache. If this is set to true, * then no block cache should be used, and the block_cache should - * point to a nullptr object. + * point to a {@code nullptr} object. * Default: false * * @param noBlockCache if use block cache @@ -69,7 +69,7 @@ public class BlockBasedTableConfig extends TableFormatConfig { * Controls the number of shards for the block cache. * This is applied only if cacheSize is set to non-negative. * - * @param numShardBits the number of shard bits. The resulting + * @param blockCacheNumShardBits the number of shard bits. The resulting * number of shards would be 2 ^ numShardBits. Any negative * number means use default settings." * @return the reference to the current option. @@ -176,13 +176,14 @@ public class BlockBasedTableConfig extends TableFormatConfig { /** * Use the specified filter policy to reduce disk reads. * - * Filter should not be disposed before options instances using this filter is - * disposed. If dispose() function is not called, then filter object will be - * GC'd automatically. + * {@link org.rocksdb.Filter} should not be disposed before options instances + * using this filter is disposed. If {@link Filter#dispose()} function is not + * called, then filter object will be GC'd automatically. * - * Filter instance can be re-used in multiple options instances. + * {@link org.rocksdb.Filter} instance can be re-used in multiple options + * instances. * - * @param Filter Filter Policy java instance. + * @param filter {@link org.rocksdb.Filter} Filter Policy java instance. * @return the reference to the current config. */ public BlockBasedTableConfig setFilter(Filter filter) { @@ -206,7 +207,7 @@ public class BlockBasedTableConfig extends TableFormatConfig { If not specified, each "table reader" object will pre-load index/filter block during table initialization. * - * @param index and filter blocks should be put in block cache. + * @param cacheIndexAndFilterBlocks and filter blocks should be put in block cache. * @return the reference to the current config. */ public BlockBasedTableConfig setCacheIndexAndFilterBlocks( @@ -233,7 +234,7 @@ public class BlockBasedTableConfig extends TableFormatConfig { if true, does not store prefix and allows prefix hash collision (less memory consumption) * - * @param if hash collisions should be allowed. + * @param hashIndexAllowCollision points out if hash collisions should be allowed. * @return the reference to the current config. */ public BlockBasedTableConfig setHashIndexAllowCollision( @@ -256,7 +257,7 @@ public class BlockBasedTableConfig extends TableFormatConfig { * Size of compressed block cache. If 0, then block_cache_compressed is set * to null. * - * @param size of compressed block cache. + * @param blockCacheCompressedSize of compressed block cache. * @return the reference to the current config. */ public BlockBasedTableConfig setBlockCacheCompressedSize( @@ -281,7 +282,7 @@ public class BlockBasedTableConfig extends TableFormatConfig { * Controls the number of shards for the block compressed cache. * This is applied only if blockCompressedCacheSize is set to non-negative. * - * @param numShardBits the number of shard bits. The resulting + * @param blockCacheCompressedNumShardBits the number of shard bits. The resulting * number of shards would be 2 ^ numShardBits. Any negative * number means use default settings." * @return the reference to the current option. diff --git a/java/org/rocksdb/GenericRateLimiterConfig.java b/java/org/rocksdb/GenericRateLimiterConfig.java index 78b8b37ec..2a2e7b657 100644 --- a/java/org/rocksdb/GenericRateLimiterConfig.java +++ b/java/org/rocksdb/GenericRateLimiterConfig.java @@ -7,18 +7,48 @@ package org.rocksdb; /** * Config for rate limiter, which is used to control write rate of flush and * compaction. + * + * @see RateLimiterConfig */ public class GenericRateLimiterConfig extends RateLimiterConfig { private static final long DEFAULT_REFILL_PERIOD_MICROS = (100 * 1000); private static final int DEFAULT_FAIRNESS = 10; - + + /** + * GenericRateLimiterConfig constructor + * + * @param rateBytesPerSecond this is the only parameter you want to set + * most of the time. It controls the total write rate of compaction + * and flush in bytes per second. Currently, RocksDB does not enforce + * rate limit for anything other than flush and compaction, e.g. write to WAL. + * @param refillPeriodMicros this controls how often tokens are refilled. For example, + * when rate_bytes_per_sec is set to 10MB/s and refill_period_us is set to + * 100ms, then 1MB is refilled every 100ms internally. Larger value can lead to + * burstier writes while smaller value introduces more CPU overhead. + * The default should work for most cases. + * @param fairness RateLimiter accepts high-pri requests and low-pri requests. + * A low-pri request is usually blocked in favor of hi-pri request. Currently, + * RocksDB assigns low-pri to request from compaction and high-pri to request + * from flush. Low-pri requests can get blocked if flush requests come in + * continuously. This fairness parameter grants low-pri requests permission by + * fairness chance even though high-pri requests exist to avoid starvation. + * You should be good by leaving it at default 10. + */ public GenericRateLimiterConfig(long rateBytesPerSecond, long refillPeriodMicros, int fairness) { rateBytesPerSecond_ = rateBytesPerSecond; refillPeriodMicros_ = refillPeriodMicros; fairness_ = fairness; } - + + /** + * GenericRateLimiterConfig constructor + * + * @param rateBytesPerSecond this is the only parameter you want to set + * most of the time. It controls the total write rate of compaction + * and flush in bytes per second. Currently, RocksDB does not enforce + * rate limit for anything other than flush and compaction, e.g. write to WAL. + */ public GenericRateLimiterConfig(long rateBytesPerSecond) { this(rateBytesPerSecond, DEFAULT_REFILL_PERIOD_MICROS, DEFAULT_FAIRNESS); } diff --git a/java/org/rocksdb/MemTableConfig.java b/java/org/rocksdb/MemTableConfig.java index a473c2585..904aa37b5 100644 --- a/java/org/rocksdb/MemTableConfig.java +++ b/java/org/rocksdb/MemTableConfig.java @@ -21,7 +21,7 @@ public abstract class MemTableConfig { * which will create a c++ shared-pointer to the c++ MemTableRepFactory * that associated with the Java MemTableConfig. * - * @see Options.setMemTableFactory() + * @see Options#setMemTableConfig(MemTableConfig) */ abstract protected long newMemTableFactoryHandle(); } diff --git a/java/org/rocksdb/Options.java b/java/org/rocksdb/Options.java index 7ccc74834..642c6c4dd 100644 --- a/java/org/rocksdb/Options.java +++ b/java/org/rocksdb/Options.java @@ -7,10 +7,10 @@ package org.rocksdb; /** * Options to control the behavior of a database. It will be used - * during the creation of a RocksDB (i.e., RocksDB.open()). + * during the creation of a {@link org.rocksdb.RocksDB} (i.e., RocksDB.open()). * - * If dispose() function is not called, then it will be GC'd automatically and - * native resources will be released as part of the process. + * If {@link #dispose()} function is not called, then it will be GC'd automatically + * and native resources will be released as part of the process. */ public class Options extends RocksObject { static { @@ -30,7 +30,7 @@ public class Options extends RocksObject { * Construct options for opening a RocksDB. * * This constructor will create (by allocating a block of memory) - * an rocksdb::Options in the c++ side. + * an {@code rocksdb::Options} in the c++ side. */ public Options() { super(); @@ -42,13 +42,14 @@ public class Options extends RocksObject { /** * If this value is set to true, then the database will be created - * if it is missing during RocksDB.open(). + * if it is missing during {@code RocksDB.open()}. * Default: false * * @param flag a flag indicating whether to create a database the - * specified database in RocksDB.open() operation is missing. - * @return the instance of the current Options. - * @see RocksDB.open() + * specified database in {@link org.rocksdb.RocksDB#open(Options, String)} operation + * is missing. + * @return the instance of the current Options + * @see org.rocksdb.RocksDB#open(Options, String) */ public Options setCreateIfMissing(boolean flag) { assert(isInitialized()); @@ -59,7 +60,7 @@ public class Options extends RocksObject { /** * Use the specified object to interact with the environment, * e.g. to read/write files, schedule background work, etc. - * Default: RocksEnv.getDefault() + * Default: {@link RocksEnv#getDefault()} */ public Options setEnv(RocksEnv env) { assert(isInitialized()); @@ -79,7 +80,7 @@ public class Options extends RocksObject { * If true, the database will be created if it is missing. * * @return true if the createIfMissing option is set to true. - * @see setCreateIfMissing() + * @see #setCreateIfMissing(boolean) */ public boolean createIfMissing() { assert(isInitialized()); @@ -87,12 +88,12 @@ public class Options extends RocksObject { } /** - * Set BuiltinComparator to be used with RocksDB. + * Set {@link org.rocksdb.Options.BuiltinComparator} to be used with RocksDB. * * Note: Comparator can be set once upon database creation. * * Default: BytewiseComparator. - * @param builtinComparator a BuiltinComparator type. + * @param builtinComparator a {@link org.rocksdb.Options.BuiltinComparator} type. */ public void setBuiltinComparator(BuiltinComparator builtinComparator) { assert(isInitialized()); @@ -106,7 +107,7 @@ public class Options extends RocksObject { * on disk) before converting to a sorted on-disk file. * * Larger values increase performance, especially during bulk loads. - * Up to max_write_buffer_number write buffers may be held in memory + * Up to {@code max_write_buffer_number} write buffers may be held in memory * at the same time, so you may wish to adjust this parameter * to control memory usage. * @@ -116,7 +117,7 @@ public class Options extends RocksObject { * Default: 4MB * @param writeBufferSize the size of write buffer. * @return the instance of the current Options. - * @see RocksDB.open() + * @see org.rocksdb.RocksDB#open(Options, String) */ public Options setWriteBufferSize(long writeBufferSize) { assert(isInitialized()); @@ -128,7 +129,7 @@ public class Options extends RocksObject { * Return size of write buffer size. * * @return size of write buffer. - * @see setWriteBufferSize() + * @see #setWriteBufferSize(long) */ public long writeBufferSize() { assert(isInitialized()); @@ -143,7 +144,7 @@ public class Options extends RocksObject { * * @param maxWriteBufferNumber maximum number of write buffers. * @return the instance of the current Options. - * @see RocksDB.open() + * @see org.rocksdb.RocksDB#open(Options, String) */ public Options setMaxWriteBufferNumber(int maxWriteBufferNumber) { assert(isInitialized()); @@ -155,7 +156,7 @@ public class Options extends RocksObject { * Returns maximum number of write buffers. * * @return maximum number of write buffers. - * @see setMaxWriteBufferNumber() + * @see #setMaxWriteBufferNumber(int) */ public int maxWriteBufferNumber() { assert(isInitialized()); @@ -181,9 +182,9 @@ public class Options extends RocksObject { * Default: false * * @param errorIfExists if true, an exception will be thrown - * during RocksDB.open() if the database already exists. + * during {@code RocksDB.open()} if the database already exists. * @return the reference to the current option. - * @see RocksDB.open() + * @see org.rocksdb.RocksDB#open(Options, String) */ public Options setErrorIfExists(boolean errorIfExists) { assert(isInitialized()); @@ -237,8 +238,9 @@ public class Options extends RocksObject { * Number of open files that can be used by the DB. You may need to * increase this if your database has a large working set. Value -1 means * files opened are always kept open. You can estimate number of files based - * on target_file_size_base and target_file_size_multiplier for level-based - * compaction. For universal-style compaction, you can usually set it to -1. + * on {@code target_file_size_base} and {@code target_file_size_multiplier} + * for level-based compaction. For universal-style compaction, you can usually + * set it to -1. * * @return the maximum number of open files. */ @@ -252,8 +254,9 @@ public class Options extends RocksObject { * Number of open files that can be used by the DB. You may need to * increase this if your database has a large working set. Value -1 means * files opened are always kept open. You can estimate number of files based - * on target_file_size_base and target_file_size_multiplier for level-based - * compaction. For universal-style compaction, you can usually set it to -1. + * on {@code target_file_size_base} and {@code target_file_size_multiplier} + * for level-based compaction. For universal-style compaction, you can usually + * set it to -1. * Default: 5000 * * @param maxOpenFiles the maximum number of open files. @@ -271,7 +274,7 @@ public class Options extends RocksObject { * to stable storage. Their contents remain in the OS buffers till the * OS decides to flush them. This option is good for bulk-loading * of data. Once the bulk-loading is complete, please issue a - * sync to the OS to flush all dirty buffesrs to stable storage. + * sync to the OS to flush all dirty buffers to stable storage. * * @return if true, then data-sync is disabled. */ @@ -286,7 +289,7 @@ public class Options extends RocksObject { * to stable storage. Their contents remain in the OS buffers till the * OS decides to flush them. This option is good for bulk-loading * of data. Once the bulk-loading is complete, please issue a - * sync to the OS to flush all dirty buffesrs to stable storage. + * sync to the OS to flush all dirty buffers to stable storage. * Default: false * * @param disableDataSync a boolean flag to specify whether to @@ -306,7 +309,7 @@ public class Options extends RocksObject { * This parameter should be set to true while storing data to * filesystem like ext3 that can lose files after a reboot. * - * @return true if fsync is used. + * @return boolean value indicating if fsync is used. */ public boolean useFsync() { assert(isInitialized()); @@ -438,7 +441,8 @@ public class Options extends RocksObject { * Default: 1 * * @return the maximum number of concurrent background compaction jobs. - * @see Env.setBackgroundThreads() + * @see org.rocksdb.RocksEnv#setBackgroundThreads(int) + * @see org.rocksdb.RocksEnv#setBackgroundThreads(int, int) */ public int maxBackgroundCompactions() { assert(isInitialized()); @@ -451,7 +455,7 @@ public class Options extends RocksObject { it does not use any locks to prevent concurrent updates. * * @return the instance of the current Options. - * @see RocksDB.open() + * @see org.rocksdb.RocksDB#open(Options, String) */ public Options createStatistics() { assert(isInitialized()); @@ -460,11 +464,11 @@ public class Options extends RocksObject { } /** - * Returns statistics object. Calls createStatistics() if - * C++ returns NULL pointer for statistics. + * Returns statistics object. Calls {@link #createStatistics()} if + * C++ returns {@code nullptr} for statistics. * * @return the instance of the statistics object. - * @see createStatistics() + * @see #createStatistics() */ public Statistics statisticsPtr() { assert(isInitialized()); @@ -489,8 +493,9 @@ public class Options extends RocksObject { * compaction jobs. * @return the reference to the current option. * - * @see Env.setBackgroundThreads() - * @see maxBackgroundFlushes() + * @see org.rocksdb.RocksEnv#setBackgroundThreads(int) + * @see org.rocksdb.RocksEnv#setBackgroundThreads(int, int) + * @see #maxBackgroundFlushes() */ public Options setMaxBackgroundCompactions(int maxBackgroundCompactions) { assert(isInitialized()); @@ -505,7 +510,8 @@ public class Options extends RocksObject { * Default: 1 * * @return the maximum number of concurrent background flush jobs. - * @see Env.setBackgroundThreads() + * @see org.rocksdb.RocksEnv#setBackgroundThreads(int) + * @see org.rocksdb.RocksEnv#setBackgroundThreads(int, int) */ public int maxBackgroundFlushes() { assert(isInitialized()); @@ -519,11 +525,12 @@ public class Options extends RocksObject { * HIGH priority thread pool. For more information, see * Default: 1 * - * @param maxBackgroundFlushes + * @param maxBackgroundFlushes number of max concurrent flush jobs * @return the reference to the current option. * - * @see Env.setBackgroundThreads() - * @see maxBackgroundCompactions() + * @see org.rocksdb.RocksEnv#setBackgroundThreads(int) + * @see org.rocksdb.RocksEnv#setBackgroundThreads(int, int) + * @see #maxBackgroundCompactions() */ public Options setMaxBackgroundFlushes(int maxBackgroundFlushes) { assert(isInitialized()); @@ -713,20 +720,22 @@ public class Options extends RocksObject { /** * WalTtlSeconds() and walSizeLimitMB() affect how archived logs * will be deleted. - * 1. If both set to 0, logs will be deleted asap and will not get into - * the archive. - * 2. If WAL_ttl_seconds is 0 and WAL_size_limit_MB is not 0, - * WAL files will be checked every 10 min and if total size is greater - * then WAL_size_limit_MB, they will be deleted starting with the - * earliest until size_limit is met. All empty files will be deleted. - * 3. If WAL_ttl_seconds is not 0 and WAL_size_limit_MB is 0, then - * WAL files will be checked every WAL_ttl_secondsi / 2 and those that - * are older than WAL_ttl_seconds will be deleted. - * 4. If both are not 0, WAL files will be checked every 10 min and both - * checks will be performed with ttl being first. + *
    + *
  1. If both set to 0, logs will be deleted asap and will not get into + * the archive.
    2. + *
  2. If WAL_ttl_seconds is 0 and WAL_size_limit_MB is not 0, + * WAL files will be checked every 10 min and if total size is greater + * then WAL_size_limit_MB, they will be deleted starting with the + * earliest until size_limit is met. All empty files will be deleted.
    3. + *
  3. If WAL_ttl_seconds is not 0 and WAL_size_limit_MB is 0, then + * WAL files will be checked every WAL_ttl_secondsi / 2 and those that + * are older than WAL_ttl_seconds will be deleted.
    4. + *
  4. If both are not 0, WAL files will be checked every 10 min and both + * checks will be performed with ttl being first.
    5. + *
* * @return the wal-ttl seconds - * @see walSizeLimitMB() + * @see #walSizeLimitMB() */ public long walTtlSeconds() { assert(isInitialized()); @@ -735,23 +744,24 @@ public class Options extends RocksObject { private native long walTtlSeconds(long handle); /** - * WalTtlSeconds() and walSizeLimitMB() affect how archived logs + * {@link #walTtlSeconds()} and {@link #walSizeLimitMB()} affect how archived logs * will be deleted. - * 1. If both set to 0, logs will be deleted asap and will not get into - * the archive. - * 2. If WAL_ttl_seconds is 0 and WAL_size_limit_MB is not 0, + *
    + *
  1. If both set to 0, logs will be deleted asap and will not get into + * the archive.
    2. + *
  2. If WAL_ttl_seconds is 0 and WAL_size_limit_MB is not 0, * WAL files will be checked every 10 min and if total size is greater * then WAL_size_limit_MB, they will be deleted starting with the - * earliest until size_limit is met. All empty files will be deleted. - * 3. If WAL_ttl_seconds is not 0 and WAL_size_limit_MB is 0, then + * earliest until size_limit is met. All empty files will be deleted.
    3. + *
  3. If WAL_ttl_seconds is not 0 and WAL_size_limit_MB is 0, then * WAL files will be checked every WAL_ttl_secondsi / 2 and those that - * are older than WAL_ttl_seconds will be deleted. - * 4. If both are not 0, WAL files will be checked every 10 min and both - * checks will be performed with ttl being first. + * are older than WAL_ttl_seconds will be deleted.
    4. + *
  4. If both are not 0, WAL files will be checked every 10 min and both + * checks will be performed with ttl being first.
    5. * * @param walTtlSeconds the ttl seconds * @return the reference to the current option. - * @see setWalSizeLimitMB() + * @see #setWalSizeLimitMB(long) */ public Options setWalTtlSeconds(long walTtlSeconds) { assert(isInitialized()); @@ -761,22 +771,23 @@ public class Options extends RocksObject { private native void setWalTtlSeconds(long handle, long walTtlSeconds); /** - * WalTtlSeconds() and walSizeLimitMB() affect how archived logs + * {@link #walTtlSeconds()} and {@link #walSizeLimitMB()} affect how archived logs * will be deleted. - * 1. If both set to 0, logs will be deleted asap and will not get into - * the archive. - * 2. If WAL_ttl_seconds is 0 and WAL_size_limit_MB is not 0, + *
      + *
    1. If both set to 0, logs will be deleted asap and will not get into + * the archive.
      2. + *
    2. If WAL_ttl_seconds is 0 and WAL_size_limit_MB is not 0, * WAL files will be checked every 10 min and if total size is greater * then WAL_size_limit_MB, they will be deleted starting with the - * earliest until size_limit is met. All empty files will be deleted. - * 3. If WAL_ttl_seconds is not 0 and WAL_size_limit_MB is 0, then - * WAL files will be checked every WAL_ttl_secondsi / 2 and those that - * are older than WAL_ttl_seconds will be deleted. - * 4. If both are not 0, WAL files will be checked every 10 min and both - * checks will be performed with ttl being first. - * + * earliest until size_limit is met. All empty files will be deleted.
      3. + *
    3. If WAL_ttl_seconds is not 0 and WAL_size_limit_MB is 0, then + * WAL files will be checked every WAL_ttl_seconds i / 2 and those that + * are older than WAL_ttl_seconds will be deleted.
      4. + *
    4. If both are not 0, WAL files will be checked every 10 min and both + * checks will be performed with ttl being first.
      5. + *
    * @return size limit in mega-bytes. - * @see walSizeLimitMB() + * @see #walSizeLimitMB() */ public long walSizeLimitMB() { assert(isInitialized()); @@ -787,21 +798,22 @@ public class Options extends RocksObject { /** * WalTtlSeconds() and walSizeLimitMB() affect how archived logs * will be deleted. - * 1. If both set to 0, logs will be deleted asap and will not get into - * the archive. - * 2. If WAL_ttl_seconds is 0 and WAL_size_limit_MB is not 0, + *
      + *
    1. If both set to 0, logs will be deleted asap and will not get into + * the archive.
      2. + *
    2. If WAL_ttl_seconds is 0 and WAL_size_limit_MB is not 0, * WAL files will be checked every 10 min and if total size is greater * then WAL_size_limit_MB, they will be deleted starting with the - * earliest until size_limit is met. All empty files will be deleted. - * 3. If WAL_ttl_seconds is not 0 and WAL_size_limit_MB is 0, then + * earliest until size_limit is met. All empty files will be deleted.
      3. + *
    3. If WAL_ttl_seconds is not 0 and WAL_size_limit_MB is 0, then * WAL files will be checked every WAL_ttl_secondsi / 2 and those that - * are older than WAL_ttl_seconds will be deleted. - * 4. If both are not 0, WAL files will be checked every 10 min and both - * checks will be performed with ttl being first. + * are older than WAL_ttl_seconds will be deleted.
      4. + *
    4. If both are not 0, WAL files will be checked every 10 min and both + * checks will be performed with ttl being first.
      5. * * @param sizeLimitMB size limit in mega-bytes. * @return the reference to the current option. - * @see setWalSizeLimitMB() + * @see #setWalSizeLimitMB(long) */ public Options setWalSizeLimitMB(long sizeLimitMB) { assert(isInitialized()); @@ -857,7 +869,7 @@ public class Options extends RocksObject { * Data being read from file storage may be buffered in the OS * Default: true * - * @param allowOsBufferif true, then OS buffering is allowed. + * @param allowOsBuffer if true, then OS buffering is allowed. * @return the reference to the current option. */ public Options setAllowOsBuffer(boolean allowOsBuffer) { @@ -1122,7 +1134,7 @@ public class Options extends RocksObject { * Memtable format can be set using setTableFormatConfig. * * @return the name of the currently-used memtable factory. - * @see setTableFormatConfig() + * @see #setTableFormatConfig(TableFormatConfig) */ public String memTableFactoryName() { assert(isInitialized()); @@ -1273,7 +1285,7 @@ public class Options extends RocksObject { long handle, int numLevels); /** - * The number of files in leve 0 to trigger compaction from level-0 to + * The number of files in level 0 to trigger compaction from level-0 to * level-1. A value < 0 means that level-0 compaction will not be * triggered by number of files at all. * Default: 4 @@ -1400,7 +1412,7 @@ public class Options extends RocksObject { * * @return the target size of a level-0 file. * - * @see targetFileSizeMultiplier() + * @see #targetFileSizeMultiplier() */ public int targetFileSizeBase() { return targetFileSizeBase(nativeHandle_); @@ -1421,7 +1433,7 @@ public class Options extends RocksObject { * @param targetFileSizeBase the target size of a level-0 file. * @return the reference to the current option. * - * @see setTargetFileSizeMultiplier() + * @see #setTargetFileSizeMultiplier(int) */ public Options setTargetFileSizeBase(int targetFileSizeBase) { setTargetFileSizeBase(nativeHandle_, targetFileSizeBase); @@ -1471,7 +1483,7 @@ public class Options extends RocksObject { * by default 'maxBytesForLevelBase' is 10MB. * * @return the upper-bound of the total size of leve-1 files in bytes. - * @see maxBytesForLevelMultiplier() + * @see #maxBytesForLevelMultiplier() */ public long maxBytesForLevelBase() { return maxBytesForLevelBase(nativeHandle_); @@ -1491,7 +1503,7 @@ public class Options extends RocksObject { * @return maxBytesForLevelBase the upper-bound of the total size of * leve-1 files in bytes. * @return the reference to the current option. - * @see setMaxBytesForLevelMultiplier() + * @see #setMaxBytesForLevelMultiplier(int) */ public Options setMaxBytesForLevelBase(long maxBytesForLevelBase) { setMaxBytesForLevelBase(nativeHandle_, maxBytesForLevelBase); @@ -1507,7 +1519,7 @@ public class Options extends RocksObject { * * @return the ratio between the total size of level-(L+1) files and * the total size of level-L files for all L. - * @see maxBytesForLevelBase() + * @see #maxBytesForLevelBase() */ public int maxBytesForLevelMultiplier() { return maxBytesForLevelMultiplier(nativeHandle_); @@ -1522,7 +1534,7 @@ public class Options extends RocksObject { * @param multiplier the ratio between the total size of level-(L+1) * files and the total size of level-L files for all L. * @return the reference to the current option. - * @see setMaxBytesForLevelBase() + * @see #setMaxBytesForLevelBase(long) */ public Options setMaxBytesForLevelMultiplier(int multiplier) { setMaxBytesForLevelMultiplier(nativeHandle_, multiplier); @@ -1538,7 +1550,7 @@ public class Options extends RocksObject { * (expanded_compaction_factor * targetFileSizeLevel()) many bytes. * * @return the maximum number of bytes in all compacted files. - * @see sourceCompactionFactor() + * @see #sourceCompactionFactor() */ public int expandedCompactionFactor() { return expandedCompactionFactor(nativeHandle_); @@ -1554,7 +1566,7 @@ public class Options extends RocksObject { * @param expandedCompactionFactor the maximum number of bytes in all * compacted files. * @return the reference to the current option. - * @see setSourceCompactionFactor() + * @see #setSourceCompactionFactor(int) */ public Options setExpandedCompactionFactor(int expandedCompactionFactor) { setExpandedCompactionFactor(nativeHandle_, expandedCompactionFactor); @@ -1573,7 +1585,7 @@ public class Options extends RocksObject { * a compaction. * * @return the maximum number of bytes in all source files to be compactedo. - * @see expendedCompactionFactor() + * @see #expandedCompactionFactor() */ public int sourceCompactionFactor() { return sourceCompactionFactor(nativeHandle_); @@ -1592,7 +1604,7 @@ public class Options extends RocksObject { * @param sourceCompactionFactor the maximum number of bytes in all * source files to be compacted in a single compaction run. * @return the reference to the current option. - * @see setExpendedCompactionFactor() + * @see #setExpandedCompactionFactor(int) */ public Options setSourceCompactionFactor(int sourceCompactionFactor) { setSourceCompactionFactor(nativeHandle_, sourceCompactionFactor); @@ -1979,7 +1991,7 @@ public class Options extends RocksObject { * This value will be used only when a prefix-extractor is specified. * * @return the number of bloom-bits. - * @see useFixedLengthPrefixExtractor() + * @see #useFixedLengthPrefixExtractor(int) */ public int memtablePrefixBloomBits() { return memtablePrefixBloomBits(nativeHandle_); @@ -2037,7 +2049,7 @@ public class Options extends RocksObject { * Default: 0 * * @return the level of locality of bloom-filter probes. - * @see setMemTablePrefixBloomProbes + * @see #setMemtablePrefixBloomProbes(int) */ public int bloomLocality() { return bloomLocality(nativeHandle_); @@ -2149,7 +2161,7 @@ public class Options extends RocksObject { * * Default: 2 * - * @return + * @return min partial merge operands */ public int minPartialMergeOperands() { return minPartialMergeOperands(nativeHandle_); diff --git a/java/org/rocksdb/RateLimiterConfig.java b/java/org/rocksdb/RateLimiterConfig.java index 22de65921..1b309e6c9 100644 --- a/java/org/rocksdb/RateLimiterConfig.java +++ b/java/org/rocksdb/RateLimiterConfig.java @@ -10,11 +10,12 @@ package org.rocksdb; */ public abstract class RateLimiterConfig { /** - * This function should only be called by Options.setRateLimiter(), - * which will create a c++ shared-pointer to the c++ RateLimiter - * that is associated with the Java RateLimtierConifg. + * This function should only be called by + * {@link org.rocksdb.Options#setRateLimiter(long, long)}, which will + * create a c++ shared-pointer to the c++ {@code RateLimiter} that is associated + * with a Java RateLimiterConfig. * - * @see Options.setRateLimiter() + * @see org.rocksdb.Options#setRateLimiter(long, long) */ abstract protected long newRateLimiterHandle(); } diff --git a/java/org/rocksdb/ReadOptions.java b/java/org/rocksdb/ReadOptions.java index 97c47c7d6..3590a1a87 100644 --- a/java/org/rocksdb/ReadOptions.java +++ b/java/org/rocksdb/ReadOptions.java @@ -64,7 +64,7 @@ public class ReadOptions extends RocksObject { private native boolean fillCache(long handle); /** - * Fill the cache when loading the block-based sst formated db. + * 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 * @@ -86,7 +86,8 @@ public class ReadOptions extends RocksObject { * 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! + * + * Not supported in {@code ROCKSDB_LITE} mode! * * @return true if tailing iterator is enabled. */ diff --git a/java/org/rocksdb/RestoreBackupableDB.java b/java/org/rocksdb/RestoreBackupableDB.java index dbde447a0..5bc8dfbec 100644 --- a/java/org/rocksdb/RestoreBackupableDB.java +++ b/java/org/rocksdb/RestoreBackupableDB.java @@ -11,9 +11,13 @@ package org.rocksdb; * Note that dispose() must be called before this instance become out-of-scope * to release the allocated memory in c++. * - * @param options Instance of BackupableDBOptions. */ public class RestoreBackupableDB extends RocksObject { + /** + * Constructor + * + * @param options {@link org.rocksdb.BackupableDBOptions} instance + */ public RestoreBackupableDB(BackupableDBOptions options) { super(); nativeHandle_ = newRestoreBackupableDB(options.nativeHandle_); @@ -30,6 +34,12 @@ public class RestoreBackupableDB extends RocksObject { * database will diverge from backups 4 and 5 and the new backup will fail. * If you want to create new backup, you will first have to delete backups 4 * and 5. + * + * @param backupId id pointing to backup + * @param dbDir database directory to restore to + * @param walDir directory where wal files are located + * @param restoreOptions {@link org.rocksdb.RestoreOptions} instance + * @throws RocksDBException */ public void restoreDBFromBackup(long backupId, String dbDir, String walDir, RestoreOptions restoreOptions) throws RocksDBException { @@ -39,6 +49,11 @@ public class RestoreBackupableDB extends RocksObject { /** * Restore from the latest backup. + * + * @param dbDir database directory to restore to + * @param walDir directory where wal files are located + * @param restoreOptions {@link org.rocksdb.RestoreOptions} instance + * @throws RocksDBException */ public void restoreDBFromLatestBackup(String dbDir, String walDir, RestoreOptions restoreOptions) throws RocksDBException { @@ -49,7 +64,7 @@ public class RestoreBackupableDB extends RocksObject { /** * Deletes old backups, keeping latest numBackupsToKeep alive. * - * @param Number of latest backups to keep + * @param numBackupsToKeep of latest backups to keep */ public void purgeOldBackups(int numBackupsToKeep) throws RocksDBException { purgeOldBackups0(nativeHandle_, numBackupsToKeep); @@ -58,7 +73,7 @@ public class RestoreBackupableDB extends RocksObject { /** * Deletes a specific backup. * - * @param ID of backup to delete. + * @param backupId of backup to delete. */ public void deleteBackup(long backupId) throws RocksDBException { deleteBackup0(nativeHandle_, backupId); diff --git a/java/org/rocksdb/RestoreOptions.java b/java/org/rocksdb/RestoreOptions.java index 77a2b99bc..2325c8f6c 100644 --- a/java/org/rocksdb/RestoreOptions.java +++ b/java/org/rocksdb/RestoreOptions.java @@ -11,13 +11,17 @@ package org.rocksdb; * Note that dispose() must be called before this instance become out-of-scope * to release the allocated memory in c++. * - * @param If true, restore won't overwrite the existing log files in wal_dir. It - * will also move all log files from archive directory to wal_dir. Use this - * option in combination with BackupableDBOptions::backup_log_files = false - * for persisting in-memory databases. - * Default: false */ public class RestoreOptions extends RocksObject { + /** + * Constructor + * + * @param keepLogFiles If true, restore won't overwrite the existing log files in wal_dir. It + * will also move all log files from archive directory to wal_dir. Use this + * option in combination with BackupableDBOptions::backup_log_files = false + * for persisting in-memory databases. + * Default: false + */ public RestoreOptions(boolean keepLogFiles) { super(); nativeHandle_ = newRestoreOptions(keepLogFiles); diff --git a/java/org/rocksdb/RocksDB.java b/java/org/rocksdb/RocksDB.java index a16586551..3fa2079a8 100644 --- a/java/org/rocksdb/RocksDB.java +++ b/java/org/rocksdb/RocksDB.java @@ -17,7 +17,7 @@ import org.rocksdb.NativeLibraryLoader; * A RocksDB is a persistent ordered map from keys to values. It is safe for * concurrent access from multiple threads without any external synchronization. * All methods of this class could potentially throw RocksDBException, which - * indicates sth wrong at the rocksdb library side and the call failed. + * indicates sth wrong at the RocksDB library side and the call failed. */ public class RocksDB extends RocksObject { public static final int NOT_FOUND = -1; @@ -95,12 +95,11 @@ public class RocksDB extends RocksObject { * set to true. * * @param path the path to the rocksdb. - * @param status an out value indicating the status of the Open(). * @return a rocksdb instance on success, null if the specified rocksdb can * not be opened. * - * @see Options.setCreateIfMissing() - * @see Options.createIfMissing() + * @see Options#setCreateIfMissing(boolean) + * @see org.rocksdb.Options#createIfMissing() */ public static RocksDB open(String path) throws RocksDBException { RocksDB db = new RocksDB(); @@ -280,8 +279,8 @@ public class RocksDB extends RocksObject { /** * Returns a map of keys for which values were found in DB. * - * @param List of keys for which values need to be retrieved. * @param opt Read options. + * @param keys of keys for which values need to be retrieved. * @return Map where key of map is the key passed by user and value for map * entry is the corresponding value in DB. * diff --git a/java/org/rocksdb/RocksObject.java b/java/org/rocksdb/RocksObject.java index 353918d2e..828bb4f3c 100644 --- a/java/org/rocksdb/RocksObject.java +++ b/java/org/rocksdb/RocksObject.java @@ -7,16 +7,22 @@ package org.rocksdb; /** * RocksObject is the base-class of all RocksDB classes that has a pointer to - * some c++ rocksdb object. + * some c++ {@code rocksdb} object. * - * RocksObject has dispose() function, which releases its associated c++ resource. + *

      + * RocksObject has {@code dispose()} function, which releases its associated c++ + * resource. + *

      + *

      * This function can be either called manually, or being called automatically - * during the regular Java GC process. However, since Java may wrongly assume a + * during the regular Java GC process. However, since Java may wrongly assume a * RocksObject only contains a long member variable and think it is small in size, - * Java may give RocksObject low priority in the GC process. For this, it is - * suggested to call dispose() manually. However, it is safe to let RocksObject go - * out-of-scope without manually calling dispose() as dispose() will be called - * in the finalizer during the regular GC process. + *

      + *

      Java may give {@code RocksObject} low priority in the GC process. For this, it is + * suggested to call {@code dispose()} manually. However, it is safe to let + * {@code RocksObject} go out-of-scope without manually calling {@code dispose()} + * as {@code dispose()} will be called in the finalizer during the + * regular GC process.

      */ public abstract class RocksObject { protected RocksObject() { @@ -26,16 +32,18 @@ public abstract class RocksObject { /** * Release the c++ object manually pointed by the native handle. - * - * Note that dispose() will also be called during the GC process - * if it was not called before its RocksObject went out-of-scope. + *

      + * Note that {@code dispose()} will also be called during the GC process + * if it was not called before its {@code RocksObject} went out-of-scope. * However, since Java may wrongly wrongly assume those objects are * small in that they seems to only hold a long variable. As a result, * they might have low priority in the GC process. To prevent this, - * it is suggested to call dispose() manually. - * - * Note that once an instance of RocksObject has been disposed, + * it is suggested to call {@code dispose()} manually. + *

      + *

      + * Note that once an instance of {@code RocksObject} has been disposed, * calling its function will lead undefined behavior. + *

      */ public final synchronized void dispose() { if (isOwningNativeHandle() && isInitialized()) { @@ -46,40 +54,41 @@ public abstract class RocksObject { } /** - * The helper function of dispose() which all subclasses of RocksObject - * must implement to release their associated C++ resource. + * The helper function of {@code dispose()} which all subclasses of + * {@code RocksObject} must implement to release their associated + * C++ resource. */ protected abstract void disposeInternal(); /** * Revoke ownership of the native object. - * + *

      * This will prevent the object from attempting to delete the underlying * native object in its finalizer. This must be used when another object * takes over ownership of the native object or both will attempt to delete * the underlying object when garbage collected. - * - * When disOwnNativeHandle() is called, dispose() will simply set nativeHandle_ - * to 0 without releasing its associated C++ resource. As a result, - * incorrectly use this function may cause memory leak, and this function call - * will not affect the return value of isInitialized(). - * - * @see dispose() - * @see isInitialized() + *

      + * When {@code disOwnNativeHandle()} is called, {@code dispose()} will simply set + * {@code nativeHandle_} to 0 without releasing its associated C++ resource. + * As a result, incorrectly use this function may cause memory leak, and this + * function call will not affect the return value of {@code isInitialized()}. + *

      + * @see #dispose() + * @see #isInitialized() */ protected void disOwnNativeHandle() { owningHandle_ = false; } /** - * Returns true if the current RocksObject is responsable to release its - * native handle. + * Returns true if the current {@code RocksObject} is responsible to release + * its native handle. * - * @return true if the current RocksObject is responsible to release its - * native handle. + * @return true if the current {@code RocksObject} is responsible to release + * its native handle. * - * @see disOwnNativeHandle() - * @see dispose() + * @see #disOwnNativeHandle() + * @see #dispose() */ protected boolean isOwningNativeHandle() { return owningHandle_; @@ -90,14 +99,14 @@ public abstract class RocksObject { * * @return true if the associated native handle has been initialized. * - * @see dispose() + * @see #dispose() */ protected boolean isInitialized() { return (nativeHandle_ != 0); } /** - * Simply calls dispose() and release its c++ resource if it has not + * Simply calls {@code dispose()} and release its c++ resource if it has not * yet released. */ @Override protected void finalize() { @@ -110,8 +119,8 @@ public abstract class RocksObject { protected long nativeHandle_; /** - * A flag indicating whether the current RocksObject is responsible to - * release the c++ object stored in its nativeHandle_. + * A flag indicating whether the current {@code RocksObject} is responsible to + * release the c++ object stored in its {@code nativeHandle_}. */ private boolean owningHandle_; }