org.firebirdsql.management

Class FBMaintenanceManager

java.lang.Object

org.firebirdsql.management.FBServiceManager

org.firebirdsql.management.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

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 and Description
FBMaintenanceManager() Create a new instance of FBMaintenanceManager based on the default GDSType.
FBMaintenanceManager(org.firebirdsql.gds.impl.GDSType gdsType) Create a new instance of FBMaintenanceManager based on a given GDSType.
FBMaintenanceManager(java.lang.String gdsType) Create a new instance of FBMaintenanceManager based on a given GDSType.

Method Summary

Modifier and Type	Method and 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 new since Firebird 2.5.
void	commitTransaction(int transactionId) Deprecated.
void	commitTransaction(long transactionId) Commit a limbo transaction based on its ID.
int[]	getLimboTransactions() Deprecated. Will return long[] in 3.0
long[]	getLimboTransactionsAsLong() Deprecated. Will be renamed to getLimboTransactions() in 3.0
void	killUnavailableShadows() Remove references to unavailable shadow files.
java.util.List<java.lang.Integer>	limboTransactionsAsList() Deprecated. Will return List<Long> in 3.0
java.util.List<java.lang.Long>	limboTransactionsAsLongList() Deprecated. Will be renamed to limboTransactionsAsList() in 3.0
void	listLimboTransactions() Retrieve the ID of each limbo transaction.
void	markCorruptRecords() Mark corrupt records in the database as unavailable.
void	rollbackTransaction(int transactionId) Deprecated.
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 class org.firebirdsql.management.FBServiceManager

attachServiceManager, createRequestBuffer, detachServiceManager, executeServicesOperation, getDatabase, getGds, getHost, getLogger, getPassword, getPort, getServiceName, getUser, queueService, setDatabase, setHost, setLogger, setPassword, setPort, setUser

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.firebirdsql.management.ServiceManager

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

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(org.firebirdsql.gds.impl.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

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

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

Set the default page-buffer count to be cached in the database. The Firebird default is 2048.

Specified by:

setDefaultCacheBuffer in interface MaintenanceManager

Parameters:

pageCount - The number of pages to be cached, must be 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

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.

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

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

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

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

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

Bring a shutdown database online with enhanced operation modes new since Firebird 2.5.

Specified by:

bringDatabaseOnline in interface MaintenanceManager

Throws:

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

markCorruptRecords

public 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). This method is the equivalent of gfix -mend.

Specified by:

markCorruptRecords in interface MaintenanceManager

Throws:

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

validateDatabase

public 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.

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

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

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

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

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

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

public void listLimboTransactions()
                           throws java.sql.SQLException

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

@Deprecated
public java.util.List<java.lang.Integer> limboTransactionsAsList()
                                                                       throws java.sql.SQLException

Deprecated. Will return List<Long> in 3.0

Throws:

java.sql.SQLException

limboTransactionsAsLongList

@Deprecated
public java.util.List<java.lang.Long> limboTransactionsAsLongList()
                                                                        throws java.sql.SQLException

Deprecated. Will be renamed to limboTransactionsAsList() in 3.0

Throws:

java.sql.SQLException

getLimboTransactions

@Deprecated
public int[] getLimboTransactions()
                                        throws java.sql.SQLException

Deprecated. Will return long[] in 3.0

Throws:

java.sql.SQLException

getLimboTransactionsAsLong

@Deprecated
public long[] getLimboTransactionsAsLong()
                                               throws java.sql.SQLException

Deprecated. Will be renamed to getLimboTransactions() in 3.0

Throws:

java.sql.SQLException

commitTransaction

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

Deprecated.

Description copied from interface: MaintenanceManager

Commit a limbo transaction based on its ID.

Specified by:

commitTransaction in interface MaintenanceManager

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

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

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

Deprecated.

Description copied from interface: MaintenanceManager

Rollback a limbo transaction based on its ID.

Specified by:

rollbackTransaction in interface MaintenanceManager

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

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