Package org.firebirdsql.management

Class FBMaintenanceManager

  • All Implemented Interfaces:
    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

    • 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

      • listLimboTransactions

        @Deprecated
public void listLimboTransactions()
                           throws java.sql.SQLException
        Deprecated.
        Description copied from interface: MaintenanceManager
        Retrieve the ID of each limbo transaction. The output of this method is written to the logger.
        Specified by:
        listLimboTransactions 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