From d7529b2de9eb20236dc20ec600c7160e6423635c Mon Sep 17 00:00:00 2001 From: fyrz Date: Sun, 16 Nov 2014 14:36:22 +0100 Subject: [PATCH] [RocksJava] Cleanup Backupable implementations - Correct usage of isInitialized() - Adjusted JavaDoc --- java/org/rocksdb/BackupableDB.java | 43 ++++++++++++------- java/org/rocksdb/RestoreBackupableDB.java | 52 ++++++++++++++--------- 2 files changed, 58 insertions(+), 37 deletions(-) diff --git a/java/org/rocksdb/BackupableDB.java b/java/org/rocksdb/BackupableDB.java index e73df52e0..5c5de5fd3 100644 --- a/java/org/rocksdb/BackupableDB.java +++ b/java/org/rocksdb/BackupableDB.java @@ -8,21 +8,23 @@ package org.rocksdb; import java.util.List; /** - * A subclass of RocksDB which supports backup-related operations. + *

A subclass of RocksDB which supports + * backup-related operations.

* * @see org.rocksdb.BackupableDBOptions */ public class BackupableDB extends RocksDB { /** - * Open a {@code 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. + * input BackupableDBOptions.

* * @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. + * + * @return {@link BackupableDB} reference to the opened database. * * @throws RocksDBException thrown if error happens in underlying * native library. @@ -43,8 +45,8 @@ public class BackupableDB extends RocksDB { } /** - * Captures the state of the database in the latest backup. - * Note that this function is not thread-safe. + *

Captures the state of the database in the latest backup. + * Note that this function is not thread-safe.

* * @param flushBeforeBackup if true, then all data will be flushed * before creating backup. @@ -54,11 +56,12 @@ public class BackupableDB extends RocksDB { */ public void createNewBackup(boolean flushBeforeBackup) throws RocksDBException { + assert(isInitialized()); createNewBackup(nativeHandle_, flushBeforeBackup); } /** - * Deletes old backups, keeping latest numBackupsToKeep alive. + *

Deletes old backups, keeping latest numBackupsToKeep alive.

* * @param numBackupsToKeep Number of latest backups to keep. * @@ -67,11 +70,12 @@ public class BackupableDB extends RocksDB { */ public void purgeOldBackups(int numBackupsToKeep) throws RocksDBException { + assert(isInitialized()); purgeOldBackups(nativeHandle_, numBackupsToKeep); } /** - * Deletes a specific backup. + *

Deletes a specific backup.

* * @param backupId of backup to delete. * @@ -79,16 +83,18 @@ public class BackupableDB extends RocksDB { * native library. */ public void deleteBackup(int backupId) throws RocksDBException { + assert(isInitialized()); deleteBackup0(nativeHandle_, backupId); } /** - * Returns a list of {@link BackupInfo} instances, which describe - * already made backups. + *

Returns a list of {@link BackupInfo} instances, which describe + * already made backups.

* * @return List of {@link BackupInfo} instances. */ public List getBackupInfos() { + assert(isInitialized()); return getBackupInfo(nativeHandle_); } @@ -100,6 +106,7 @@ public class BackupableDB extends RocksDB { * @return list of backup ids as Integer. */ public List getCorruptedBackups() { + assert(isInitialized()); return getCorruptedBackups(nativeHandle_); } @@ -112,15 +119,18 @@ public class BackupableDB extends RocksDB { * native library. */ public void garbageCollect() throws RocksDBException { + assert(isInitialized()); garbageCollect(nativeHandle_); } /** - * Close the BackupableDB instance and release resource. + *

Close the BackupableDB instance and release resource.

* - * 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. + *

Internally, {@link 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()) { @@ -129,8 +139,9 @@ public class BackupableDB extends RocksDB { } /** - * A protected construction that will be used in the static factory - * method {@link #open(Options, BackupableDBOptions, String)}. + *

A protected construction that will be used in the static + * factory method {@link #open(Options, BackupableDBOptions, String)}. + *

*/ protected BackupableDB() { super(); diff --git a/java/org/rocksdb/RestoreBackupableDB.java b/java/org/rocksdb/RestoreBackupableDB.java index 9c41f4345..e7890c278 100644 --- a/java/org/rocksdb/RestoreBackupableDB.java +++ b/java/org/rocksdb/RestoreBackupableDB.java @@ -8,15 +8,17 @@ package org.rocksdb; import java.util.List; /** - * This class is used to access information about backups and restore from them. + *

This class is used to access information about backups and + * restore from them.

* - * Note that dispose() must be called before this instance become out-of-scope - * to release the allocated memory in c++. + *

Note: {@code dispose()} must be called before this instance + * become out-of-scope to release the allocated + * memory in c++.

* */ public class RestoreBackupableDB extends RocksObject { /** - * Constructor + *

Construct new estoreBackupableDB instance.

* * @param options {@link org.rocksdb.BackupableDBOptions} instance */ @@ -26,16 +28,18 @@ public class RestoreBackupableDB extends RocksObject { } /** - * Restore from backup with backup_id - * IMPORTANT -- if options_.share_table_files == true and you restore DB - * from some backup that is not the latest, and you start creating new - * backups from the new DB, they will probably fail. + *

Restore from backup with backup_id.

* - * Example: Let's say you have backups 1, 2, 3, 4, 5 and you restore 3. - * If you add new data to the DB and try creating a new backup now, the - * 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. + *

Important: If options_.share_table_files == true + * and you restore DB from some backup that is not the latest, and you + * start creating new backups from the new DB, they will probably + * fail.

+ * + *

Example: Let's say you have backups 1, 2, 3, 4, 5 + * and you restore 3. If you add new data to the DB and try creating a new + * backup now, the 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 @@ -47,12 +51,13 @@ public class RestoreBackupableDB extends RocksObject { */ public void restoreDBFromBackup(long backupId, String dbDir, String walDir, RestoreOptions restoreOptions) throws RocksDBException { + assert(isInitialized()); restoreDBFromBackup0(nativeHandle_, backupId, dbDir, walDir, restoreOptions.nativeHandle_); } /** - * Restore from the latest backup. + *

Restore from the latest backup.

* * @param dbDir database directory to restore to * @param walDir directory where wal files are located @@ -63,12 +68,13 @@ public class RestoreBackupableDB extends RocksObject { */ public void restoreDBFromLatestBackup(String dbDir, String walDir, RestoreOptions restoreOptions) throws RocksDBException { + assert(isInitialized()); restoreDBFromLatestBackup0(nativeHandle_, dbDir, walDir, restoreOptions.nativeHandle_); } /** - * Deletes old backups, keeping latest numBackupsToKeep alive. + *

Deletes old backups, keeping latest numBackupsToKeep alive.

* * @param numBackupsToKeep of latest backups to keep * @@ -76,11 +82,12 @@ public class RestoreBackupableDB extends RocksObject { * native library. */ public void purgeOldBackups(int numBackupsToKeep) throws RocksDBException { + assert(isInitialized()); purgeOldBackups0(nativeHandle_, numBackupsToKeep); } /** - * Deletes a specific backup. + *

Deletes a specific backup.

* * @param backupId of backup to delete. * @@ -88,16 +95,18 @@ public class RestoreBackupableDB extends RocksObject { * native library. */ public void deleteBackup(int backupId) throws RocksDBException { + assert(isInitialized()); deleteBackup0(nativeHandle_, backupId); } /** - * Returns a list of {@link BackupInfo} instances, which describe - * already made backups. + *

Returns a list of {@link BackupInfo} instances, which describe + * already made backups.

* * @return List of {@link BackupInfo} instances. */ public List getBackupInfos() { + assert(isInitialized()); return getBackupInfo(nativeHandle_); } @@ -109,6 +118,7 @@ public class RestoreBackupableDB extends RocksObject { * @return list of backup ids as Integer. */ public List getCorruptedBackups() { + assert(isInitialized()); return getCorruptedBackups(nativeHandle_); } @@ -121,15 +131,15 @@ public class RestoreBackupableDB extends RocksObject { * native library. */ public void garbageCollect() throws RocksDBException { + assert(isInitialized()); garbageCollect(nativeHandle_); } /** - * Release the memory allocated for the current instance - * in the c++ side. + *

Release the memory allocated for the current instance + * in the c++ side.

*/ @Override public synchronized void disposeInternal() { - assert(isInitialized()); dispose(nativeHandle_); }