org.firebirdsql.management.MaintenanceManager Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jaybird Show documentation
JDBC Driver for the Firebird RDBMS
The newest version!
/*
 * Public Firebird Java API.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *    1. Redistributions of source code must retain the above copyright notice,
 *       this list of conditions and the following disclaimer.
 *    2. Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *    3. The name of the author may not be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
 * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
package org.firebirdsql.management;

import org.firebirdsql.gds.ISCConstants;

import java.sql.SQLException;
import java.util.List;

/**
 * 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
 * @author Thomas Steinmaurer
 */
public interface MaintenanceManager extends ServiceManager {

    /**
     * Database read-write mode
     */
    int ACCESS_MODE_READ_WRITE = ISCConstants.isc_spb_prp_am_readwrite;

    /**
     * Database read-only mode
     */
    int ACCESS_MODE_READ_ONLY = ISCConstants.isc_spb_prp_am_readonly;

    /**
     * Don't allow new connections while waiting to shut down.
     */
    int SHUTDOWN_ATTACH = ISCConstants.isc_spb_prp_deny_new_attachments;

    /**
     * Don't allow new transactions while waiting to shut down.
     */
    int SHUTDOWN_TRANSACTIONAL = ISCConstants.isc_spb_prp_deny_new_transactions;

    /**
     * Forced database shutdown.
     */
    int SHUTDOWN_FORCE = ISCConstants.isc_spb_prp_shutdown_db;

    /**
     * Only report corrupt or misallocated structures, don't fix.
     */
    int VALIDATE_READ_ONLY = ISCConstants.isc_spb_rpr_check_db;

    /**
     * Ignore checksums during repair operations.
     */
    int VALIDATE_IGNORE_CHECKSUM = ISCConstants.isc_spb_rpr_ignore_checksum;

    /**
     * Do a full check on record and pages structures, releasing unassigned
     * record fragments.
     */
    int VALIDATE_FULL = ISCConstants.isc_spb_rpr_full;

    /**
     * Fully fill pages when inserting records.
     */
    int PAGE_FILL_FULL = ISCConstants.isc_spb_prp_res_use_full;

    /**
     * While inserting records, reserve 20% of each page for later record deltas
     */
    int PAGE_FILL_RESERVE = ISCConstants.isc_spb_prp_res;

    /**
     * Operation mode normal online.
     * 
     * To be used with the {@link #shutdownDatabase(byte, int, int)} method.
     * 
     *
     * @see #shutdownDatabase(byte, int, int)
     * @since Firebird 2.5
     */
    byte OPERATION_MODE_NORMAL = ISCConstants.isc_spb_prp_sm_normal;

    /**
     * Operation mode multi shutdown/online.
     * 
     * To be used with the {@link #shutdownDatabase(byte, int, int)} method.
     * 
     *
     * @see #shutdownDatabase(byte, int, int)
     * @since Firebird 2.5
     */
    byte OPERATION_MODE_MULTI = ISCConstants.isc_spb_prp_sm_multi;

    /**
     * Operation mode single shutdown/online.
     * 
     * To be used with the {@link #shutdownDatabase(byte, int, int)} method.
     * 
     *
     * @see #shutdownDatabase(byte, int, int)
     * @since Firebird 2.5
     */
    byte OPERATION_MODE_SINGLE = ISCConstants.isc_spb_prp_sm_single;

    /**
     * Operation mode full shutdown.
     * 
     * To be used with the {@link #shutdownDatabase(byte, int, int)} method.
     * 
     *
     * @see #shutdownDatabase(byte, int, int)
     * @since Firebird 2.5
     */
    byte OPERATION_MODE_FULL_SHUTDOWN = ISCConstants.isc_spb_prp_sm_full;

    /**
     * Force shutdown.
     * 
     * To be used with the {@link #shutdownDatabase(byte, int, int)} method.
     * 
     *
     * @see #shutdownDatabase(byte, int, int)
     * @since Firebird 2.5
     */
    int SHUTDOWNEX_FORCE = ISCConstants.isc_spb_prp_force_shutdown;

    /**
     * Shutdown attachments.
     * 
     * To be used with the {@link #shutdownDatabase(byte, int, int)} method.
     * 
     *
     * @see #shutdownDatabase(byte, int, int)
     * @since Firebird 2.5
     */
    int SHUTDOWNEX_ATTACHMENTS = ISCConstants.isc_spb_prp_attachments_shutdown;

    /**
     * Shutdown transactions.
     * 
     * To be used with the {@link #shutdownDatabase(byte, int, int)} method.
     * 
     *
     * @see #shutdownDatabase(byte, int, int)
     * @since Firebird 2.5
     */
    int SHUTDOWNEX_TRANSACTIONS = ISCConstants.isc_spb_prp_transactions_shutdown;

