ceph/src/rocksdb/java/src/main/java/org/rocksdb/RestoreBackupableDB.java

   1 // Copyright (c) 2011-present, Facebook, Inc.  All rights reserved.
   2 // This source code is licensed under the BSD-style license found in the
   3 // LICENSE file in the root directory of this source tree. An additional grant
   4 // of patent rights can be found in the PATENTS file in the same directory.
   5
   6 package org.rocksdb;
   7
   8 import java.util.List;
   9
  10 /**
  11  * <p>This class is used to access information about backups and
  12  * restore from them.</p>
  13  *
  14  * <p>Note: {@code dispose()} must be called before this instance
  15  * become out-of-scope to release the allocated
  16  * memory in c++.</p>
  17  *
  18  */
  19 public class RestoreBackupableDB extends RocksObject {
  20   /**
  21    * <p>Construct new estoreBackupableDB instance.</p>
  22    *
  23    * @param options {@link org.rocksdb.BackupableDBOptions} instance
  24    */
  25   public RestoreBackupableDB(final BackupableDBOptions options) {
  26     super(newRestoreBackupableDB(options.nativeHandle_));
  27   }
  28
  29   /**
  30    * <p>Restore from backup with backup_id.</p>
  31    *
  32    * <p><strong>Important</strong>: If options_.share_table_files == true
  33    * and you restore DB from some backup that is not the latest, and you
  34    * start creating new backups from the new DB, they will probably
  35    * fail.</p>
  36    *
  37    * <p><strong>Example</strong>: Let's say you have backups 1, 2, 3, 4, 5
  38    * and you restore 3. If you add new data to the DB and try creating a new
  39    * backup now, the database will diverge from backups 4 and 5 and the new
  40    * backup will fail. If you want to create new backup, you will first have
  41    * to delete backups 4 and 5.</p>
  42    *
  43    * @param backupId id pointing to backup
  44    * @param dbDir database directory to restore to
  45    * @param walDir directory where wal files are located
  46    * @param restoreOptions {@link org.rocksdb.RestoreOptions} instance.
  47    *
  48    * @throws RocksDBException thrown if error happens in underlying
  49    *    native library.
  50    */
  51   public void restoreDBFromBackup(final long backupId, final String dbDir,
  52       final String walDir, final RestoreOptions restoreOptions)
  53       throws RocksDBException {
  54     assert(isOwningHandle());
  55     restoreDBFromBackup0(nativeHandle_, backupId, dbDir, walDir,
  56         restoreOptions.nativeHandle_);
  57   }
  58
  59   /**
  60    * <p>Restore from the latest backup.</p>
  61    *
  62    * @param dbDir database directory to restore to
  63    * @param walDir directory where wal files are located
  64    * @param restoreOptions {@link org.rocksdb.RestoreOptions} instance
  65    *
  66    * @throws RocksDBException thrown if error happens in underlying
  67    *    native library.
  68    */
  69   public void restoreDBFromLatestBackup(final String dbDir,
  70       final String walDir, final RestoreOptions restoreOptions)
  71       throws RocksDBException {
  72     assert(isOwningHandle());
  73     restoreDBFromLatestBackup0(nativeHandle_, dbDir, walDir,
  74         restoreOptions.nativeHandle_);
  75   }
  76
  77   /**
  78    * <p>Deletes old backups, keeping latest numBackupsToKeep alive.</p>
  79    *
  80    * @param numBackupsToKeep of latest backups to keep
  81    *
  82    * @throws RocksDBException thrown if error happens in underlying
  83    *    native library.
  84    */
  85   public void purgeOldBackups(final int numBackupsToKeep)
  86       throws RocksDBException {
  87     assert(isOwningHandle());
  88     purgeOldBackups0(nativeHandle_, numBackupsToKeep);
  89   }
  90
  91   /**
  92    * <p>Deletes a specific backup.</p>
  93    *
  94    * @param backupId of backup to delete.
  95    *
  96    * @throws RocksDBException thrown if error happens in underlying
  97    *    native library.
  98    */
  99   public void deleteBackup(final int backupId)
 100       throws RocksDBException {
 101     assert(isOwningHandle());
 102     deleteBackup0(nativeHandle_, backupId);
 103   }
 104
 105   /**
 106    * <p>Returns a list of {@link BackupInfo} instances, which describe
 107    * already made backups.</p>
 108    *
 109    * @return List of {@link BackupInfo} instances.
 110    */
 111   public List<BackupInfo> getBackupInfos() {
 112     assert(isOwningHandle());
 113     return getBackupInfo(nativeHandle_);
 114   }
 115
 116   /**
 117    * <p>Returns a list of corrupted backup ids. If there
 118    * is no corrupted backup the method will return an
 119    * empty list.</p>
 120    *
 121    * @return array of backup ids as int ids.
 122    */
 123   public int[] getCorruptedBackups() {
 124     assert(isOwningHandle());
 125     return getCorruptedBackups(nativeHandle_);
 126   }
 127
 128   /**
 129    * <p>Will delete all the files we don't need anymore. It will
 130    * do the full scan of the files/ directory and delete all the
 131    * files that are not referenced.</p>
 132    *
 133    * @throws RocksDBException thrown if error happens in underlying
 134    *    native library.
 135    */
 136   public void garbageCollect() throws RocksDBException {
 137     assert(isOwningHandle());
 138     garbageCollect(nativeHandle_);
 139   }
 140
 141   private native static long newRestoreBackupableDB(final long options);
 142   private native void restoreDBFromBackup0(long nativeHandle, long backupId,
 143       String dbDir, String walDir, long restoreOptions)
 144       throws RocksDBException;
 145   private native void restoreDBFromLatestBackup0(long nativeHandle,
 146       String dbDir, String walDir, long restoreOptions)
 147       throws RocksDBException;
 148   private native void purgeOldBackups0(long nativeHandle, int numBackupsToKeep)
 149       throws RocksDBException;
 150   private native void deleteBackup0(long nativeHandle, int backupId)
 151       throws RocksDBException;
 152   private native List<BackupInfo> getBackupInfo(long handle);
 153   private native int[] getCorruptedBackups(long handle);
 154   private native void garbageCollect(long handle)
 155       throws RocksDBException;
 156   @Override protected final native void disposeInternal(
 157       final long nativeHandle);
 158 }