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 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, Thomas Steinmaurer

Field Summary

static int	ACCESS_MODE_READ_ONLY Database read-only mode
static int	ACCESS_MODE_READ_WRITE Database read-write mode
static byte	OPERATION_MODE_FULL_SHUTDOWN Operation mode full shutdown.
static byte	OPERATION_MODE_MULTI Operation mode multi shutdown/online.
static byte	OPERATION_MODE_NORMAL Operation mode normal online.
static byte	OPERATION_MODE_SINGLE Operation mode single shutdown/online.
static int	PAGE_FILL_FULL Fully fill pages when inserting records.
static int	PAGE_FILL_RESERVE While inserting recrods, reserve 20% of each page for later record deltas
static int	SHUTDOWN_ATTACH Don't allow new connections while waiting to shut down.
static int	SHUTDOWN_FORCE Forced database shutdown.
static int	SHUTDOWN_TRANSACTIONAL Don't allow new transactions while waiting to shut down.
static int	SHUTDOWNEX_ATTACHMENTS Shutdown attachments.
static int	SHUTDOWNEX_FORCE Force shutdown.
static int	SHUTDOWNEX_TRANSACTIONS Shutdown transactions.
static int	VALIDATE_FULL Do a full check on record and pages structures, releasing unassigned record fragments.
static int	VALIDATE_IGNORE_CHECKSUM Ignore checksums during repair operations.
static int	VALIDATE_READ_ONLY Only report corrupt or misallocated structures, don't fix.

Method Summary

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 new since Firebird 2.5.
void	commitTransaction(int transactionId) Deprecated. Use commitTransaction(long). This method wil be removed in Jaybird 3.1.
void	commitTransaction(long transactionId) Commit a limbo transaction based on its ID.
void	killUnavailableShadows() Remove references to unavailable shadow files.
void	listLimboTransactions() Retrieve the ID of each limbo transaction.
void	markCorruptRecords() Mark corrupt records in the database as unavailable.
void	rollbackTransaction(int transactionId) Deprecated. Use rollbackTransaction(long). This method wil be removed in Jaybird 3.1.
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 new since Firebird 2.5.
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 interface org.firebirdsql.management.ServiceManager

getDatabase, getHost, getLogger, getPassword, getPort, getUser, setDatabase, setHost, setLogger, setPassword, setPort, setUser

Field Detail

ACCESS_MODE_READ_WRITE

static final int ACCESS_MODE_READ_WRITE

Database read-write mode

See Also:

Constant Field Values

ACCESS_MODE_READ_ONLY

static final int ACCESS_MODE_READ_ONLY

Database read-only mode

See Also:

Constant Field Values

SHUTDOWN_ATTACH

static final int SHUTDOWN_ATTACH

Don't allow new connections while waiting to shut down.

See Also:

Constant Field Values

SHUTDOWN_TRANSACTIONAL

static final int SHUTDOWN_TRANSACTIONAL

Don't allow new transactions while waiting to shut down.

See Also:

Constant Field Values

SHUTDOWN_FORCE

static final int SHUTDOWN_FORCE

Forced database shutdown.

See Also:

Constant Field Values

VALIDATE_READ_ONLY

static final int VALIDATE_READ_ONLY

Only report corrupt or misallocated structures, don't fix.

See Also:

Constant Field Values

VALIDATE_IGNORE_CHECKSUM

static final int VALIDATE_IGNORE_CHECKSUM

Ignore checksums during repair operations.

See Also:

Constant Field Values

VALIDATE_FULL

static final int VALIDATE_FULL

Do a full check on record and pages structures, releasing unassigned record fragments.

See Also:

Constant Field Values

PAGE_FILL_FULL

static final int PAGE_FILL_FULL

Fully fill pages when inserting records.

See Also:

Constant Field Values

PAGE_FILL_RESERVE

static final int PAGE_FILL_RESERVE

While inserting recrods, reserve 20% of each page for later record deltas

See Also:

Constant Field Values

OPERATION_MODE_NORMAL

static final byte OPERATION_MODE_NORMAL

Operation mode normal online. New with Firebird 2.5. To be used with the shutdownDatabase(byte, int, int) method.

See Also:

shutdownDatabase(byte, int, int), Constant Field Values

OPERATION_MODE_MULTI

static final byte OPERATION_MODE_MULTI

Operation mode multi shutdown/online. New with Firebird 2.5. To be used with the shutdownDatabase(byte, int, int) method.

See Also:

shutdownDatabase(byte, int, int), Constant Field Values

OPERATION_MODE_SINGLE

static final byte OPERATION_MODE_SINGLE

Operation mode single shutdown/online. New with Firebird 2.5. To be used with the shutdownDatabase(byte, int, int) method.

See Also:

shutdownDatabase(byte, int, int), Constant Field Values

OPERATION_MODE_FULL_SHUTDOWN

static final byte OPERATION_MODE_FULL_SHUTDOWN

Operation mode full shutdown. New with Firebird 2.5. To be used with the shutdownDatabase(byte, int, int) method.

See Also:

shutdownDatabase(byte, int, int), Constant Field Values

SHUTDOWNEX_FORCE

static final int SHUTDOWNEX_FORCE

Force shutdown. New with Firebird 2.5. To be used with the shutdownDatabase(byte, int, int) method.

See Also:

shutdownDatabase(byte, int, int), Constant Field Values

SHUTDOWNEX_ATTACHMENTS

static final int SHUTDOWNEX_ATTACHMENTS

Shutdown attachments. New with Firebird 2.5. To be used with the shutdownDatabase(byte, int, int) method.

See Also:

shutdownDatabase(byte, int, int), Constant Field Values

SHUTDOWNEX_TRANSACTIONS

static final int SHUTDOWNEX_TRANSACTIONS

Shutdown transactions. New with Firebird 2.5. To be used with the shutdownDatabase(byte, int, int) method.

See Also:

shutdownDatabase(byte, int, int), Constant Field Values

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. The Firebird default is 2048.

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 use buffered writing 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 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.

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

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 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:

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

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

void listLimboTransactions()
                           throws java.sql.SQLException

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

commitTransaction

@Deprecated
void commitTransaction(int transactionId)
                       throws java.sql.SQLException

Deprecated. Use commitTransaction(long). This method wil be removed in Jaybird 3.1.

Commit a limbo transaction based on its ID.

Parameters:

transactionId - The ID of the limbo transaction to be committed

Throws:

java.sql.SQLException - if a database access error occurs or the given transaction ID is not valid

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, either call the - deprecated - commitTransaction(int), or 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

@Deprecated
void rollbackTransaction(int transactionId)
                         throws java.sql.SQLException

Deprecated. Use rollbackTransaction(long). This method wil be removed in Jaybird 3.1.

Rollback a limbo transaction based on its ID.

Parameters:

transactionId - The ID of the limbo transaction to be rolled back

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, either call the - deprecated - rollbackTransaction(int), or 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