#948 Add getters to BackupManager and allow "use default" to be set

Author: mrotteveel

src/docs/asciidoc/release_notes.adoc

@@ -688,6 +688,7 @@ See also https://github.com/FirebirdSQL/jaybird/blob/master/devdoc/jdp/jdp-2026-
 * Improvement: Clear warnings on connection close (https://github.com/FirebirdSQL/jaybird/pull/943[#943])
 +
 This change was contributed by https://github.com/FuriousFourier[FuriousFourier^]
+* Improvement: Add getters to BackupManager and allow "`use default`" to be set (https://github.com/FirebirdSQL/jaybird/issues/948[#948])
 * ...
 
 [#compatibility-changes]

src/main/org/firebirdsql/management/BackupManager.java

@@ -17,7 +17,9 @@
  *
  * @author Roman Rokytskyy
  * @author Steven Jardine
+ * @author Mark Rotteveel
  */
+@SuppressWarnings("unused")
 public interface BackupManager extends ServiceManager {
 
     /**
@@ -86,7 +88,6 @@ public interface BackupManager extends ServiceManager {
      */
     int RESTORE_USE_ALL_SPACE = ISCConstants.isc_spb_res_use_all_space;
 
-
     /**
      * Sets the location of the backup file. This method is used to set the
      * path to the backup consisting of a single file. It is not possible to
@@ -200,49 +201,88 @@ public interface BackupManager extends ServiceManager {
      * Set whether the operations of this {@code BackupManager} will result in verbose logging to the configured logger.
      *
      * @param verbose
-     *         If {@code true}, operations will be logged verbosely, otherwise they will not be logged verbosely
+     *         {@code true}, operations will be logged verbosely, otherwise they will not be logged verbosely
+     * @see #isVerbose()
      */
     void setVerbose(boolean verbose);
 
     /**
-     * Set the default number of pages to be buffered (cached) by default in a
-     * restored database.
+     * @return {@code true}, operations will be logged verbosely, otherwise they will not be logged verbosely
+     * @see #setVerbose(boolean)
+     * @since 7
+     */
+    boolean isVerbose();
+
+    /**
+     * Set the default number of pages to be buffered (cached) by default in a restored database.
      *
      * @param bufferCount
-     *         The page-buffer size to be used, a positive value
+     *         page-buffer size to be used, a positive value, or {@code -1} for the value recorded in the backup
+     * @see #getRestorePageBufferCount()
      */
     void setRestorePageBufferCount(int bufferCount);
 
     /**
-     * Set the page size that will be used for a restored database. The value for {@code pageSize} must be one
-     * of: 1024, 2048, 4096, 8192 or 16384. The default value depends on the Firebird version.
+     * @return page-buffer size to be used, or {@code -1} for the value recorded in the backup
+     * @see #setRestorePageBufferCount(int)
+     * @since 7
+     */
+    int getRestorePageBufferCount();
+
+    /**
+     * Set the page size that will be used for a restored database. The value for {@code pageSize} must be
+     * one of {@link PageSizeConstants}. Use {@link PageSizeConstants#USE_DEFAULT} ({@code -1}) for the value recorded
+     * in the backup.
+     * <p>
+     * Be aware that not all page sizes are supported by all Firebird versions.
+     * </p>
      *
      * @param pageSize
-     *         The page size to be used in a restored database, one of 1024, 2048, 4196, 8192 or 16384
+     *         page size to be used in a restored database, see {@link PageSizeConstants}
+     * @see #getRestorePageSize()
      * @see PageSizeConstants
      */
     void setRestorePageSize(int pageSize);
 
     /**
-     * Set the restore operation to create a new database, as opposed to
-     * overwriting an existing database.
+     * @return page size to be used, or {@code -1} for the value recorded in the backup
+     * @see #setRestorePageSize(int)
+     * @since 7
+     */
+    int getRestorePageSize();
+
+    /**
+     * Set the restore operation to create a new database, as opposed to overwriting an existing database.
      *
      * @param replace
-     *         If {@code true}, the restore operation will attempt to create a new database if it does not exit or
-     *         overwrite an existing one when it exists, {@code false} when restore should fail if database already
-     *         exist (if it doesn't, a database will be successfully created).
+     *         {@code true} drop existing database and overwrite, {@code false} fail if database exists
+     * @see #isRestoreReplace()
      */
     void setRestoreReplace(boolean replace);
 
+    /**
+     * @return {@code true} drop existing database and overwrite, {@code false} fail if database exists
+     * @see #setRestoreReplace(boolean)
+     * @since 7
+     */
+    boolean isRestoreReplace();
+
     /**
      * Set the read-only attribute on a restored database.
      *
      * @param readOnly
-     *         If {@code true}, a restored database will be
-     *         read-only, otherwise it will be read-write.
+     *         {@code true} restored database is marked read-only, otherwise it will be read-write
+     * @see #isRestoreReadOnly()
      */
     void setRestoreReadOnly(boolean readOnly);
 
+    /**
+     * @return {@code true} restored database is marked read-only, otherwise it will be read-write
+     * @see #setRestoreReadOnly(boolean)
+     * @since 7
+     */
+    boolean isRestoreReadOnly();
+
     /**
      * SQL regular expression for the tables to exclude from the backup or restore.
      * <p>

src/main/org/firebirdsql/management/FBBackupManagerBase.java

@@ -24,7 +24,7 @@
 import static org.firebirdsql.util.FirebirdSupportInfo.supportInfoFor;
 
 /**
- * Implements the common functionality between regular and streaming backup/restore
+ * Implements the common functionality between regular and streaming backup/restore.
  *
  * @author Roman Rokytskyy
  * @author Mark Rotteveel
@@ -79,8 +79,8 @@ public String toString() {
 
     protected boolean verbose;
 
-    private int restoreBufferCount = -1;
-    private int restorePageSize = -1;
+    private int restorePageBufferCount = -1;
+    private int restorePageSize = PageSizeConstants.USE_DEFAULT;
     private boolean restoreReadOnly;
     private boolean restoreReplace;
     private @Nullable String skipData;
@@ -92,13 +92,13 @@ public String toString() {
     private static final int RESTORE_CREATE = isc_spb_res_create;
 
     /**
-     * Create a new instance of <code>FBBackupManagerBase</code> based on the default GDSType.
+     * Create a new instance of {@code FBBackupManagerBase} based on the default GDSType.
      */
     protected FBBackupManagerBase() {
     }
 
     /**
-     * Create a new instance of <code>FBBackupManagerBase</code> based on a given GDSType.
+     * Create a new instance of {@code FBBackupManagerBase} based on a given GDSType.
      *
      * @param gdsType
      *         type must be PURE_JAVA, EMBEDDED, or NATIVE
@@ -108,7 +108,7 @@ protected FBBackupManagerBase(String gdsType) {
     }
 
     /**
-     * Create a new instance of <code>FBBackupManagerBase</code> based on a given GDSType.
+     * Create a new instance of {@code FBBackupManagerBase} based on a given GDSType.
      *
      * @param gdsType
      *         type must be PURE_JAVA, EMBEDDED, or NATIVE
@@ -208,71 +208,61 @@ public void restoreDatabase() throws SQLException {
         restoreDatabase(0);
     }
 
-    /**
-     * Set whether the operations of this {@code BackupManager} will result in verbose logging to the configured logger.
-     *
-     * @param verbose
-     *         If <code>true</code>, operations will be logged verbosely, otherwise they will not be logged verbosely
-     */
     @Override
     public void setVerbose(boolean verbose) {
         this.verbose = verbose;
     }
 
-    /**
-     * Set the default number of pages to be buffered (cached) by default in a restored database.
-     *
-     * @param bufferCount
-     *         The page-buffer size to be used, a positive value
-     */
+    @Override
+    public boolean isVerbose() {
+        return verbose;
+    }
+
     @Override
     public void setRestorePageBufferCount(int bufferCount) {
-        if (bufferCount < 0) {
-            throw new IllegalArgumentException("Buffer count must be positive");
+        if (bufferCount < -1) {
+            throw new IllegalArgumentException("Buffer count must be positive or -1");
         }
-        this.restoreBufferCount = bufferCount;
+        this.restorePageBufferCount = bufferCount;
+    }
+
+    @Override
+    public int getRestorePageBufferCount() {
+        return restorePageBufferCount;
     }
 
-    /**
-     * Set the page size that will be used for a restored database. The value for {@code pageSize} must be
-     * one of {@link PageSizeConstants}. The default value depends on the Firebird version.
-     * <p>
-     * Be aware that not all page sizes are supported by all Firebird versions.
-     * </p>
-     *
-     * @param pageSize
-     *         The page size to be used in a restored database, see {@link PageSizeConstants}
-     * @see PageSizeConstants
-     */
     @Override
     public void setRestorePageSize(int pageSize) {
-        this.restorePageSize = PageSizeConstants.requireValidPageSize(pageSize);
+        this.restorePageSize = pageSize != PageSizeConstants.USE_DEFAULT
+                ? PageSizeConstants.requireValidPageSize(pageSize)
+                : PageSizeConstants.USE_DEFAULT;
+    }
+
+    @Override
+    public int getRestorePageSize() {
+        return restorePageSize;
     }
 
-    /**
-     * Set the restore operation to create a new database, as opposed to overwriting an existing database. This is true
-     * by default.
-     *
-     * @param replace
-     *         If <code>true</code>, the restore operation will attempt to create a new database, otherwise the restore
-     *         operation will overwrite an existing database
-     */
     @Override
     public void setRestoreReplace(boolean replace) {
         this.restoreReplace = replace;
     }
 
-    /**
-     * Set the read-only attribute on a restored database.
-     *
-     * @param readOnly
-     *         If <code>true</code>, a restored database will be read-only, otherwise it will be read-write.
-     */
+    @Override
+    public boolean isRestoreReplace() {
+        return restoreReplace;
+    }
+
     @Override
     public void setRestoreReadOnly(boolean readOnly) {
         this.restoreReadOnly = readOnly;
     }
 
+    @Override
+    public boolean isRestoreReadOnly() {
+        return restoreReadOnly;
+    }
+
     @Override
     public void setSkipData(@Nullable String skipData) {
         this.skipData = skipData;
@@ -342,8 +332,8 @@ protected ServiceRequestBuffer getRestoreSRB(FbService service, int options) thr
 
         addBackupsToRestoreRequestBuffer(service, restoreSPB);
 
-        if (restoreBufferCount != -1) {
-            restoreSPB.addArgument(isc_spb_res_buffers, restoreBufferCount);
+        if (restorePageBufferCount != -1) {
+            restoreSPB.addArgument(isc_spb_res_buffers, restorePageBufferCount);
         }
 
         if (restorePageSize != -1) {

src/main/org/firebirdsql/management/FBStreamingBackupManager.java

@@ -46,7 +46,8 @@ public class FBStreamingBackupManager extends FBBackupManagerBase implements Bac
      * </p>
      *
      * @param bufferSize
-     *        The buffer size to be used, a positive value
+     *        buffer size to be used, a positive value
+     * @see #getBackupBufferSize()
      */
     public void setBackupBufferSize(int bufferSize) {
         if (bufferSize <= 0) {
@@ -55,6 +56,15 @@ public void setBackupBufferSize(int bufferSize) {
         this.backupBufferSize = bufferSize;
     }
 
+    /**
+     * @return buffer size to be used for backup
+     * @see #setBackupBufferSize(int)
+     * @since 7
+     */
+    public int getBackupBufferSize() {
+        return backupBufferSize;
+    }
+
     /**
      * Create a new instance of <code>FBStreamingBackupManager</code> based on
      * the default GDSType.
@@ -154,7 +164,7 @@ protected boolean verboseBackup() {
      */
     @Override
     public void setRestorePageSize(int pageSize) {
-        if (pageSize < PageSizeConstants.SIZE_4K) {
+        if (pageSize != PageSizeConstants.USE_DEFAULT && pageSize < PageSizeConstants.SIZE_4K) {
             throw new IllegalArgumentException(
                     "FirebirdSQL versions with streaming restore support don't support pages below 4096");
         }

src/main/org/firebirdsql/management/PageSizeConstants.java

@@ -13,10 +13,22 @@
  * @author Mark Rotteveel
  * @since 3.0
  */
-@SuppressWarnings("unused")
+@SuppressWarnings({ "unused", "DeprecatedIsStillUsed" })
 public final class PageSizeConstants {
 
+    /**
+     * Value to signal use of a (server determined) default value.
+     */
+    public static final int USE_DEFAULT = -1;
+    /**
+     * @deprecated deprecated in Firebird 2.1, and not supported in Firebird 2.5 and higher
+     */
+    @Deprecated
     public static final int SIZE_1K = 1024;
+    /**
+     * @deprecated deprecated in Firebird 2.1, and not supported in Firebird 2.5 and higher
+     */
+    @Deprecated
     public static final int SIZE_2K = 2 * SIZE_1K;
     public static final int SIZE_4K = 4 * SIZE_1K;
     public static final int SIZE_8K = 8 * SIZE_1K;
@@ -38,6 +50,9 @@ private PageSizeConstants() {
      * Actual support of a page size depends on the Firebird version, even if a page size is valid according to this
      * method, it can still be invalid for the actual Firebird version used.
      * </p>
+     * <p>
+     * This method does not consider {@link #USE_DEFAULT} ({@code -1}) a valid page size.
+     * </p>
      *
      * @param pageSize
      *         Page size to check