Package org.firebirdsql.management

## Class FBMaintenanceManager

- java.lang.Object
- - org.firebirdsql.management.FBServiceManager
  - - org.firebirdsql.management.FBMaintenanceManager

- All Implemented Interfaces:
    `AttachmentProperties`, `BaseProperties`, `ServiceConnectionProperties`, `MaintenanceManager`, `ServiceManager`

      public class FBMaintenanceManager
      extends FBServiceManager
      implements MaintenanceManager

  The `FBMaintenanceManager` class is responsible for replicating the functionality provided by the `gfix` command-line tool.

  Among the responsibilities of this class are:

  - Database shutdown
  - Extended database shutdown/online modes new with Firebird 2.5
  - Changing database mode to read-only or read-write
  - Enabling or disabling forced writes in the database
  - Changing the dialect of the database
  - Setting the cache size at database-level
  - Mending databases and making minor repairs
  - Sweeping databases
  - Activating and killing shadow files
  - Displaying, committing, or recovering limbo transactions
  Author:
    Gabriel Reid, Thomas Steinmaurer, Mark Rotteveel

- - ### Field Summary

    - ### Fields inherited from class org.firebirdsql.management.FBServiceManager

      `BUFFER_SIZE`

    - ### Fields inherited from interface org.firebirdsql.management.MaintenanceManager

      `ACCESS_MODE_READ_ONLY, ACCESS_MODE_READ_WRITE, OPERATION_MODE_FULL_SHUTDOWN, OPERATION_MODE_MULTI, OPERATION_MODE_NORMAL, OPERATION_MODE_SINGLE, PAGE_FILL_FULL, PAGE_FILL_RESERVE, SHUTDOWN_ATTACH, SHUTDOWN_FORCE, SHUTDOWN_TRANSACTIONAL, SHUTDOWNEX_ATTACHMENTS, SHUTDOWNEX_FORCE, SHUTDOWNEX_TRANSACTIONS, VALIDATE_FULL, VALIDATE_IGNORE_CHECKSUM, VALIDATE_READ_ONLY`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `FBMaintenanceManager()` | Create a new instance of `FBMaintenanceManager` based on the default GDSType.
    `FBMaintenanceManager​(java.lang.String gdsType)` | Create a new instance of `FBMaintenanceManager` based on a given GDSType.
    `FBMaintenanceManager​(GDSType gdsType)` | Create a new instance of `FBMaintenanceManager` based on a given GDSType.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `activateShadowFile()` | Activate a database shadow file to be used as the actual database.
    `void` | `bringDatabaseOnline()` | Bring a shutdown database online.
    `void` | `bringDatabaseOnline​(byte operationMode)` | Bring a shutdown database online with enhanced operation modes (FB 2.5 or higher).
    `void` | `commitTransaction​(long transactionId)` | Commit a limbo transaction based on its ID.
    `long[]` | `getLimboTransactions()` | Retrieve the ID of each limbo transaction as an array of longs.
    `void` | `killUnavailableShadows()` | Remove references to unavailable shadow files.
    `java.util.List<java.lang.Long>` | `limboTransactionsAsList()` | Retrieve the ID of each limbo transaction as a List of Long objects.
    `void` | `markCorruptRecords()` | Mark corrupt records in the database as unavailable.
    `void` | `rollbackTransaction​(long transactionId)` | Rollback a limbo transaction based on its ID.
    `void` | `setDatabaseAccessMode​(int mode)` | Set the database to have read-write or read-only access.
    `void` | `setDatabaseDialect​(int dialect)` | Set the database's dialect.
    `void` | `setDefaultCacheBuffer​(int pageCount)` | Set the default page-buffer count to be cached in the database.
    `void` | `setForcedWrites​(boolean forced)` | Enable or disable forced (synchronous) writes in the database.
    `void` | `setPageFill​(int pageFill)` | Set the page fill strategy for when inserting records.
    `void` | `setSweepThreshold​(int transactions)` | Set the database automatic sweep interval to a given number of transactions.
    `void` | `shutdownDatabase​(byte operationMode, int shutdownModeEx, int timeout)` | Shutdown the current database with enhanced modes (FB 2.5 or higher).
    `void` | `shutdownDatabase​(int shutdownMode, int timeout)` | Shutdown the current database.
    `void` | `sweepDatabase()` | Perform an immediate sweep of the database.
    `void` | `validateDatabase()` | Locate and release database pages that are allocated but unassigned to any data structures.
    `void` | `validateDatabase​(int options)` | Locate and release database pages that are allocated but unassigned to any data structures.

    - ### Methods inherited from class org.firebirdsql.management.FBServiceManager

      `attachDatabase, attachServiceManager, connectionPropertyValues, createRequestBuffer, executeServicesOperation, executeServicesOperation, getAuthPlugins, getBooleanProperty, getCharSet, getDatabase, getDbCryptConfig, getExpectedDb, getHost, getIntProperty, getLogger, getPassword, getPort, getPortNumber, getProperty, getServerName, getServerVersion, getServiceName, getUser, getWireCrypt, getWireCryptAsEnum, isWireCompression, queueService, setAuthPlugins, setBooleanProperty, setCharSet, setDatabase, setDbCryptConfig, setExpectedDb, setHost, setIntProperty, setLogger, setPassword, setPort, setPortNumber, setProperty, setServerName, setServiceName, setType, setUser, setWireCompression, setWireCryptAsEnum`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface org.firebirdsql.jaybird.props.AttachmentProperties

      `getAuthPlugins, getCharSet, getConnectTimeout, getDbCryptConfig, getEncoding, getPassword, getPortNumber, getProcessId, getProcessName, getRoleName, getServerName, getSocketBufferSize, getSoTimeout, getType, getUser, getWireCrypt, isWireCompression, setAuthPlugins, setCharSet, setConnectTimeout, setDbCryptConfig, setEncoding, setPassword, setPortNumber, setProcessId, setProcessName, setRoleName, setServerName, setSocketBufferSize, setSoTimeout, setType, setUser, setWireCompression, setWireCrypt`

    - ### Methods inherited from interface org.firebirdsql.jaybird.props.BaseProperties

      `connectionPropertyValues, getBooleanProperty, getBooleanProperty, getIntProperty, getIntProperty, getProperty, getProperty, setBooleanProperty, setIntProperty, setProperty`

    - ### Methods inherited from interface org.firebirdsql.jaybird.props.ServiceConnectionProperties

      `getExpectedDb, getServiceName, setExpectedDb, setServiceName`

    - ### Methods inherited from interface org.firebirdsql.management.ServiceManager

      `getDatabase, getHost, getLogger, getPort, getServerVersion, getWireCryptAsEnum, setDatabase, setHost, setLogger, setPort, setWireCryptAsEnum`