    /**
     * Set the database to have read-write or read-only access.
     *
     * @param mode
     *         Must be either {@code ACCESS_MODE_READ_WRITE} or {@code ACCESS_MODE_READ_ONLY}
     * @throws SQLException
     *         if a database access error occurs
     */
    void setDatabaseAccessMode(int mode) throws SQLException;

    /**
     * Set the database's dialect.
     *
     * @param dialect
     *         The database dialect, must be either 1 or 3
     * @throws SQLException
     *         if a database access error occurs
     */
    void setDatabaseDialect(int dialect) throws SQLException;

    /**
     * Set the default page-buffer count to be cached in the database.
     *
     * @param pageCount
     *         The number of pages to be cached, must be a positive
     * @throws SQLException
     *         If the given page count cannot be set, or a database access error occurs
     */
    void setDefaultCacheBuffer(int pageCount) throws 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.
     * 
     *
     * @param forced
     *         If {@code true}, forced writes will be used in the database, otherwise buffered writes will be used.
     * @throws SQLException
     *         if a database access error occurs
     */
    void setForcedWrites(boolean forced) throws SQLException;

    /**
     * Set the page fill strategy for when inserting records.
     * 
     * {@code pageFill} can be one of:
     * 

     * {@code PAGE_FILL_FULL} Fully fill database pages
     * 
{@code PAGE_FILL_RESERVE} Reserve 20% of page space for later
     * record deltas
     * 
     * 
     *
     * @param pageFill
     *         The page-filling strategy, either {@code PAGE_FILL_FULL} or {@code PAGE_FILL_RESERVE}
     * @throws SQLException
     *         if a database access error occurs
     */
    void setPageFill(int pageFill) throws SQLException;

    // ----------- Database Shutdown -------------------

    /**
     * Shutdown the current database.
     * 
     * Shutdown can be done in three modes:
     * 

     * {@code 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.
     * {@code 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.
     * {@code SHUTDOWN_FORCE} - Forcefully shuts down the database at the end of the timeout.
     * 
     * 
     *
     * @param shutdownMode
     *         One of {@code SHUTDOWN_ATTACH}, {@code SHUTDOWN_TRANSACTIONAL}, or {@code SHUTDOWN_FORCE}.
     * @param timeout
     *         The maximum amount of time allocated for the operation, in seconds
     * @throws SQLException
     *         if the requested operation cannot be completed within the given timeout, or a database access error
     *         occurs
     */
    void shutdownDatabase(int shutdownMode, int timeout) throws SQLException;

    /**
     * Shutdown the current database with enhanced modes (FB 2.5 or higher).
     * 
     * There are three operation modes for shutdown available:
     * 

     * {@code OPERATION_MODE_MULTI} - Multi-user maintenance. Unlimited SYSDBA/database owner connections are
     * allowed.
     * {@code OPERATION_MODE_SINGLE} - Single-user maintenance. Only one SYSDBA/database owner connection is
     * allowed.
     * {@code OPERATION_MODE_FULL_SHUTDOWN} - Full shutdown. Full exclusive shutdown. No connections are allowed.
     * 
     * 
     * 
     * There are three extended shutdown modes for shutdown available:
     * 

     * {@code SHUTDOWNEX_FORCE} - Force shutdown.
     * {@code SHUTDOWNEX_ATTACHMENTS} - Shutdown attachments.
     * {@code SHUTDOWNEX_TRANSACTIONS} - Shutdown transactions.
     * 
     * 
     *
     * @param operationMode
     *         one of {@code OPERATION_MODE_*} operation modes listed above
     * @param shutdownModeEx
     *         one of {@code SHUTDOWNEX_*} extended shutdown modes listed above
     * @param timeout
     *         The maximum amount of time allocated for the operation, in seconds. 0 = immediately.
     * @throws SQLException
     *         if the requested operation cannot be completed within the given timeout, or a database access error
     *         occurs
     * @since Firebird 2.5
     */
    void shutdownDatabase(byte operationMode, int shutdownModeEx, int timeout) throws SQLException;

    /**
     * Bring a shutdown database online.
     *
     * @throws SQLException
     *         if a database access error occurs
     */
    void bringDatabaseOnline() throws 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:
     * 

     * {@code OPERATION_MODE_NORMAL} - Normal operation modes.
     * {@code OPERATION_MODE_MULTI} - Multi-user maintenance. Unlimited SYSDBA/database owner connections are
     * allowed.
     * {@code OPERATION_MODE_SINGLE} - Single-user maintenance. Only one SYSDBA/database owner connection is
     * allowed.
     * 
     * 
     *
     * @throws SQLException
     *         if a database access error occurs
     * @since Firebird 2.5
     */
    void bringDatabaseOnline(byte operationMode) throws SQLException;

