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-jdk15 Show documentation
Show all versions of jaybird-jdk15 Show documentation
JDBC Driver for the Firebird RDBMS
/*
* Firebird Open Source J2EE Connector - JDBC Driver
*
* Copyright (C) All Rights Reserved.
*
* This file was created by members of the firebird development team.
* All individual contributions remain the Copyright (C) of those
* individuals. Contributors to this file are either listed here or
* can be obtained from a CVS history command.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* - Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* - 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.
* - Neither the name of the firebird development team nor the names
* of its contributors may be used to endorse or promote products
* derived from this software without specific prior written
* permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* "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
* COPYRIGHT OWNER OR CONTRIBUTORS 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 java.sql.SQLException;
import org.firebirdsql.gds.ISCConstants;
/**
* 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 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
*
- 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
*/
public static final int ACCESS_MODE_READ_WRITE = ISCConstants.isc_spb_prp_am_readwrite;
/**
* Database read-only mode
*/
public static final int ACCESS_MODE_READ_ONLY = ISCConstants.isc_spb_prp_am_readonly;
/**
* Don't allow new connections while waiting to shut down.
*/
public static final int SHUTDOWN_ATTACH = ISCConstants.isc_spb_prp_deny_new_attachments;
/**
* Don't allow new transactions while waiting to shut down.
*/
public static final int SHUTDOWN_TRANSACTIONAL = ISCConstants.isc_spb_prp_deny_new_transactions;
/**
* Forced database shutdown.
*/
public static final int SHUTDOWN_FORCE = ISCConstants.isc_spb_prp_shutdown_db;
/**
* Only report corrupt or misallocated structures, don't fix.
*/
public static final int VALIDATE_READ_ONLY = ISCConstants.isc_spb_rpr_check_db;
/**
* Ignore checksums during repair operations.
*/
public static final int VALIDATE_IGNORE_CHECKSUM = ISCConstants.isc_spb_rpr_ignore_checksum;
/**
* Do a full check on record and pages structures, releasing unassigned
* record fragments.
*/
public static final int VALIDATE_FULL = ISCConstants.isc_spb_rpr_full;
/**
* Fully fill pages when inserting records.
*/
public static final int PAGE_FILL_FULL = ISCConstants.isc_spb_prp_res_use_full;
/**
* While inserting recrods, reserve 20% of each page for later
* record deltas
*/
public static final int PAGE_FILL_RESERVE = ISCConstants.isc_spb_prp_res;
/**
* Operation mode normal online. New with Firebird 2.5.
* To be used with the {@link #shutdownDatabase(byte, int, int)} method.
* @see #shutdownDatabase(byte, int, int)
*/
public static final byte OPERATION_MODE_NORMAL = ISCConstants.isc_spb_prp_sm_normal;
/**
* Operation mode multi shutdown/online. New with Firebird 2.5.
* To be used with the {@link #shutdownDatabase(byte, int, int)} method.
* @see #shutdownDatabase(byte, int, int)
*/
public static final byte OPERATION_MODE_MULTI = ISCConstants.isc_spb_prp_sm_multi;
/**
* Operation mode single shutdown/online. New with Firebird 2.5.
* To be used with the {@link #shutdownDatabase(byte, int, int)} method.
* @see #shutdownDatabase(byte, int, int)
*/
public static final byte OPERATION_MODE_SINGLE = ISCConstants.isc_spb_prp_sm_single;
/**
* Operation mode full shutdown. New with Firebird 2.5.
* To be used with the {@link #shutdownDatabase(byte, int, int)} method.
* @see #shutdownDatabase(byte, int, int)
*/
public static final byte OPERATION_MODE_FULL_SHUTDOWN = ISCConstants.isc_spb_prp_sm_full;
/**
* Force shutdown. New with Firebird 2.5.
* To be used with the {@link #shutdownDatabase(byte, int, int)} method.
* @see #shutdownDatabase(byte, int, int)
*/
public static final int SHUTDOWNEX_FORCE = ISCConstants.isc_spb_prp_force_shutdown;
/**
* Shutdown attachments. New with Firebird 2.5.
* To be used with the {@link #shutdownDatabase(byte, int, int)} method.
* @see #shutdownDatabase(byte, int, int)
*/
public static final int SHUTDOWNEX_ATTACHMENTS = ISCConstants.isc_spb_prp_attachments_shutdown;
/**
* Shutdown transactions. New with Firebird 2.5.
* To be used with the {@link #shutdownDatabase(byte, int, int)} method.
* @see #shutdownDatabase(byte, int, int)
*/
public static final 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 ACCESS_MODE_READ_WRITE
* or ACCESS_MODE_READ_ONLY
* @throws SQLException if a database access error occurs
*/
public 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
*/
public void setDatabaseDialect(int dialect) throws SQLException;
/**
* Set the default page-buffer count to be cached in the database. The
* Firebird default is 2048.
*
* @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
*/
public 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 use buffered
* writing on Windows platforms.
*
* @param forced If true, forced writes will be used in the
* database, otherwise buffered writes will be used.
* @throws SQLException if a database access error occurs
*/
public void setForcedWrites(boolean forced) throws 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
*
*
* @param pageFill The page-filling strategy, either
* PAGE_FILL_FULL or PAGE_FILL_RESERVE
* @throws SQLException if a database access error occurs
*/
public void setPageFill(int pageFill) throws SQLException;
//----------- Database Shutdown -------------------
/**
* 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.
*
*
* @param shutdownMode One of SHUTDOWN_ATTACH,
* SHUTDOWN_TRANSACTIONAL,
* or 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
*/
public void shutdownDatabase(int shutdownMode, int timeout)
throws SQLException ;
/**
* Shutdown the current database with enhanced modes new since Firebird 2.5.
* 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.
*
* @param operationMode one of OPERATION_MODE_* operation modes listed above
* @param shutdownModeEx one of 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
*/
public void shutdownDatabase(byte operationMode, int shutdownModeEx, int timeout) throws SQLException ;
/**
* Bring a shutdown database online.
*
* @throws SQLException if a database access error occurs
*/
public void bringDatabaseOnline() throws SQLException;
/**
* Bring a shutdown database online with enhanced operation modes
* new since Firebird 2.5.
* 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 SQLException if a database access error occurs
*/
public 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
*/
public 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
*/
public 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 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.
*
* @param options Either 0, VALIDATE_READ_ONLY, or
* VALIDATE_FULL
* @throws SQLException if a database access error occurs
*/
public 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
* 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
*/
public void setSweepThreshold(int transactions) throws SQLException;
/**
* Perform an immediate sweep of the database.
*
* @throws SQLException if a database access error occurs
*/
public void sweepDatabase() throws SQLException;
//----------- Shadow Files ------------------------------------
/**
* Activate a database shadow file to be used as the actual database.
* This method is the equivalent of gfix -activate.
*
* @throws SQLException if a database access error occurs
*/
public void activateShadowFile() throws SQLException;
/**
* Remove references to unavailable shadow files. This method is the
* equivalent of gfix -kill.
*
* @throws SQLException if a database access error occurs
*/
public void killUnavailableShadows() throws SQLException;
//----------- Transaction Management ----------------------------
/**
* Retrieve the ID of each limbo transaction. The output of this method
* is written to the logger.
*
* @throws SQLException if a database access error occurs
*/
public void listLimboTransactions() throws SQLException;
/**
* Commit a limbo transaction based on its ID.
*
* @param transactionId The ID of the limbo transaction to be committed
* @throws SQLException if a database access error occurs or the
* given transaction ID is not valid
*/
public void commitTransaction(int transactionId) throws SQLException;
/**
* Rollback a limbo transaction based on its ID.
*
* @param transactionId The ID of the limbo transaction to be rolled back
* @throws SQLException if a database access error occurs or the
* given transaction ID is not valid
*/
public void rollbackTransaction(int transactionId) throws SQLException;
}