Overview | Package | Class | Tree | Deprecated | Index | Help

3.00.12
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## interbase.interclient
Class ServerManager

    java.lang.Object
      |
      +--interbase.interclient.ServerManager

public final class ServerManager
extends Object

Provides a session for servicing an InterBase server.

A server manager object is obtained thru a `DataSource` using `DataSource.getServerManager()`. The DataSource property named `serverManagerHost` must be set using `DataSource.setServerManagerHost(hostName)`. See DataSource Properties for a list of other DataSource and Connection properties.

The ServerManager may be used for setting persistent database properties, and for making service requests on databases and the server as a whole. Use connection properties for configuring transient properties of a connection. Use the `DatabaseMetaData` class for querying persistent database properties in general.

See the InterClient Extension API for a complete list of available InterBase extensions to JDBC.

Since:
  Extension, proposed for InterClient 3.0

Method Summary
`void` | `activateShadow(String shadow)` Activate a database shadow file.
`void` | `addInterBaseLicense(String licenseKey, String licenseId)` Converts the license id and key to a valid license and adds it to the server's license file.
`void` | `addUser(String user, String password, Map userInformation)` Registers a user with the InterBase server.
`String` | `backup(String database, String[] backupFiles, int[] backupFileLengths, Map backupOptions)` Backs up a database to multiple backup files.
`String` | `backup(String database, String backupFile, Map backupOptions)` Backs up a database to a single backup file.
`void` | `bringOnline(String database)` Brings an offline database back online.
`void` | `clearWarnings()` After this call, getWarnings returns null until a new warning is reported for this ServerManager.
`void` | `close()` Close the server manager connection and release server manager resources.
`void` | `commitTransactions(String database, int[] transactionIds)` Attempt to commit limbo transactions.
`void` | `createDatabase(String database, Map databaseProperties)` Creates a single file database using the specified persistent database properties.
`void` | `createShadow(String database, String[] shadowFiles, int[] shadowFileLengths, Map shadowProperties)` Creates a multi-file shadow for a database.
`void` | `createShadow(String database, String shadow, Map shadowProperties)` Creates a single shadow file for a database.
`void` | `deleteDatabase(String database)` Remove the database file.
`void` | `deleteInterBaseLicense(String licenseKey)` Removes the license specified by the `licenseKey`.
`void` | `deleteShadow(String database)` Deletes the shadow file for a database.
`void` | `deleteUser(String user)` Removes a registered user.
`protected void` | `finalize()` A server manager connection will be closed when its finalizer is called by the garbage collector.
`String[]` | `getDatabasesInUse()` Gets the names of databases with current connections.
`String[][]` | `getInterBaseLicenses()` Gets all the InterBase license keys and IDs from the InterBase license file.
`String` | `getInterBaseVersion()` What's the version string for the InterBase server.
`int` | `getInterServerBuildCertificationLevel()` Gets the build certification level for this version of InterServer.
`int` | `getInterServerBuildNumber()` What's the build number for InterServer.
`Date` | `getInterServerExpirationDate()` Get the expiration date for the server side JDBC middleware server (InterServer).
`int` | `getInterServerJDBCNetProtocolVersion()` Get the JDBC/Net protocol used by InterServer.
`int` | `getInterServerMajorVersion()` What's the major version number for InterServer.
`int` | `getInterServerMinorVersion()` What's the minor version number for InterServer.
`int` | `getInterServerPort()` Get the JDBC/Net middleware server (InterServer) port.
`Object[]` | `getLimboTransactions(String database)` Gets limbo transaction information for the database.
`InputStream` | `getLockActivityStream(Map options)` Gets a continuous stream of InterBase lock activity from the server.
`int` | `getNumberOfInterBaseConnectionsInUse()` Returns the total number of database connections to the InterBase server.
`Map` | `getRegisteredUsers()` Returns registered user information as a map from username to a userInformation array object.
`String` | `getStatisticsText(String database, Map options)` Gets database statistics as a text string.
`SQLWarning` | `getWarnings()` The first warning reported by calls on this ServerManager is returned.
`void` | `modifyUser(String user, Map newUserInformation)` Change the user information for a registered user.
`void` | `modifyUser(String user, String newPassword)` Change the password for a registered user.
`String` | `repair(String database, Map repairOptions)` Validate and mend the database where possible.
`void` | `reserveSpaceForVersioning(String database, boolean reserveSpace)` Specify whether or not space is reserved on each newly created database page for anticipated record versions.
`String` | `restore(String backupFile, String[] databaseFiles, int[] databaseFileLengths, Map restoreOptions)` Restores a backup to multiple database files.
`String` | `restore(String backupFile, String database, Map restoreOptions)` Restores a backup to a single working database file.
`void` | `rollbackTransactions(String database, int[] transactionIds)` Rollback limbo transactions.
`void` | `setDatabaseCachePages(String database, int numCachePages)` Sets the number of cache page buffers to use for all connections to the specified `database`.
`void` | `setDatabaseReadWrite(String database, boolean readWrite)` Configure the database as read/write or read-only.
`void` | `setSweepInterval(String database, int interval)` Sets the periodicity of automatic garbage collection for the database.
`void` | `startInterBase(int defaultCachedPages, int defaultPageSize)` Start the InterBase service to allow for database connections.
`void` | `stopInterBase()` Stop the InterBase service.
`String` | `sweep(String database)` Manually sweep the database of old record versions.
`void` | `takeOffline(String database, boolean forceOffline, boolean blockNewConnections, boolean blockNewTransactions, int timeout)` Prevent further database connections or transactions, or force the shutdown of existing ones.
`void` | `twoPhaseCommitTransactions(String database, int[] transactionIds)` Attempt to resolve limbo transactions using the two-phase commit protocol.
`void` | `useSynchronousWrites(String database, boolean synchronous)` Enable or disable synchronous writes to disk on commit.
`String` | `verify(String database, Map verifyOptions)` Verifies the database's internal page structures.