    // -------------- Database Repair ----------------------

    /**
     * Mark corrupt records in the database as unavailable.
     * 
     * This operation ensures that the corrupt records are skipped (for example,
     * during a subsequent backup).
     * 
     *
     * @throws SQLException
     *         if a database access error occurs
     */
    void markCorruptRecords() throws SQLException;

    /**
     * Locate and release database pages that are allocated but unassigned to
     * any data structures. This method also reports corrupt structures.
     *
     * @throws SQLException
     *         if a database access error occurs
     */
    void validateDatabase() throws 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 {@code options} must be one of the following:
     * 

     * 0 - Simple validation
     * {@code VALIDATE_READ_ONLY} - read-only validation, no repair
     * {@code VALIDATE_FULL} - full validation and repair
     * 
     * 
     * 
     * The value for {@code options} can additionally be combined in a bitmask with {@code VALIDATE_IGNORE_CHECKSUM} to
     * ignore checksums while performing validation.
     * 
     *
     * @param options
     *         Either 0, {@code VALIDATE_READ_ONLY}, or {@code VALIDATE_FULL}
     * @throws SQLException
     *         if a database access error occurs
     */
    void validateDatabase(int options) throws SQLException;

    // ----------- Sweeping -------------------------

    /**
     * Set the database automatic sweep interval to a given number of
     * transactions.
     * 
     * The Firebird default value is 20,000. If {@code transactions} is 0, automatic sweeping is disabled.
     * 
     *
     * @param transactions
     *         The interval of transactions between automatic sweeps of the database. Can be set to 0, which disables
     *         automatic sweeping of the database.
     * @throws SQLException
     *         if a database access error occurs
     */
    void setSweepThreshold(int transactions) throws SQLException;

    /**
     * Perform an immediate sweep of the database.
     *
     * @throws SQLException
     *         if a database access error occurs
     */
    void sweepDatabase() throws SQLException;

    // ----------- Shadow Files ------------------------------------

    /**
     * Activate a database shadow file to be used as the actual database.
     * 
     * This method is the equivalent of {@code gfix -activate}.
     * 
     *
     * @throws SQLException
     *         if a database access error occurs
     */
    void activateShadowFile() throws SQLException;

    /**
     * Remove references to unavailable shadow files.
     * 
     * This method is the equivalent of {@code gfix -kill}.
     * 
     *
     * @throws SQLException
     *         if a database access error occurs
     */
    void killUnavailableShadows() throws SQLException;

    // ----------- Transaction Management ----------------------------

    /**
     * Retrieve the ID of each limbo transaction as a List of Long objects.
     *
     * @throws SQLException
     *         if a database access error occurs
     */
    List limboTransactionsAsList() throws SQLException;

    /**
     * Retrieve the ID of each limbo transaction as an array of longs.
     * 
     * In Firebird 3, transactions are (unsigned) 48 bit longs.
     * 
     *
     * @throws SQLException
     *         if a database access error occurs
     */
    long[] getLimboTransactions() throws SQLException;

    /**
     * Commit a limbo transaction based on its ID.
     * 
     * The transaction id is expected to be a positive long. If you have a negative {@code int}, convert the int to
     * an unsigned long using {@link org.firebirdsql.util.NumericHelper#toUnsignedLong(int)}
     * 
     *
     * @param transactionId
     *         The ID of the limbo transaction to be committed (must be {@code > 0})
     * @throws SQLException
     *         if a database access error occurs or the given transaction ID is not valid
     */
    void commitTransaction(long transactionId) throws SQLException;

    /**
     * Rollback a limbo transaction based on its ID.
     * 
     * The transaction id is expected to be a positive long. If you have a negative {@code int}, convert the int to
     * an unsigned long using {@link org.firebirdsql.util.NumericHelper#toUnsignedLong(int)}
     * 
     *
     * @param transactionId
     *         The ID of the limbo transaction to be rolled back (must be {@code > 0})
     * @throws SQLException
     *         if a database access error occurs or the given transaction ID is not valid
     */
    void rollbackTransaction(long transactionId) throws SQLException;

    /**
     * Perform minor ODS upgrade.
     * 
     * Requires Firebird 5.0 or higher.
     * 
     *
     * @throws SQLException
     *         if a database access error occurs
     * @since 5.0.2
     */
    void upgradeOds() throws SQLException;

    /**
     * Update or rebuild ICU-dependent collations and indexes when ICU version changed.
     * 
     * Requires Firebird 3.0 or higher.
     * 
     *
     * @throws SQLException
     *         if a database access error occurs
     * @since 5.0.2
     */
    void fixIcu() throws SQLException;

}