1.51.2

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 2.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 2.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 2.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 2.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: 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 2.0
See Also:
Driver.getBuildCertificationLevel()

getInterServerJDBCNetProtocolVersion

public int getInterServerJDBCNetProtocolVersion()
Get the JDBC/Net protocol used by InterServer.
Since:
Extension, proposed for InterClient 2.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 2.0
See Also:
DatabaseMetaData.getInterServerExpirationDate(), Driver.getExpirationDate()

getInterServerPort

public int getInterServerPort()
Get the JDBC/Net middleware server (InterServer) port.
Since:
Extension, proposed for InterClient 2.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 2.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 2.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 2.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 2.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

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:

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

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

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 2.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 2.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 2.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 2.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 2.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 2.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 2.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 2.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 2.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 2.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 2.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 2.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 2.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 2.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 2.0, not yet supported

1.51.2

Send comments or suggestions to interclient@interbase.com