- - ### Constructor Detail

    - #### FBMaintenanceManager

          public FBMaintenanceManager()

      Create a new instance of `FBMaintenanceManager` based on the default GDSType.

    - #### FBMaintenanceManager

          public FBMaintenanceManager​(java.lang.String gdsType)

      Create a new instance of `FBMaintenanceManager` based on a given GDSType.
      Parameters:
        `gdsType` - type must be PURE_JAVA, EMBEDDED, or NATIVE

    - #### FBMaintenanceManager

          public FBMaintenanceManager​(GDSType gdsType)

      Create a new instance of `FBMaintenanceManager` based on a given GDSType.
      Parameters:
        `gdsType` - The GDS implementation type to use

  - ### Method Detail

    - #### setDatabaseAccessMode

          public void setDatabaseAccessMode​(int mode)
                                     throws java.sql.SQLException

      Description copied from interface: `MaintenanceManager`
      Set the database to have read-write or read-only access.
      Specified by:
        `setDatabaseAccessMode` in interface `MaintenanceManager`
      Parameters:
        `mode` - Must be either `ACCESS_MODE_READ_WRITE` or `ACCESS_MODE_READ_ONLY`
      Throws:
        `java.sql.SQLException` - if a database access error occurs

    - #### setDatabaseDialect

          public void setDatabaseDialect​(int dialect)
                                  throws java.sql.SQLException

      Description copied from interface: `MaintenanceManager`
      Set the database's dialect.
      Specified by:
        `setDatabaseDialect` in interface `MaintenanceManager`
      Parameters:
        `dialect` - The database dialect, must be either 1 or 3
      Throws:
        `java.sql.SQLException` - if a database access error occurs

    - #### setDefaultCacheBuffer

          public void setDefaultCacheBuffer​(int pageCount)
                                     throws java.sql.SQLException

      Description copied from interface: `MaintenanceManager`
      Set the default page-buffer count to be cached in the database.
      Specified by:
        `setDefaultCacheBuffer` in interface `MaintenanceManager`
      Parameters:
        `pageCount` - The number of pages to be cached, must be a positive
      Throws:
        `java.sql.SQLException` - If the given page count cannot be set, or a database access error occurs

    - #### setForcedWrites

          public void setForcedWrites​(boolean forced)
                               throws java.sql.SQLException

      Description copied from interface: `MaintenanceManager`
      Enable or disable forced (synchronous) writes in the database.

      Note, it is considered to be a very bad idea to disable forced writes on Windows platforms.

      Specified by:
        `setForcedWrites` in interface `MaintenanceManager`
      Parameters:
        `forced` - If `true`, forced writes will be used in the database, otherwise buffered writes will be used.
      Throws:
        `java.sql.SQLException` - if a database access error occurs

    - #### setPageFill

          public void setPageFill​(int pageFill)
                           throws java.sql.SQLException

      Description copied from interface: `MaintenanceManager`
      Set the page fill strategy for when inserting records.

      `pageFill` can be one of:

      - `PAGE_FILL_FULL` Fully fill database pages
      - `PAGE_FILL_RESERVE` Reserve 20% of page space for later record deltas
      Specified by:
        `setPageFill` in interface `MaintenanceManager`
      Parameters:
        `pageFill` - The page-filling strategy, either `PAGE_FILL_FULL` or `PAGE_FILL_RESERVE`
      Throws:
        `java.sql.SQLException` - if a database access error occurs

    - #### shutdownDatabase

          public void shutdownDatabase​(int shutdownMode,
                                       int timeout)
                                throws java.sql.SQLException

      Description copied from interface: `MaintenanceManager`
      Shutdown the current database.

      Shutdown can be done in three modes:

      - `SHUTDOWN_ATTACH` - No new non-owner connections will be allowed to the database during the shutdown, and shutdown is cancelled if there are still processes connected at the end of the timeout.
      - `SHUTDOWN_TRANSACTIONAL` - No new transactions can be started during the timeout period, and shutdown is cancelled if there are still active transactions at the end of the timeout.
      - `SHUTDOWN_FORCE` - Forcefully shuts down the database at the end of the timeout.
      Specified by:
        `shutdownDatabase` in interface `MaintenanceManager`
      Parameters:
        `shutdownMode` - One of `SHUTDOWN_ATTACH`, `SHUTDOWN_TRANSACTIONAL`, or `SHUTDOWN_FORCE`.
        `timeout` - The maximum amount of time allocated for the operation, in seconds
      Throws:
        `java.sql.SQLException` - if the requested operation cannot be completed within the given timeout, or a database access error occurs

    - #### shutdownDatabase

          public void shutdownDatabase​(byte operationMode,
                                       int shutdownModeEx,
                                       int timeout)
                                throws java.sql.SQLException

      Description copied from interface: `MaintenanceManager`
      Shutdown the current database with enhanced modes (FB 2.5 or higher).

      There are three operation modes for shutdown available:

      - `OPERATION_MODE_MULTI` - Multi-user maintenance. Unlimited SYSDBA/database owner connections are allowed.
      - `OPERATION_MODE_SINGLE` - Single-user maintenance. Only one SYSDBA/database owner connection is allowed.
      - `OPERATION_MODE_FULL_SHUTDOWN` - Full shutdown. Full exclusive shutdown. No connections are allowed.

      There are three extended shutdown modes for shutdown available:

      - `SHUTDOWNEX_FORCE` - Force shutdown.
      - `SHUTDOWNEX_ATTACHMENTS` - Shutdown attachments.
      - `SHUTDOWNEX_TRANSACTIONS` - Shutdown transactions.
      Specified by:
        `shutdownDatabase` in interface `MaintenanceManager`
      Parameters:
        `operationMode` - one of `OPERATION_MODE_*` operation modes listed above
        `shutdownModeEx` - one of `SHUTDOWNEX_*` extended shutdown modes listed above
        `timeout` - The maximum amount of time allocated for the operation, in seconds. 0 = immediately.
      Throws:
        `java.sql.SQLException` - if the requested operation cannot be completed within the given timeout, or a database access error occurs

    - #### bringDatabaseOnline

          public void bringDatabaseOnline()
                                   throws java.sql.SQLException

      Description copied from interface: `MaintenanceManager`
      Bring a shutdown database online.
      Specified by:
        `bringDatabaseOnline` in interface `MaintenanceManager`
      Throws:
        `java.sql.SQLException` - if a database access error occurs

    - #### bringDatabaseOnline

          public void bringDatabaseOnline​(byte operationMode)
                                   throws java.sql.SQLException

      Description copied from interface: `MaintenanceManager`
      Bring a shutdown database online with enhanced operation modes (FB 2.5 or higher).

      There are three operation modes for bringing a database online available:

      - `OPERATION_MODE_NORMAL` - Normal operation modes.
      - `OPERATION_MODE_MULTI` - Multi-user maintenance. Unlimited SYSDBA/database owner connections are allowed.
      - `OPERATION_MODE_SINGLE` - Single-user maintenance. Only one SYSDBA/database owner connection is allowed.
      Specified by:
        `bringDatabaseOnline` in interface `MaintenanceManager`
      Throws:
        `java.sql.SQLException` - if a database access error occurs

    - #### markCorruptRecords

          public void markCorruptRecords()
                                  throws java.sql.SQLException

      Description copied from interface: `MaintenanceManager`
      Mark corrupt records in the database as unavailable.

      This operation ensures that the corrupt records are skipped (for example, during a subsequent backup).

      Specified by:
        `markCorruptRecords` in interface `MaintenanceManager`
      Throws:
        `java.sql.SQLException` - if a database access error occurs

    - #### validateDatabase

          public void validateDatabase()
                                throws java.sql.SQLException

      Description copied from interface: `MaintenanceManager`
      Locate and release database pages that are allocated but unassigned to any data structures. This method also reports corrupt structures.
      Specified by:
        `validateDatabase` in interface `MaintenanceManager`
      Throws:
        `java.sql.SQLException` - if a database access error occurs

    - #### validateDatabase

          public void validateDatabase​(int options)
                                throws java.sql.SQLException

      Description copied from interface: `MaintenanceManager`
      Locate and release database pages that are allocated but unassigned to any data structures. This method also reports corrupt structures.

      The value supplied for `options` must be one of the following:

      - 0 - Simple validation
      - `VALIDATE_READ_ONLY` - read-only validation, no repair
      - `VALIDATE_FULL` - full validation and repair

      The value for `options` can additionally be combined in a bitmask with `VALIDATE_IGNORE_CHECKSUM` to ignore checksums while performing validation.

      Specified by:
        `validateDatabase` in interface `MaintenanceManager`
      Parameters:
        `options` - Either 0, `VALIDATE_READ_ONLY`, or `VALIDATE_FULL`
      Throws:
        `java.sql.SQLException` - if a database access error occurs

    - #### setSweepThreshold

          public void setSweepThreshold​(int transactions)
                                 throws java.sql.SQLException

      Description copied from interface: `MaintenanceManager`
      Set the database automatic sweep interval to a given number of transactions.

      The Firebird default value is 20,000. If `transactions` is 0, automatic sweeping is disabled.

      Specified by:
        `setSweepThreshold` in interface `MaintenanceManager`
      Parameters:
        `transactions` - The interval of transactions between automatic sweeps of the database. Can be set to 0, which disables automatic sweeping of the database.
      Throws:
        `java.sql.SQLException` - if a database access error occurs

    - #### sweepDatabase

          public void sweepDatabase()
                             throws java.sql.SQLException

      Description copied from interface: `MaintenanceManager`
      Perform an immediate sweep of the database.
      Specified by:
        `sweepDatabase` in interface `MaintenanceManager`
      Throws:
        `java.sql.SQLException` - if a database access error occurs

    - #### activateShadowFile

          public void activateShadowFile()
                                  throws java.sql.SQLException

      Description copied from interface: `MaintenanceManager`
      Activate a database shadow file to be used as the actual database.

      This method is the equivalent of `gfix -activate`.

      Specified by:
        `activateShadowFile` in interface `MaintenanceManager`
      Throws:
        `java.sql.SQLException` - if a database access error occurs

    - #### killUnavailableShadows

          public void killUnavailableShadows()
                                      throws java.sql.SQLException

      Description copied from interface: `MaintenanceManager`
      Remove references to unavailable shadow files.

      This method is the equivalent of `gfix -kill`.

      Specified by:
        `killUnavailableShadows` in interface `MaintenanceManager`
      Throws:
        `java.sql.SQLException` - if a database access error occurs

    - #### limboTransactionsAsList

          public java.util.List<java.lang.Long> limboTransactionsAsList()
                                                                 throws java.sql.SQLException

      Description copied from interface: `MaintenanceManager`
      Retrieve the ID of each limbo transaction as a List of Long objects.
      Specified by:
        `limboTransactionsAsList` in interface `MaintenanceManager`
      Throws:
        `java.sql.SQLException` - if a database access error occurs

    - #### getLimboTransactions

          public long[] getLimboTransactions()
                                      throws java.sql.SQLException

      Description copied from interface: `MaintenanceManager`
      Retrieve the ID of each limbo transaction as an array of longs.

      In Firebird 3, transactions are (unsigned) 48 bit longs.

      Specified by:
        `getLimboTransactions` in interface `MaintenanceManager`
      Throws:
        `java.sql.SQLException` - if a database access error occurs

    - #### commitTransaction

          public void commitTransaction​(long transactionId)
                                 throws java.sql.SQLException

      Description copied from interface: `MaintenanceManager`
      Commit a limbo transaction based on its ID.

      The transaction id is expected to be a positive long. If you have a negative `int`, convert the int to an unsigned long using `NumericHelper.toUnsignedLong(int)`

      Specified by:
        `commitTransaction` in interface `MaintenanceManager`
      Parameters:
        `transactionId` - The ID of the limbo transaction to be committed (must be `> 0`)
      Throws:
        `java.sql.SQLException` - if a database access error occurs or the given transaction ID is not valid

    - #### rollbackTransaction

          public void rollbackTransaction​(long transactionId)
                                   throws java.sql.SQLException

      Description copied from interface: `MaintenanceManager`
      Rollback a limbo transaction based on its ID.

      The transaction id is expected to be a positive long. If you have a negative `int`, convert the int to an unsigned long using `NumericHelper.toUnsignedLong(int)`

      Specified by:
        `rollbackTransaction` in interface `MaintenanceManager`
      Parameters:
        `transactionId` - The ID of the limbo transaction to be rolled back (must be `> 0`)
      Throws:
        `java.sql.SQLException` - if a database access error occurs or the given transaction ID is not valid