Package org.firebirdsql.management

Interface MaintenanceManager

  • All Superinterfaces:
    ServiceManager
    All Known Implementing Classes:
    FBMaintenanceManager
    public interface MaintenanceManager
extends ServiceManager
    A MaintenanceManager 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
    • 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
    • Displaying, committing, or recovering limbo transactions
    • Activating and killing shadow files
    • Configuring page fill

    Author:
    Gabriel Reid, Thomas Steinmaurer

    • Method Detail

      • setDatabaseAccessMode

        void setDatabaseAccessMode​(int mode)
                    throws java.sql.SQLException
        Set the database to have read-write or read-only access.
        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

        void setDatabaseDialect​(int dialect)
                 throws java.sql.SQLException
        Set the database's dialect.
        Parameters:
        dialect - The database dialect, must be either 1 or 3
        Throws:
        java.sql.SQLException - if a database access error occurs

      • setDefaultCacheBuffer

        void setDefaultCacheBuffer​(int pageCount)
                    throws java.sql.SQLException
        Set the default page-buffer count to be cached in the database.
        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

        void setForcedWrites​(boolean forced)
              throws java.sql.SQLException
        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.

        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

        void setPageFill​(int pageFill)
          throws java.sql.SQLException
        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

        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

        void shutdownDatabase​(int shutdownMode,
                      int timeout)
               throws java.sql.SQLException
        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.

        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

        void shutdownDatabase​(byte operationMode,
                      int shutdownModeEx,
                      int timeout)
               throws java.sql.SQLException
        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.

        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
        Since:
        Firebird 2.5

      • bringDatabaseOnline

        void bringDatabaseOnline()
                  throws java.sql.SQLException
        Bring a shutdown database online.
        Throws:
        java.sql.SQLException - if a database access error occurs

      • bringDatabaseOnline

        void bringDatabaseOnline​(byte operationMode)
                  throws java.sql.SQLException
        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.

        Throws:
        java.sql.SQLException - if a database access error occurs
        Since:
        Firebird 2.5

      • markCorruptRecords

        void markCorruptRecords()
                 throws java.sql.SQLException
        Mark corrupt records in the database as unavailable.

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

        Throws:
        java.sql.SQLException - if a database access error occurs

      • validateDatabase

        void validateDatabase()
               throws java.sql.SQLException
        Locate and release database pages that are allocated but unassigned to any data structures. This method also reports corrupt structures.
        Throws:
        java.sql.SQLException - if a database access error occurs

      • validateDatabase

        void validateDatabase​(int options)
               throws java.sql.SQLException
        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.

        Parameters:
        options - Either 0, VALIDATE_READ_ONLY, or VALIDATE_FULL
        Throws:
        java.sql.SQLException - if a database access error occurs

      • setSweepThreshold

        void setSweepThreshold​(int transactions)
                throws java.sql.SQLException
        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.

        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

        void sweepDatabase()
            throws java.sql.SQLException
        Perform an immediate sweep of the database.
        Throws:
        java.sql.SQLException - if a database access error occurs

      • activateShadowFile

        void activateShadowFile()
                 throws java.sql.SQLException
        Activate a database shadow file to be used as the actual database.

        This method is the equivalent of gfix -activate.

        Throws:
        java.sql.SQLException - if a database access error occurs

      • killUnavailableShadows

        void killUnavailableShadows()
                     throws java.sql.SQLException
        Remove references to unavailable shadow files.

        This method is the equivalent of gfix -kill.

        Throws:
        java.sql.SQLException - if a database access error occurs

      • listLimboTransactions

        @Deprecated
void listLimboTransactions()
                    throws java.sql.SQLException
        Deprecated.
        Use limboTransactionsAsList() or getLimboTransactions() instead; this method will be removed in Jaybird 5.
        Retrieve the ID of each limbo transaction. The output of this method is written to the logger.
        Throws:
        java.sql.SQLException - if a database access error occurs

      • limboTransactionsAsList

        java.util.List<java.lang.Long> limboTransactionsAsList()
                                                throws java.sql.SQLException
        Retrieve the ID of each limbo transaction as a List of Long objects.
        Throws:
        java.sql.SQLException - if a database access error occurs

      • getLimboTransactions

        long[] getLimboTransactions()
                     throws java.sql.SQLException
        Retrieve the ID of each limbo transaction as an array of longs.

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

        Throws:
        java.sql.SQLException - if a database access error occurs

      • commitTransaction

        void commitTransaction​(long transactionId)
                throws java.sql.SQLException
        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)

        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

        void rollbackTransaction​(long transactionId)
                  throws java.sql.SQLException
        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)

        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