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. + *
+ * 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_; }