Module org.firebirdsql.jaybird

Package org.firebirdsql.management

Class FBMaintenanceManager

java.lang.Object

org.firebirdsql.management.FBServiceManager

org.firebirdsql.management.FBMaintenanceManager

All Implemented Interfaces:

AttachmentProperties, BaseProperties, ServiceConnectionProperties, 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

Field Summary

Fields inherited from class org.firebirdsql.management.FBServiceManager

BUFFER_SIZE

Fields inherited from interface org.firebirdsql.management.MaintenanceManager

ACCESS_MODE_READ_ONLY, ACCESS_MODE_READ_WRITE, OPERATION_MODE_FULL_SHUTDOWN, OPERATION_MODE_MULTI, OPERATION_MODE_NORMAL, OPERATION_MODE_SINGLE, PAGE_FILL_FULL, PAGE_FILL_RESERVE, SHUTDOWN_ATTACH, SHUTDOWN_FORCE, SHUTDOWN_TRANSACTIONAL, SHUTDOWNEX_ATTACHMENTS, SHUTDOWNEX_FORCE, SHUTDOWNEX_TRANSACTIONS, VALIDATE_FULL, VALIDATE_IGNORE_CHECKSUM, VALIDATE_READ_ONLY

Constructor Summary

Constructors

Constructor	Description
FBMaintenanceManager()	Create a new instance of FBMaintenanceManager based on the default GDSType.
FBMaintenanceManager(String gdsType)	Create a new instance of FBMaintenanceManager based on a given GDSType.
FBMaintenanceManager(GDSType gdsType)	Create a new instance of FBMaintenanceManager based on a given GDSType.

Method Summary

Modifier and Type	Method	Description
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 (FB 2.5 or higher).
void	commitTransaction(long transactionId)	Commit a limbo transaction based on its ID.
void	fixIcu()	Update or rebuild ICU-dependent collations and indexes when ICU version changed.
long[]	getLimboTransactions()	Retrieve the ID of each limbo transaction as an array of longs.
void	killUnavailableShadows()	Remove references to unavailable shadow files.
List<Long>	limboTransactionsAsList()	Retrieve the ID of each limbo transaction as a List of Long objects.
void	markCorruptRecords()	Mark corrupt records in the database as unavailable.
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 (FB 2.5 or higher).
void	shutdownDatabase(int shutdownMode, int timeout)	Shutdown the current database.
void	sweepDatabase()	Perform an immediate sweep of the database.
void	upgradeOds()	Perform minor ODS upgrade.
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 class org.firebirdsql.management.FBServiceManager

attachDatabase, attachServiceManager, connectionPropertyValues, createRequestBuffer, executeServicesOperation, getAuthPlugins, getBooleanProperty, getCharSet, getDatabase, getDbCryptConfig, getExpectedDb, getHost, getIntProperty, getLogger, getPassword, getPort, getPortNumber, getProperty, getServerName, getServerVersion, getServiceName, getUser, getWireCrypt, getWireCryptAsEnum, isWireCompression, queueService, setAuthPlugins, setBooleanProperty, setCharSet, setDatabase, setDbCryptConfig, setExpectedDb, setHost, setIntProperty, setLogger, setPassword, setPort, setPortNumber, setProperty, setServerName, setServiceName, setType, setUser, setWireCompression, setWireCryptAsEnum

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.firebirdsql.jaybird.props.AttachmentProperties

getAuthPlugins, getCharSet, getConnectTimeout, getDbCryptConfig, getEnableProtocol, getEncoding, getParallelWorkers, getPassword, getPortNumber, getProcessId, getProcessName, getRoleName, getServerName, getSocketBufferSize, getSocketFactory, getSoTimeout, getType, getUser, getWireCrypt, isWireCompression, setAuthPlugins, setCharSet, setConnectTimeout, setDbCryptConfig, setEnableProtocol, setEncoding, setParallelWorkers, setPassword, setPortNumber, setProcessId, setProcessName, setRoleName, setServerName, setSocketBufferSize, setSocketFactory, setSoTimeout, setType, setUser, setWireCompression, setWireCrypt