Methods inherited from class java.lang.Object
`clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Method Detail

### getInterServerMajorVersion

    public int getInterServerMajorVersion()

  What's the major version number for InterServer.
  Returns:
    InterServer major version.
  Since:
    Extension, proposed for InterClient 3.0
  See Also:
    `DatabaseMetaData.getInterServerMajorVersion()`, `Driver.getMajorVersion()`

### getInterServerMinorVersion

    public int getInterServerMinorVersion()

  What's the minor version number for InterServer.
  Returns:
    InterServer minor version.
  Since:
    Extension, proposed for InterClient 3.0
  See Also:
    `DatabaseMetaData.getInterServerMinorVersion()`, `Driver.getMinorVersion()`

### getInterServerBuildNumber

    public int getInterServerBuildNumber()

  What's the build number for InterServer.
  Returns:
    InterServer build number.
  Since:
    Extension, proposed for InterClient 3.0
  See Also:
    `Driver.getBuildNumber()`

### getInterServerBuildCertificationLevel

    public int getInterServerBuildCertificationLevel()

  Gets the build certification level for this version of InterServer. The InterServer certification levels are as follows:
  - `Driver.testBuild` Test builds are experimental and uncertified with no level of quality assurance whatsoever.
  - `Driver.betaBuild` Beta builds are certified for quality assurance, but remain experimental.
  - `Driver.finalBuild` The highest level of build certification. A final build is certified for quality assurance, but is not experimental.
  These are not JDBC certification levels, rather they represent a level of quality assurance for a particular build of InterServer. So, for example, an InterServer version 2.0.1 may be a test build, and 2.0.21 may be a beta build, and 2.0.41 may be the final build.

  The progression from test, beta, to final build is not static functionally. That is, new functionality may be added to a beta build that does not exist in a test build, and likewise, there may be new functionality in a final build which does not exist in a beta build of the same version.

  Returns:
    the build certification level
  Since:
    Extension, proposed for InterClient 3.0
  See Also:
    `Driver.getBuildCertificationLevel()`

### getInterServerJDBCNetProtocolVersion

    public int getInterServerJDBCNetProtocolVersion()

  Get the JDBC/Net protocol used by InterServer.
  Since:
    Extension, proposed for InterClient 3.0
  See Also:
    `DatabaseMetaData.getInterServerJDBCNetProtocolVersion()`, `Driver.getJDBCNetProtocolVersion()`

### getInterServerExpirationDate

    public Date getInterServerExpirationDate()

  Get the expiration date for the server side JDBC middleware server (InterServer).
  Since:
    Extension, proposed for InterClient 3.0
  See Also:
    `DatabaseMetaData.getInterServerExpirationDate()`, `Driver.getExpirationDate()`

### getInterServerPort

    public int getInterServerPort()

  Get the JDBC/Net middleware server (InterServer) port.
  Since:
    Extension, proposed for InterClient 3.0
  See Also:
    `DatabaseMetaData.getInterServerPort()`

### getInterBaseVersion

    public String getInterBaseVersion()
                               throws SQLException

  What's the version string for the InterBase server.
  Returns:
    InterBase version string
  Throws:
    `SQLException` - if a database access error occurs.
  Since:
    Extension, proposed for InterClient 3.0, not yet supported
  See Also:
    `DatabaseMetaData.getDatabaseProductVersion()`

### getDatabasesInUse

    public String[] getDatabasesInUse()
                               throws SQLException

  Gets the names of databases with current connections. This includes both C and Java client connections.
  Returns:
    an array of database names
  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for InterClient 3.0, not yet supported

### getNumberOfInterBaseConnectionsInUse

    public int getNumberOfInterBaseConnectionsInUse()
                                             throws SQLException

  Returns the total number of database connections to the InterBase server. This includes both C and Java client connections.
  Returns:
    the total number of InterBase connections on server.
  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for InterClient 3.0, not yet supported

### getInterBaseLicenses

    public String[][] getInterBaseLicenses()
                                    throws SQLException

  Gets all the InterBase license keys and IDs from the InterBase license file. The InterBase server maintains a license file named `isc_license.dat`. This represents `iblicense -display` functionality. See the InterBase Operations Guide for details.
  Returns:
    an array of license key and license certificate id pairs.
  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for InterClient 3.0, not yet supported

### getRegisteredUsers

    public Map getRegisteredUsers()
                           throws SQLException

  Returns registered user information as a map from username to a userInformation array object. Users are registered in the InterBase `isc4.gdb`. This represents `gsec display` functionality. See the InterBase Operations Guide for details.

  The user information array object for each user in the map is a 5-tuple containing

  - firstName
  - middleName
  - lastName
  - unixUserId
  - unixGroupId

  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for for InterClient 2.0, not yet supported

### getLockActivityStream

    public InputStream getLockActivityStream(Map options)
                                      throws SQLException

  Gets a continuous stream of InterBase lock activity from the server. This represents `iblockpr` functionality. See the InterBase Operations Guide for details.

  Parameter `options` maps the following string-based keys: TBD.

  This method is a placeholder for possible future functionality.

  Returns:
    iblockpr info as an ascii stream.
  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for possible future release, not yet supported

### startInterBase

    public void startInterBase(int defaultCachedPages,
                               int defaultPageSize)
                        throws SQLException

  Start the InterBase service to allow for database connections. This represents `ibmgr -start` functionality. See the InterBase Operations Guide for details.

  `defaultPageSize` is the page size that will be used by the InterBase server when a new database is created. This affects the page size of a database created with the `createDatabase` method.

  `defaultCachedPages` suggests the number of cached pages the InterBase server will use for database attachments.

  Database cache is the number of memory pages reserved for each attached database. If the figure is set high enough to accommodate the page requirements for all attached databases, overall performance is maximized because all database activity can be handled in physical RAM rather than having it swapped to disk. If too many pages are reserved, however, and you have many databases running simultaneously, your request may exceed the amount of physical RAM available to the system. If that happens, some of your operations would be swapped to disk as the operating system tries to manage the excessive demands of your databases and the needs of other running applications.

  On Classic, the default number of pages cached is 75 for each connection. The minimum is 50 pages.

  On SuperServer, a single page buffer cache is allocated per database, and shared between connections. The default allocation is 256 cached pages.

  There are 3 ways to programmatically specify the number of cache pages:

  - Server-wide default: The default number of cache buffers to use for all database attachments.
    Note: This value is NOT stamped onto the database header page by `createDatabase`. If this default is not set, the default is 256 for SuperServer and 75 for Classic.
  - Database-wide: The number of cache buffers to use for attachments to a particular database may be stamped onto the database header page using `setDatabaseCachePages`. By default, `createDatabase` stamps a zero onto the database header page. If this value is non-zero, it takes precedence over both the server-wide and connection-wide settings.
  - Connection-wide: The number of cache pages may be set at connection-time using the `suggestedCachePages` connection property, or `DataSource.setSuggestedCachePages`, but this value is transient and not stamped onto the database header page. This transient setting takes precedence over the server-wide default, but not any database-wide setting.

  The number of cached database pages may also be set manually in the server's `ibconfig` file by assigning the configuration parameter `DATABASE_CACHE_PAGES`. This manual server-wide setting takes precedence over any programmatic server-wide setting, but is overriden by the database-wide and connection-wide programmatic settings.

  This method is a placeholder for possible future functionality.

  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for possible future release, not yet supported
  See Also:
    `DatabaseMetaData.getActualCachePagesInUse()`, `DatabaseMetaData.getPersistentDatabaseCachePages()`, `stopInterBase()`

### stopInterBase

    public void stopInterBase()
                       throws SQLException

  Stop the InterBase service. This represents `ibmgr -shut` functionality. See the InterBase Operations Guide for details.

  This command rolls back all active transactions and forces immediate shutdown of the server. Use with caution.

  This method is a placeholder for possible future functionality.

  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for possible future release, not yet supported
  See Also:
    `startInterBase(int, int)`

### addInterBaseLicense

    public void addInterBaseLicense(String licenseKey,
                                    String licenseId)
                             throws SQLException

  Converts the license id and key to a valid license and adds it to the server's license file. The InterBase server maintains a license file named `isc_license.dat`. This represents `iblicense -add` functionality. See the InterBase Operations Guide for details.

  The server will need to be restarted if the license being added changes the server from a local server to a remote server. This is necessary because the listener threads are started and allocated once the server starts up. If the license id and key being added simply adds user licenses to the server, no server restart is needed.

  This service can also be used to add evaluation licenses. Evaluation licenses, however, can not be removed using the ServerManager or any other means.

  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for InterClient 3.0, not yet supported

### deleteInterBaseLicense

    public void deleteInterBaseLicense(String licenseKey)
                                throws SQLException

  Removes the license specified by the `licenseKey`. The InterBase server maintains a license file named `isc_license.dat`. This represents `iblicense -remove -key` functionality. See the InterBase Operations Guide for details.

  The server will need to be restarted if the license being removed changes server's state from a remote server to a local server. This is necessary because the listener threads will need to be shut down to complete the operation and cannot be shutdown while the server is in use. If the license id and key being removed simply removes user licenses to the server, no server restart is needed.

  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for InterClient 3.0, not yet supported

### addUser

    public void addUser(String user,
                        String password,
                        Map userInformation)
                 throws SQLException

  Registers a user with the InterBase server. Registered users are stored in `isc4.gdb`. This represents `gsec add` functionality. See the InterBase Operations Guide for details.

  `userInformation` maps any of the following keys to String or Integer objects:

  `firstName`
    This represents `gsec add -fname` functionality. The first name of the user being added.
  `middleName`
    This represents `gsec add -mname` functionality. The middle name of the user being added.
  `lastName`
    This represents `gsec add -lname` functionality. The last name of the user being added.
  `unixUserId`
    An Integer switch representing `gsec add -uid` functionality.
  `unixGroupId`
    An Integer switch representing `gsec add -gid` functionality.

  All such properties are optional. Furthermore, the `userInformation` map itself may be null.

  When adding users to the security database, the only information required is the username and password and are restricted to ASCII characters. The information for first, middle, and last names are stored in Unicode.

  By default, only SYSDBA is allowed to add user information in the security database, however, no checks are made by this API to enforce this. Since this is strictly enforced at the database level, it is possible for SYSDBA to grant update priviledges to those fields that can be updatable by end users.

  The SQL role name used for this operation is the `roleName` property inherited from the `DataSource` that produced this ServerManager.

  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for InterClient 3.0, not yet supported

### deleteUser

    public void deleteUser(String user)
                    throws SQLException

  Removes a registered user. Registered users are stored in `isc4.gdb`. This represents `gsec delete` functionality. See the InterBase Operations Guide for details.

  Once a user has been removed from the security database, you will need to create a new user record using `addUser` before that user can connect to the server.

  By default, only SYSDBA is allowed to remove user information in the security database, however, no checks are made by this API to enforce this. This is strictly enforced at the database level. This would allow the SYSDBA to grant update priviledges to those fields that can be updatable by end-users.

  The SQL role name used for this operation is the `roleName` property inherited from the `DataSource` that produced this ServerManager.

  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for InterClient 3.0, not yet supported

### modifyUser

    public void modifyUser(String user,
                           Map newUserInformation)
                    throws SQLException

  Change the user information for a registered user. Registered users are stored in `isc4.gdb`. This represents `gsec modify` functionality. See the InterBase Operations Guide for details.

  `newUserInformation` maps any of the following keys to String or Integer objects:

  `password`
    This represents `gsec modify -pw` functionality. The new password of the user being modified.
  `firstName`
    This represents `gsec modify -fname` functionality. The new first name of the user being modified.
  `middleName`
    This represents `gsec modify -mname` functionality. The new middle name of the user being modified.
  `lastName`
    This represents `gsec modify -lname` functionality. The new last name of the user being modified.
  `unixUserId`
    An Integer switch representing `gsec modify -uid` functionality.
  `unixGroupId`
    An Integer switch representing `gsec modify -gid` functionality.

  Only information that has a corresponding parameter will be modified. To change the user name, that user must be removed from the security database and then re-added.

  By default only SYSDBA is allowed to modify user information in the security database. However, no checks are made by this API to enforce this. This is strictly enforced at the database level. This would allow SYSDBA to grant update priviledges to those fields that can be updatable by end-users.

  The SQL role name used for this operation is the `roleName` property inherited from the `DataSource` that produced this ServerManager.

  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for InterClient 3.0, not yet supported

### modifyUser

    public void modifyUser(String user,
                           String newPassword)
                    throws SQLException

  Change the password for a registered user.

  This method is less general than `modifyUser(user, newUserInformation)`, but is convenient for the common task of changing a user's password.

  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for InterClient 3.0, not yet supported

### reserveSpaceForVersioning

    public void reserveSpaceForVersioning(String database,
                                          boolean reserveSpace)
                                   throws SQLException

  Specify whether or not space is reserved on each newly created database page for anticipated record versions. True by default.

  This represents `gfix -use full`, and `gfix -use reserve` functionality.

  By default, an 80% fill ratio is used for newly created pages. If space reservation is disabled, then a 100% fill ratio is used.

  The default is to reserve space for back versions in a database. It's only if the database is mostly archival (read only loosely-speaking) that no reserve space is recommended.

  Since:
    Extension, proposed for InterClient 3.0, not yet supported
  See Also:
    `DatabaseMetaData.reservingSpaceForVersioning()`

### setDatabaseCachePages

    public void setDatabaseCachePages(String database,
                                      int numCachePages)
                               throws SQLException

  Sets the number of cache page buffers to use for all connections to the specified `database`. This is a persistent property of the database and is stamped onto the database header page. This represents `gfix -buffers` functionality. See the InterBase Operations Guide for details.

  This persistent property of the database overrides the `suggestedCachePages` connection property (see Connection Properties), and also overrides the server-wide default set by `DATABASE_CACHE_PAGES` in the InterBase `ibconfig` startup file or by `startInterBase(defaultCachePages, defaultPageSize)`.

  Upon connection, if a persistent database-wide cache pages property is not set, then the connection-wide setting is used if specified on connect, otherwise the server-wide default is used.

  By default, `createDatabase` stamps a zero onto the database header page. If this value is non-zero, it takes precedence over both the server-wide and connection-wide settings. A connection-wide setting may be established using the `suggestedCachePages` connection property, see Connection Properties, or by `DataSource.setSuggestedCachePages`. A server-wide setting may be established using `DATABASE_CACHE_PAGES` in the InterBase `ibconfig` startup file or by `startInterBase(defaultCachedPages, defaultPageSize)`.

  The SuperServer architecture allocates a separate page buffer cache per database.

  There is an absolute limitation of MAX_PAGE_BUFFERS (65535) pages imposed by InterBase code. So the cache memory size for a database cannot go beyond a maximum of MAX_PAGE_BUFFERS*PageSize bytes which amounts to 512MB for an 8K page size. 8K here is the maxiumum database page size currently allowed. If this property is 0 or unspecified, and there is no server-wide or database-wide default set, the default pages used is 256 cache pages.

  Since:
    Extension, proposed for InterClient 3.0, not yet supported
  See Also:
    `DatabaseMetaData.getActualCachePagesInUse()`, `DatabaseMetaData.getPersistentDatabaseCachePages()`

### setDatabaseReadWrite

    public void setDatabaseReadWrite(String database,
                                     boolean readWrite)
                              throws SQLException

  Configure the database as read/write or read-only. True by default. This is a persistent property of the database and is stamped onto the database header page. `gfix` flag for this functionality to be determined. See the InterBase Operations Guide for details.

  By default, a database is read/write.

  Since:
    Extension, proposed for InterClient 3.0, not yet supported
  See Also:
    `DatabaseMetaData.isDatabaseReadWrite()`

### setSweepInterval

    public void setSweepInterval(String database,
                                 int interval)
                          throws SQLException

  Sets the periodicity of automatic garbage collection for the database. This represents `gfix -housekeeping interval` functionality. See the InterBase Operations Guide for more details.

  The default sweep interval is 20,000.

  To turn off automatic sweeping altogether, set the sweep interval to 0.

  Since:
    Extension, proposed for InterClient 3.0, not yet supported
  See Also:
    `DatabaseMetaData.getSweepInterval()`

### useSynchronousWrites

    public void useSynchronousWrites(String database,
                                     boolean synchronous)
                              throws SQLException

  Enable or disable synchronous writes to disk on commit. This represents `gfix -write {sync | async}` functionality. See the InterBase Operations Guide for more details.

  If writes are asynchronous then data may not be physically written to disk on a database write, since operating systems buffer disk writes. If there is a system failure before the data is written to disk, then information can be lost.

  Performing synchronous writes ensures data integrity and safety, but slower performance. In particular, operations which involve data modification are slower.

  There are two significant shortcomings of using asynchronous writes:

  - When a transaction is committed, pages will be written to the OS cache, but we will not wait for them to be written to disk before returning from the commit with a success status.
  - The "careful write" strategy is defeated. We write pages to disk in such a way that what's on disk is always logically consistent. If asynchronous writes are specified, we still write pages out to the OS cache in this order, but the OS will probably write them to disk in a different order to optimize disk seeks.

  So there are risks for database corruption if async writes are being used. The window of risk is the amount of time it takes your OS to write pages to disk once we have written them out to the OS cache. While this may seem like a small window, imagine a system under full load, pages being constantly updated. At any given time you may lose power, and certain pages will not be written out, or even worse pages may be written which expect the presence of other pages.

  Sometimes the loss of a page is easily recoverable, such as when a new record is added to a data page. You will merely lose that new record. Other times the damage could be more severe. Some things can be fixed by gfix -mend. If that doesn't work, sometimes data can be recovered from a damaged database by copying it to another database one table at a time. But you do have to face the possibility of complete non-recovery of the database, though this is relatively rare.

  So to be safe, those using asynchronous write should use a UPS, or at the very least take a backup once a day and be prepared, in the worst case, to lose that day's changes.

  Since:
    Extension, proposed for InterClient 3.0, not yet supported
  See Also:
    `DatabaseMetaData.usingSynchronousWrites()`

### takeOffline

    public void takeOffline(String database,
                            boolean forceOffline,
                            boolean blockNewConnections,
                            boolean blockNewTransactions,
                            int timeout)
                     throws SQLException

  Prevent further database connections or transactions, or force the shutdown of existing ones. This incorporates `gfix -shut -force timeout`, `gfix -shut -attach timeout`, and `gfix -shut -tran timeout` functionality. See the InterBase Operations Guide for details.

  During the timeout period, new connections and/or transactions may be prevented from starting. If the `forceOffline` option is disabled, then at the end of the specified `timeout` period, if there are still open connections, this method is aborted and the database is not taken offline.

  If the `forceOffline` option is enabled, then at the end of the timeout period any open transactions are rolled back, connections are disconnected, and the database is taken offline. This option should only be used as a last resort.

  To force an immediate database shutdown, specify `forceOffline` with a `timeout` period of 0.

  Only the SYSDBA user or the database owner may invoke this method. Once a database is offline, sysdba or the database owner may connect to the offline database and operate on it in the normal fashion. Other users will be denied access.

  Periodically you will want to shut down a database for backups and restores. Backup saves only the current committed version of each record while also putting all the data for each relation on contiguous pages in the database. Restore will rebuild all the indices and reset the statistics for each. This usually will increase performance significantly.

  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for InterClient 3.0, not yet supported

### bringOnline

    public void bringOnline(String database)
                     throws SQLException

  Brings an offline database back online. This represents `gfix -online` functionality. See the InterBase Operations Guide for more details.
  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for InterClient 3.0, not yet supported

### backup

    public String backup(String database,
                         String[] backupFiles,
                         int[] backupFileLengths,
                         Map backupOptions)
                  throws SQLException

  Backs up a database to multiple backup files. This represents `gbak -backup_database` functionality. See the InterBase Operations Guide for details.

  Parameter `backupOptions` maps any of the following String-based keys to String, Boolean, or Integer objects:

  `tapeDeviceBlockingFactor`
    An Integer switch for `gbak -backup_database -factor n`. Use blocking factor n for a tape device.
  `nonTransportable`
    A Boolean switch for `gbak -backup_database -nt`. Create a non-transportable backup which may not be restored on another machine architecture. By default, `gbak -backup_database -transportable` is used to produce an architecture independent backup file in XDR format.
  `ignoreLimboTransactions`
    A Boolean switch for `gbak -backup_database -limbo`. Ignore limbo transactions during backup.
  `ignoreChecksums`
    A Boolean switch for `gbak -backup_database -ignore`. Ignore checksums during backup.
  `metaDataOnly`
    A Boolean switch for `gbak -backup_database -metadata`. Backup metadata only, no data.
  `inhibitGarbageCollection`
    A Boolean switch for `gbak -backup_database -garbage_collect`. Do not garbage collect during backup.
  `convertExternalFilesToInternalTables`
    A Boolean switch for `gbak -backup_database -convert`. Convert external files as internal tables.
  `verbose`
    A Boolean switch for `gbak -backup_database -verify`. Report details of the backup process. This is the return value of the backup method.
  `oldDescriptions`
    A Boolean switch for `gbak -backup_database -old_descriptions`. Backup metadata in old-style format.

  All such configuration information is optional. Furthermore, the `backupOptions` map itself may be null.

  All boolean options are `false` by default.

  The user name and password used to obtain the ServerManager will be used to connect to the database for backup. This helps add some degree of security for this operation. Only SYSDBA or the database owner will be able to backup a database.

  The SQL role name used for this operation is the `roleName` property inherited from the `DataSource` that produced this ServerManager.

  Under normal circumstances, when backing up a database, the backup file will always be located on the InterBase server machine since the backup service cannot open a file over a network connection. The backup service can create a remote file if the following conditions are true:

  - The InterBase server is running on Windows NT.
  - The path to the backup file is specified as a UNC name.
  - The destination for the file is another Windows NT machine or a machine which can be connected to via UNC naming conventions.
  OR the destination drive is mounted via NFS (or some equivalent) on the machine running the InterBase server.
  Returns:
    textual information concerning the restore
  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for InterClient 3.0, not yet supported
  See Also:
    `backup(String,String,java.util.Map)`

### backup

    public String backup(String database,
                         String backupFile,
                         Map backupOptions)
                  throws SQLException

  Backs up a database to a single backup file.

  See the more general `backup(database, backupFiles[], fileLengths[], infoMap)` for details.

  Returns:
    textual information concerning the restore
  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for InterClient 3.0, not yet supported

### restore

    public String restore(String backupFile,
                          String[] databaseFiles,
                          int[] databaseFileLengths,
                          Map restoreOptions)
                   throws SQLException

  Restores a backup to multiple database files. This represents `gbak -c[reate_database]` or `gbak -r[eplace_database]` functionality. See the InterBase Operations Guide for details.

  Parameter `restoreOptions` maps any of the following String-based keys to String, Boolean, or Integer objects:

  `replaceDatabase`
    A Boolean switch for `gbak -r[eplace_database]`. Restore database to new file or replace existing file. By default `gbak -c[reate_database]` functionality is used so that you can restore to a new file only; an existing database file is not replaced.
  `pageSize`
    An Integer switch for `gbak {-r|-c} -page_size`. The default is 1024 (1K).
  `cachePages`
    An Integer switch for `gbak {-r|-c} -buffers`. See `setDatabaseCachePages()`.
  `deactivateIndices`
    A Boolean switch for `gbak {-r|-c} -inactive`.
  `dropValidityConstraints`
    A Boolean switch for `gbak {-r|-c} -novalidity`. Do not restore validity constraints when restoring metadata; allows restoration of data that would otherwise not meet validity constraints.
  `noShadow`
    A Boolean switch for `gbak {-r|-c} -kill`. Do not restore metadata references to shadows that were previously defined. Subsequent database operations will not be shadowed.
  `oneTableAtATime`
    A Boolean switch for `gbak {-r|-c} -one_at_a_time`. Restore one table at a time. This is useful for partial recovery of a database that contains corrupt data.
  `verbose`
    A Boolean switch for `gbak {-r|-c} -verify`. Report details of the restore. This is the return value of the restore method.
  `reserveNoSpaceForVersioning`
    A Boolean switch for `gbak {-r|-c} -use_all_space`. See `reserveSpaceForVersioning()`.

  All such configuration information is optional. Furthermore, the `restoreOptions` map itself may be null.

  All boolean options are `false` by default.

  The user name and password inherited from the `DataSource` used to obtain this ServerManager is used to connect to the database for restore. This adds some degree of security for this operation.

  The SQL role name used for this operation is the `roleName` property inherited from the `DataSource` that produced this ServerManager.

  Returns:
    textual information concerning the restore
  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for InterClient 3.0, not yet supported

### restore

    public String restore(String backupFile,
                          String database,
                          Map restoreOptions)
                   throws SQLException

  Restores a backup to a single working database file.

  See the more general `restore(backupFile, databaseFiles[], fileLengths[], infoMap)` for details.

  Returns:
    textual information concerning the restore
  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for InterClient 3.0, not yet supported

### sweep

    public String sweep(String database)
                 throws SQLException

  Manually sweep the database of old record versions. This represents `gfix -sweep` functionality. See the InterBase Operations Guide for details.

  Sweep does not require exclusive access, but if there are no active transactions on the database, then sweep can update certain data and transaction state information.

  Returns:
    textual information about the sweep
  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for InterClient 3.0, not yet supported
  See Also:
    `setSweepInterval(java.lang.String, int)`

### verify

    public String verify(String database,
                         Map verifyOptions)
                  throws SQLException

  Verifies the database's internal page structures. Also checks the database for checksum errors, and unassigned or corrupt pages. This represents `gfix -validate -no_update` functionality, with other switches specified in the `verifyOptions` map. No database structures are updated. See the InterBase Operations Guide for details.

  Parameter `verifyOptions` maps any of the following String-based keys to Boolean objects:

  `full`
    A Boolean switch for `gfix -validate -noupdate -full`. This validate all records. Without full validation, only page structures will be validated, which does involve some limited checking of records.
  `ignoreChecksums`
    A Boolean switch for `gfix -validate -noupdate -ignore`

  All such configuration information is optional. Furthermore, the `verifyOptions` map itself may be null.

  This method will attempt to obtain exclusive access to the database. Verification requires exclusive access to ensure that database structures are not modified during validation. If there are other connections to the database, a SQLException will be thrown and the connection refused.

  Returns:
    textual information detailing the verification
  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for InterClient 3.0, not yet supported

### repair

    public String repair(String database,
                         Map repairOptions)
                  throws SQLException

  Validate and mend the database where possible. Orphaned pages will be released, and allocated pages not in use will be freed. In addition, if any inconsistencies are found then an attempt is made to mend the database to make it viable for reading, but is not guaranteed to retain data. This represents `gfix -validate -mend` functionality. See the InterBase Operations Guide for details.

  Note: Clearly this cannot repair all corrupt databases in general.

  Parameter `repairOptions` maps any of the following String-based keys to Boolean objects:

  `full`
    A Boolean switch for `gfix -validate -mend -full`. Validate and mend record fragments. Without full validation, only page structures will be validated, which does involve some limited checking of records.
  `ignoreChecksums`
    A Boolean switch for `gfix -validate -mend -ignore`.
  `killShadows`
    A Boolean switch for `gfix -validate -mend -kill`.. Drops any shadow files associated with the database.
  `sweep`
    A Boolean switch for `gfix -validate -mend -sweep`. Sweeps the database.

  All such configuration information is optional. Furthermore, the `repairOptions` map itself may be null.

  This method will attempt to obtain exclusive access to the database. Verification and repair requires exclusive access to ensure that database structures are not modified during validation. If there are other connections to the database, a SQLException will be thrown and the connection refused.

  Returns:
    textual information detailing the reparations
  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for InterClient 3.0, not yet supported

### createShadow

    public void createShadow(String database,
                             String[] shadowFiles,
                             int[] shadowFileLengths,
                             Map shadowProperties)
                      throws SQLException

  Creates a multi-file shadow for a database.

  Shadows are carbon copies of the database, and may be used as a protection against hardware failures by setting up a shadow file on a separate disk partition or even a separate machine from the database file. If your primary disk or server fails, the shadow file may be activated for use as a regular database file by using `activateShadow(shadowFile)`. On activation, the shadow is no longer a shadow but becomes a regular database file. Users may then reconnect to the activated shadow file as a regular database file. Recovering in this way from a shadow file is quicker than restoring from a backup.

  Shadows can be composed of multiple files just like normal databases.

  A drawback to using shadows is that it doubles the number of writes the database server must perform.

  Parameter `shadowProperties` maps any of the following String-based keys to Integer objects:

  `pageSize`
    The shadow file page size.

  All such properties are optional. Furthermore, the `shadowProperties` map itself may be null.

  See the InterBase Operations Guide for further details on shadows.

  This method is a placeholder for possible future API functionality. Currently a shadow file may only be created by executing the SQL command `CREATE SHADOW` on a connection to the database.

  Reviewers Note: Are there other shadow properties that should be specified?

  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for possible future release, not yet supported

### createShadow

    public void createShadow(String database,
                             String shadow,
                             Map shadowProperties)
                      throws SQLException

  Creates a single shadow file for a database.

  See the more general `createShadow(database, shadowFiles[], lengths[], shadowProperties)` for details.

  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for possible future release, not yet supported

### activateShadow

    public void activateShadow(String shadow)
                        throws SQLException

  Activate a database shadow file. Once activated, the shadow file becomes a regular database file. This represents `gfix -activate` functionality. See the InterBase Operations Guide for details.

  Warning: Be sure the main database is offline with no attachments before activating its shadow. If a shadow is activated while the main database is online the shadow can be corrupted by existing attachments to the main database.

  See the InterBase Operations Guide for further details on shadows.

  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for InterClient 3.0, not yet supported

### deleteShadow

    public void deleteShadow(String database)
                      throws SQLException

  Deletes the shadow file for a database. This represents `gfix -kill` functionality. See the InterBase Operations Guide for details.

  A shadow file may also be deleted by executing the SQL command `DROP SHADOW` on a connection to the database.

  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for InterClient 3.0, not yet supported

### createDatabase

    public void createDatabase(String database,
                               Map databaseProperties)
                        throws SQLException

  Creates a single file database using the specified persistent database properties.

  Parameter `databaseProperties` maps any of the following String-based keys to Boolean or Integer objects:

  `pageSize`
    The page size of the new database.
  `reserveSpaceForVersioning`
    See `reserveSpaceForVersioning(database, boolean)`.
  `useSynchronousWrites`
    See `useSynchronousWrites(database, boolean)`.
  `cachePages`
    See `setDatabaseCachePages(database, int)`.
  `sweepInterval`
    See `setSweepInterval(database, int)`.

  All such properties are optional. Furthermore, the `databaseProperties` map itself may be null. All boolean configurables default to `true`, the page size defaults to 1024 (1K), the sweep interval defaults to 20,000, and the `cachePages` default stamped onto the database header page is 0. The server-wide defaults for page size and cache pages can be configured using `DATABASE_CACHE_PAGES` in the InterBase `ibconfig` startup file or when starting the server dynamically with `ServerManager.startInterBase(defaultCachePages, defaultPageSize)`.

  Note: The SQL string `CREATE DATABASE ...` cannot be executed with InterClient because SQL is executed within the context of a Connection in JDBC. Connectionless SQL is not allowed.

  Reviewers Note: Do we need sqlDialect as an option as well?

  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for InterClient 3.0, not yet supported

### deleteDatabase

    public void deleteDatabase(String database)
                        throws SQLException

  Remove the database file. This method will fail if there are any connections to the database.
  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for InterClient 3.0, not yet supported

### getLimboTransactions

    public Object[] getLimboTransactions(String database)
                                  throws SQLException

  Gets limbo transaction information for the database. This represents `gfix -list` functionality. See the InterBase Operations Guide for more details.

  The `object[]` array returned contains the following information: TBD.

  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for future release, not yet supported

### rollbackTransactions

    public void rollbackTransactions(String database,
                                     int[] transactionIds)
                              throws SQLException

  Rollback limbo transactions. This represents `gfix -rollback` functionality. See the InterBase Operations Guide for more details.
  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for future release, not yet supported

### commitTransactions

    public void commitTransactions(String database,
                                   int[] transactionIds)
                            throws SQLException

  Attempt to commit limbo transactions. This represents `gfix -commit` functionality. See the InterBase Operations Guide for more details.
  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for future release, not yet supported

### twoPhaseCommitTransactions

    public void twoPhaseCommitTransactions(String database,
                                           int[] transactionIds)
                                    throws SQLException

  Attempt to resolve limbo transactions using the two-phase commit protocol. This represents `gfix -two_phase` functionality. See the InterBase Operations Guide for more details.
  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for future release, not yet supported

### getStatisticsText

    public String getStatisticsText(String database,
                                    Map options)
                             throws SQLException

  Gets database statistics as a text string. This represents `gstat` functionality. See the InterBase Operations Guide for details.

  Parameter `options` maps the following string-based keys to Boolean objects:

  `header`
    A Boolean switch representing `gstat -header` functionality. Stop reporting statistics after reporting the information on the header page. False by default.
  `log`
    A Boolean switch representing `gstat -log` functionality. Stop reporting statistics after reporting the information on the log pages. False by default.
  `index`
    A Boolean switch representing `gstat -index` functionality. Retrieve and display statistics on indexes in the database. True by default.
  `data`
    A Boolean switch representing `gstat -data` functionality. Retrieve and display statistics on data tables in the database. True by default.
  `system`
    A Boolean switch representing `gstat -system` functionality. Retrieve statistics on system tables and indexes in addition to user tables and indices. False by default.

  Reading header information would normally not require that the server be running. However, in order to read the header information using this API, the server must be running as the logic for doing this is not in the client.

  Only the SYSDBA user or the database owner may run this service.

  This method is a placeholder for possible future functionality.

  Returns:
    statistical information as flat text
  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for future release, not yet supported

### getWarnings

    public SQLWarning getWarnings()
                           throws SQLException

  The first warning reported by calls on this ServerManager is returned. Subsequent warnings are chained to this SQLWarning.
  Returns:
    the first SQLWarning or null
  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for InterClient 3.0, not yet supported

### clearWarnings

    public void clearWarnings()
                       throws SQLException

  After this call, getWarnings returns null until a new warning is reported for this ServerManager.
  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for InterClient 3.0, not yet supported

### finalize

    protected void finalize()
                     throws Throwable

  A server manager connection will be closed when its finalizer is called by the garbage collector. However, there is no guarantee that the garbage collector will ever run, and in general will not run when an application terminates abruptly without closing its server connections.

  Therefore, it is recommended that server manager connections be explicitly closed even if your application throws an exception. This can be achieved by placing a call to close() in a finally clause of your application as follows

       try {
         ...
       }
       finally {
         if (serverManager != null)
           try { serverManager.close (); } catch (SQLException e) {}
       }

  Or alternatively, use the `System.runFinalizersOnExit(boolean)` method.

  Overrides:
    `finalize` in class `Object`
  Since:
    Extension, proposed for InterClient 3.0

### close

    public void close()
               throws SQLException

  Close the server manager connection and release server manager resources.

  In most cases, it is desirable to immediately release a ServerManager connection instead of waiting for it to be automatically released; the `close` method provides this immediate release.

  Note: A ServerManager connection is automatically closed when it is garbage collected. Certain fatal errors also result in a closed ServerManager.

  Throws:
    `SQLException` - if a server access error occurs
  Since:
    Extension, proposed for InterClient 3.0, not yet supported

Overview | Package | Class | Tree | Deprecated | Index | Help

3.00.12
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Send comments or suggestions to interclient@borland.com