ceph/src/rocksdb/java/src/main/java/org/rocksdb/BackupableDB.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>A subclass of RocksDB which supports
  12  * backup-related operations.</p>
  13  *
  14  * @see org.rocksdb.BackupableDBOptions
  15  */
  16 public class BackupableDB extends RocksDB {
  17   /**
  18    * <p>Open a {@code BackupableDB} under the specified path.
  19    * Note that the backup path should be set properly in the
  20    * input BackupableDBOptions.</p>
  21    *
  22    * @param opt {@link org.rocksdb.Options} to set for the database.
  23    * @param bopt {@link org.rocksdb.BackupableDBOptions} to use.
  24    * @param db_path Path to store data to. The path for storing the backup
  25    *   should be specified in the {@link org.rocksdb.BackupableDBOptions}.
  26    *
  27    * @return {@link BackupableDB} reference to the opened database.
  28    *
  29    * @throws RocksDBException thrown if error happens in underlying
  30    *    native library.
  31    */
  32   public static BackupableDB open(
  33       final Options opt, final BackupableDBOptions bopt, final String db_path)
  34       throws RocksDBException {
  35
  36     final RocksDB db = RocksDB.open(opt, db_path);
  37     final BackupableDB bdb = new BackupableDB(open(db.nativeHandle_,
  38         bopt.nativeHandle_));
  39
  40     // Prevent the RocksDB object from attempting to delete
  41     // the underly C++ DB object.
  42     db.disOwnNativeHandle();
  43
  44     return bdb;
  45   }
  46
  47   /**
  48    * <p>Captures the state of the database in the latest backup.
  49    * Note that this function is not thread-safe.</p>
  50    *
  51    * @param flushBeforeBackup if true, then all data will be flushed
  52    *     before creating backup.
  53    *
  54    * @throws RocksDBException thrown if error happens in underlying
  55    *    native library.
  56    */
  57   public void createNewBackup(final boolean flushBeforeBackup)
  58       throws RocksDBException {
  59     assert(isOwningHandle());
  60     createNewBackup(nativeHandle_, flushBeforeBackup);
  61   }
  62
  63   /**
  64    * <p>Deletes old backups, keeping latest numBackupsToKeep alive.</p>
  65    *
  66    * @param numBackupsToKeep Number of latest backups to keep.
  67    *
  68    * @throws RocksDBException thrown if error happens in underlying
  69    *    native library.
  70    */
  71   public void purgeOldBackups(final int numBackupsToKeep)
  72       throws RocksDBException {
  73     assert(isOwningHandle());
  74     purgeOldBackups(nativeHandle_, numBackupsToKeep);
  75   }
  76
  77   /**
  78    * <p>Deletes a specific backup.</p>
  79    *
  80    * @param backupId of backup to delete.
  81    *
  82    * @throws RocksDBException thrown if error happens in underlying
  83    *    native library.
  84    */
  85   public void deleteBackup(final int backupId) throws RocksDBException {
  86     assert(isOwningHandle());
  87     deleteBackup0(nativeHandle_, backupId);
  88   }
  89
  90   /**
  91    * <p>Returns a list of {@link BackupInfo} instances, which describe
  92    * already made backups.</p>
  93    *
  94    * @return List of {@link BackupInfo} instances.
  95    */
  96   public List<BackupInfo> getBackupInfos() {
  97     assert(isOwningHandle());
  98     return getBackupInfo(nativeHandle_);
  99   }
 100
 101   /**
 102    * <p>Returns a list of corrupted backup ids. If there
 103    * is no corrupted backup the method will return an
 104    * empty list.</p>
 105    *
 106    * @return array of backup ids as int ids.
 107    */
 108   public int[] getCorruptedBackups() {
 109     assert(isOwningHandle());
 110     return getCorruptedBackups(nativeHandle_);
 111   }
 112
 113   /**
 114    * <p>Will delete all the files we don't need anymore. It will
 115    * do the full scan of the files/ directory and delete all the
 116    * files that are not referenced.</p>
 117    *
 118    * @throws RocksDBException thrown if error happens in underlying
 119    *    native library.
 120    */
 121   public void garbageCollect() throws RocksDBException {
 122     assert(isOwningHandle());
 123     garbageCollect(nativeHandle_);
 124   }
 125
 126   /**
 127    * <p>Close the BackupableDB instance and release resource.</p>
 128    *
 129    * <p>Internally, {@link BackupableDB} owns the {@code rocksdb::DB}
 130    * pointer to its associated {@link org.rocksdb.RocksDB}.
 131    * The release of that RocksDB pointer is handled in the destructor
 132    * of the c++ {@code rocksdb::BackupableDB} and should be transparent
 133    * to Java developers.</p>
 134    */
 135   @Override public void close() {
 136       super.close();
 137   }
 138
 139   /**
 140    * <p>A protected construction that will be used in the static
 141    * factory method {@link #open(Options, BackupableDBOptions, String)}.
 142    * </p>
 143    *
 144    * @param nativeHandle The native handle of the C++ BackupableDB object
 145    */
 146   protected BackupableDB(final long nativeHandle) {
 147     super(nativeHandle);
 148   }
 149
 150   @Override protected void finalize() throws Throwable {
 151     close();
 152     super.finalize();
 153   }
 154
 155   protected native static long open(final long rocksDBHandle,
 156       final long backupDBOptionsHandle);
 157   protected native void createNewBackup(long handle, boolean flag)
 158       throws RocksDBException;
 159   protected native void purgeOldBackups(long handle, int numBackupsToKeep)
 160       throws RocksDBException;
 161   private native void deleteBackup0(long nativeHandle, int backupId)
 162       throws RocksDBException;
 163   protected native List<BackupInfo> getBackupInfo(long handle);
 164   private native int[] getCorruptedBackups(long handle);
 165   private native void garbageCollect(long handle)
 166       throws RocksDBException;
 167 }