Methods inherited from interface org.firebirdsql.jaybird.props.BaseProperties

connectionPropertyValues, getBooleanProperty, getBooleanProperty, getIntProperty, getIntProperty, getProperty, getProperty, setBooleanProperty, setIntProperty, setProperty

Methods inherited from interface org.firebirdsql.jaybird.props.ServiceConnectionProperties

getExpectedDb, getServiceName, setExpectedDb, setServiceName

Methods inherited from interface org.firebirdsql.management.ServiceManager

getDatabase, getHost, getLogger, getPort, getServerVersion, getWireCryptAsEnum, setDatabase, setHost, setLogger, setPort, setWireCryptAsEnum

Constructor Details

FBMaintenanceManager

public FBMaintenanceManager()

Create a new instance of FBMaintenanceManager based on the default GDSType.

FBMaintenanceManager

public FBMaintenanceManager(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 Details

setDatabaseAccessMode

public void setDatabaseAccessMode(int mode)
                           throws 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:

SQLException - if a database access error occurs

setDatabaseDialect

public void setDatabaseDialect(int dialect)
                        throws 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:

SQLException - if a database access error occurs

setDefaultCacheBuffer

public void setDefaultCacheBuffer(int pageCount)
                           throws 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:

SQLException - If the given page count cannot be set, or a database access error occurs

setForcedWrites

public void setForcedWrites(boolean forced)
                     throws 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:

SQLException - if a database access error occurs

setPageFill

public void setPageFill(int pageFill)
                 throws 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:

SQLException - if a database access error occurs

shutdownDatabase

public void shutdownDatabase(int shutdownMode,
 int timeout)
                      throws 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:

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

SQLException - if the requested operation cannot be completed within the given timeout, or a database access error occurs

bringDatabaseOnline

public void bringDatabaseOnline()
                         throws SQLException

Description copied from interface: MaintenanceManager

Bring a shutdown database online.

Specified by:

bringDatabaseOnline in interface MaintenanceManager

Throws:

SQLException - if a database access error occurs

bringDatabaseOnline

public void bringDatabaseOnline(byte operationMode)
                         throws 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:

SQLException - if a database access error occurs

markCorruptRecords

public void markCorruptRecords()
                        throws 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:

SQLException - if a database access error occurs

validateDatabase

public void validateDatabase()
                      throws 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:

SQLException - if a database access error occurs

validateDatabase

public void validateDatabase(int options)
                      throws 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:

SQLException - if a database access error occurs

setSweepThreshold

public void setSweepThreshold(int transactions)
                       throws 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:

SQLException - if a database access error occurs

sweepDatabase

public void sweepDatabase()
                   throws SQLException

Description copied from interface: MaintenanceManager

Perform an immediate sweep of the database.

Specified by:

sweepDatabase in interface MaintenanceManager

Throws:

SQLException - if a database access error occurs

activateShadowFile

public void activateShadowFile()
                        throws 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:

SQLException - if a database access error occurs

killUnavailableShadows

public void killUnavailableShadows()
                            throws 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:

SQLException - if a database access error occurs

limboTransactionsAsList

public List<Long> limboTransactionsAsList()
                                   throws 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:

SQLException - if a database access error occurs

getLimboTransactions

public long[] getLimboTransactions()
                            throws 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:

SQLException - if a database access error occurs

commitTransaction

public void commitTransaction(long transactionId)
                       throws 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:

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

rollbackTransaction

public void rollbackTransaction(long transactionId)
                         throws 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:

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

upgradeOds

public void upgradeOds()
                throws SQLException

Description copied from interface: MaintenanceManager

Perform minor ODS upgrade.

Requires Firebird 5.0 or higher.

Specified by:

upgradeOds in interface MaintenanceManager

Throws:

SQLException - if a database access error occurs

fixIcu

public void fixIcu()
            throws SQLException

Description copied from interface: MaintenanceManager

Update or rebuild ICU-dependent collations and indexes when ICU version changed.

Requires Firebird 3.0 or higher.

Specified by:

fixIcu in interface MaintenanceManager

Throws:

SQLException - if a database access error occurs