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