[RocksJava] Cleanup Backupable implementations

- Correct usage of isInitialized()
- Adjusted JavaDoc

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.
+ * <p>A subclass of RocksDB which supports
+ * backup-related operations.</p>
  *
  * @see org.rocksdb.BackupableDBOptions
  */
 public class BackupableDB extends RocksDB {
   /**
-   * Open a {@code BackupableDB} under the specified path.
+   * <p>Open a {@code BackupableDB} under the specified path.
    * Note that the backup path should be set properly in the
-   * input BackupableDBOptions.
+   * input BackupableDBOptions.</p>
    *
    * @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.
+   * <p>Captures the state of the database in the latest backup.
+   * Note that this function is not thread-safe.</p>
    *
    * @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.
+   * <p>Deletes old backups, keeping latest numBackupsToKeep alive.</p>
    *
    * @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.
+   * <p>Deletes a specific backup.</p>
    *
    * @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.
+   * <p>Returns a list of {@link BackupInfo} instances, which describe
+   * already made backups.</p>
    *
    * @return List of {@link BackupInfo} instances.
    */
   public List<BackupInfo> getBackupInfos() {
+    assert(isInitialized());
     return getBackupInfo(nativeHandle_);
   }
 
@@ -100,6 +106,7 @@ public class BackupableDB extends RocksDB {
    * @return list of backup ids as Integer.
    */
   public List<Integer> 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.
+   * <p>Close the BackupableDB instance and release resource.</p>
    *
-   * 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.
+   * <p>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.</p>
    */
   @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)}.
+   * <p>A protected construction that will be used in the static
+   * factory method {@link #open(Options, BackupableDBOptions, String)}.
+   * </p>
    */
   protected BackupableDB() {
     super();

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.
+ * <p>This class is used to access information about backups and
+ * restore from them.</p>
  *
- * Note that dispose() must be called before this instance become out-of-scope
- * to release the allocated memory in c++.
+ * <p>Note: {@code dispose()} must be called before this instance
+ * become out-of-scope to release the allocated
+ * memory in c++.</p>
  *
  */
 public class RestoreBackupableDB extends RocksObject {
   /**
-   * Constructor
+   * <p>Construct new estoreBackupableDB instance.</p>
    *
    * @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.
+   * <p>Restore from backup with backup_id.</p>
    *
-   * 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.
+   * <p><strong>Important</strong>: 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.</p>
+   *
+   * <p><strong>Example</strong>: 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.</p>
    *
    * @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.
+   * <p>Restore from the latest backup.</p>
    *
    * @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.
+   * <p>Deletes old backups, keeping latest numBackupsToKeep alive.</p>
    *
    * @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.
+   * <p>Deletes a specific backup.</p>
    *
    * @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.
+   * <p>Returns a list of {@link BackupInfo} instances, which describe
+   * already made backups.</p>
    *
    * @return List of {@link BackupInfo} instances.
    */
   public List<BackupInfo> getBackupInfos() {
+    assert(isInitialized());
     return getBackupInfo(nativeHandle_);
   }
 
@@ -109,6 +118,7 @@ public class RestoreBackupableDB extends RocksObject {
    * @return list of backup ids as Integer.
    */
   public List<Integer> 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.
+   * <p>Release the memory allocated for the current instance
+   * in the c++ side.</p>
    */
   @Override public synchronized void disposeInternal() {
-    assert(isInitialized());
     dispose(nativeHandle_);
   }