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

Methods
`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.
`long[]` `getLimboTransactions()` Retrieve the ID of each limbo transaction as an array of longs.
`void` `killUnavailableShadows()` Remove references to unavailable shadow files.
`java.util.List<java.lang.Long>` `limboTransactionsAsList()` Retrieve the ID of each limbo transaction as a List of Long objects.
`void` `listLimboTransactions()` Deprecated.
`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` `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, createRequestBuffer, executeServicesOperation, executeServicesOperation, getAuthPlugins, getCharSet, getDatabase, getDbCryptConfig, getHost, getLogger, getPassword, getPort, getServerVersion, getServiceName, getUser, getWireCrypt, isWireCompression, queueService, setAuthPlugins, setCharSet, setDatabase, setDbCryptConfig, setHost, setLogger, setPassword, setPort, setUser, setWireCompression, setWireCrypt`

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

`getAuthPlugins, getCharSet, getDatabase, getDbCryptConfig, getHost, getLogger, getPassword, getPort, getServerVersion, getUser, getWireCrypt, isWireCompression, setAuthPlugins, setCharSet, setDatabase, setDbCryptConfig, setHost, setLogger, setPassword, setPort, setUser, setWireCompression, setWireCrypt`

### 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(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

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:
  `java.sql.SQLException` - if a database access error occurs

#### setDatabaseDialect

    public void setDatabaseDialect(int dialect)
                            throws java.sql.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:
  `java.sql.SQLException` - if a database access error occurs

#### setDefaultCacheBuffer

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

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:
  `java.sql.SQLException` - if a database access error occurs

#### setPageFill

    public void setPageFill(int pageFill)
                     throws java.sql.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:
  `java.sql.SQLException` - if a database access error occurs

#### shutdownDatabase

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

Description copied from interface: `MaintenanceManager`
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

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:
  `java.sql.SQLException` - if a database access error occurs

#### markCorruptRecords

    public void markCorruptRecords()
                            throws java.sql.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:
  `java.sql.SQLException` - if a database access error occurs

#### validateDatabase

    public void validateDatabase()
                          throws java.sql.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:
  `java.sql.SQLException` - if a database access error occurs

#### validateDatabase

    public void validateDatabase(int options)
                          throws java.sql.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:
  `java.sql.SQLException` - if a database access error occurs

#### setSweepThreshold

    public void setSweepThreshold(int transactions)
                           throws java.sql.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:
  `java.sql.SQLException` - if a database access error occurs

#### sweepDatabase

    public void sweepDatabase()
                       throws java.sql.SQLException

Description copied from interface: `MaintenanceManager`
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

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:
  `java.sql.SQLException` - if a database access error occurs

#### killUnavailableShadows

    public void killUnavailableShadows()
                                throws java.sql.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:
  `java.sql.SQLException` - if a database access error occurs

#### listLimboTransactions

    @Deprecated
    public void listLimboTransactions()
                               throws java.sql.SQLException

Deprecated.
Description copied from interface: `MaintenanceManager`
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

    public java.util.List<java.lang.Long> limboTransactionsAsList()
                                                           throws java.sql.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:
  `java.sql.SQLException` - if a database access error occurs

#### getLimboTransactions

    public long[] getLimboTransactions()
                                throws java.sql.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:
  `java.sql.SQLException` - if a database access error occurs

#### 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`, 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

    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`, 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