andreacavalli/rocksdb
0
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

[RocksJava] Cleanup Backupable implementations

Browse Source 
- Correct usage of isInitialized()
- Adjusted JavaDoc
This commit is contained in:
fyrz 2014-11-16 14:36:22 +01:00
parent fa703efb28
commit d7529b2de9
2 changed files with 58 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
java/org/rocksdb/BackupableDB.java
View File

@ -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();

52
java/org/rocksdb/RestoreBackupableDB.java
View File

@ -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_);
}