|
1.50.39 | ||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object | +--interbase.interclient.Server
Represents a server session for administering an InterBase server.
Driver.getServer(java.lang.String, java.util.Properties)| Method Summary | |
void |
activateIndices(String database,
boolean activate)
Toggle use of database indices. |
void |
addUser(String user,
String password)
Register a user in isc4.gdb |
void |
backup(boolean transportable,
boolean ignoreLimboTransactions,
boolean ignoreChecksums,
boolean metaDataOnly,
boolean inhibitGarbageCollection,
String database,
String backupFile)
Backup a database. |
void |
backup(boolean transportable,
String database,
String backupFile)
Backup a database. |
void |
changePassword(String user,
String newPassword)
Change the password for a registered user in isc4.gdb. |
void |
clearWarnings()
After this call, getWarnings returns null until a new warning is reported for this Server. |
void |
close()
In some cases, it is desirable to immediately release a Server connection instead of waiting for them to be automatically released; the close method provides this immediate release. |
void |
commitLimboTransaction(String database,
int transactionId)
Attempt to commit a limbo transaction. |
void |
createDatabase(String database)
Create a database using the default page size and cache buffers. |
void |
createDatabase(String database,
int pageSize,
int cacheBuffers,
String[] secondaryFiles,
int[] lengths)
Create a database using the specified page size and stamp the number of cache buffers to use for this database onto the database header page. |
void |
createShadow(String database,
String shadowURL)
Create a database shadow file for the database. |
void |
createShadow(String database,
String shadowURL,
int pageSize)
Create a database shadow file for the database. |
void |
createShadow(String database,
String shadowURL,
int pageSize,
String[] secondaryFiles,
int[] lengths)
Create a database shadow for a multi-file database. |
void |
deregister(String database)
Remove a registered database from isc4.gdb |
void |
dropDatabase(String database)
Remove the database file, and degregister it. |
void |
dropShadow(String shadowURL)
Delete a database shadow file. |
void |
dropUser(String user)
Remove a registered user from isc4.gdb |
void |
enableAutomaticSweeping(String database,
boolean on)
Enable/disable automatic housekeeping of old record versions. |
protected void |
finalize()
A server will be closed when its finalizer is called by the garbage collector. |
int |
getBuildCertificationLevel()
Gets the build certification level for this version of InterServer. |
int |
getBuildNumber()
What's the build number for InterServer. |
int |
getCacheBuffers(String database)
Get the suggested number of cache page buffers to use for a database. |
int |
getDefaultCacheBuffers()
Get the default suggested number of cache buffers the server will use for database attachments. |
int |
getDefaultPageSize(int pageSize)
Get the default page size that will be used by the createDatabase() method. |
Date |
getExpirationDate()
Get the expiration date for the server side JDBC middleware server (InterServer). |
int |
getJDBCNetProtocolVersion()
Get the JDBC/Net protocol used by InterServer. |
int[] |
getLengths(String database)
Get the lengths of all secondary files for a multi-file database. |
int[] |
getLimboTransactionIds(String database)
Get the limbo transactions for the database. |
InputStream |
getLockActivity(String database)
Get a continuous stream of InterBase lock activity for the database. |
int |
getMajorVersion()
What's the major version number for InterServer. |
int |
getMinorVersion()
What's the minor version number for InterServer. |
int |
getPort()
Get the JDBC/Net middleware server (InterServer) port. |
String[] |
getRegisteredDatabases()
Returns an array of database files registered in isc4.gdb. |
String[] |
getSecondaryFiles(String database)
Get the secondary files for a multi-file database. |
ServerStatistics |
getStatistics()
Get server-wide statistics accumulated since the InterBase service started. |
String[] |
getUsers()
Returns an array of users registered in isc4.gdb. |
String[] |
getUsersConnected()
Returns an array of users currently connected to server. |
String[] |
getUsersConnected(String database)
Returns an array of users currently connected to database. |
SQLWarning |
getWarnings()
The first warning reported by calls on this Server is returned. |
boolean |
isClosed()
Is the server connection closed. |
void |
limitNumberOfConnections(String database,
int maxUsers)
Limit the number of connections to a database. |
void |
markAsDamaged(String database)
Mark the database as damaged. |
void |
move(String database,
String newDatabase)
Change the name or physical location of a database. |
void |
register(String database)
Register a database in isc4.gdb |
void |
repair(String database)
Release unassigned pages and record fragments. |
void |
restore(String backupFile,
String database)
Restore a database from a backup file. |
void |
restore(String backupFile,
String database,
int pageSize,
String[] secondaryFiles,
int[] lengths)
Restore a database from a backup file. |
void |
restore(String backupFile,
String database,
int pageSize,
String[] secondaryFiles,
int[] lengths,
boolean inactivateIndices,
boolean dropValidityConstraints,
boolean dropShadow,
boolean incremental,
String[] tables)
Restore a database from a backup file. |
void |
rollbackLimboTransaction(String database,
int transactionId)
Rollback a limbo transaction. |
void |
setCacheBuffers(String database,
int buffers)
Set the suggested number of cache page buffers to use for a database. |
void |
setSweepInterval(String database,
int num)
Set the sweep interval for automatic sweeping. |
void |
shutdown()
Shut down the InterBase service. |
void |
shutdown(String database,
boolean force,
boolean blockNewConnections,
boolean blockNewTransactions,
int timeout)
Prevent further database connections or transactions, or force the shutdown of existing ones. |
void |
startup(ServerProperties properties)
Start the InterBase service to allow for database connections. |
void |
sweep(String database)
Manually sweep the database of old record versions. |
void |
twoPhaseCommitLimboTransactions(String database)
Attempt to resolve all limbo transactions using two-phase commit. |
void |
verify(String database)
Check the database for checksum errors, and unassigned or corrupt pages. |
| Methods inherited from class java.lang.Object |
clone,
equals,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait |
| Method Detail |
public int getMajorVersion()
throws SQLException
DatabaseMetaData.getServerMajorVersion(),
Driver.getMajorVersion()public int getMinorVersion()
throws SQLException
DatabaseMetaData.getServerMinorVersion(),
Driver.getMinorVersion()public int getBuildNumber()
throws SQLException
Driver.getBuildNumber()public int getBuildCertificationLevel()
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.
Driver.getBuildCertificationLevel()public int getJDBCNetProtocolVersion()
throws SQLException
DatabaseMetaData.getServerJDBCNetProtocolVersion(),
Driver.getJDBCNetProtocolVersion()public Date getExpirationDate()
throws SQLException
DatabaseMetaData.getServerExpirationDate(),
Driver.getExpirationDate()public int getPort()
throws SQLException
DatabaseMetaData.getServerPort()public void startup(ServerProperties properties)
throws SQLException
public void shutdown()
throws SQLException
public void shutdown(String database,
boolean force,
boolean blockNewConnections,
boolean blockNewTransactions,
int timeout)
throws SQLException
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.
public void createDatabase(String database)
throws SQLException
Registers the database automatically.
ServerProperties.setDefaultPageSize(int)public void createDatabase(String database,
int pageSize,
int cacheBuffers,
String[] secondaryFiles,
int[] lengths)
throws SQLException
public void dropDatabase(String database)
throws SQLException
public String[] getRegisteredDatabases()
throws SQLException
public void register(String database)
throws SQLException
public void deregister(String database)
throws SQLException
public void addUser(String user,
String password)
throws SQLException
public void dropUser(String user)
throws SQLException
public void changePassword(String user,
String newPassword)
throws SQLException
public String[] getUsers()
throws SQLException
public String[] getUsersConnected()
throws SQLException
public String[] getUsersConnected(String database)
throws SQLException
public void backup(boolean transportable,
String database,
String backupFile)
throws SQLException
Backup always stores the database backup to a single gbak file. Garbage collection of old record versions is performed by default.
public void backup(boolean transportable,
boolean ignoreLimboTransactions,
boolean ignoreChecksums,
boolean metaDataOnly,
boolean inhibitGarbageCollection,
String database,
String backupFile)
throws SQLException
Issues a SQLWarning for checksum errors and limbo transactions
public void restore(String backupFile,
String database)
throws SQLException
public void restore(String backupFile,
String database,
int pageSize,
String[] secondaryFiles,
int[] lengths)
throws SQLException
secondaryFiles argument may be null if you're only changing pageSize.
public void restore(String backupFile,
String database,
int pageSize,
String[] secondaryFiles,
int[] lengths,
boolean inactivateIndices,
boolean dropValidityConstraints,
boolean dropShadow,
boolean incremental,
String[] tables)
throws SQLException
If the tables argument is non-null then restore only those tables.
The database page size decides how much data will be retrieved with one logical access from the database. The default is 1K (1024 bytes) with 2K, 4K, and 8K the other allowed values. A single logical access from the database may involve multiple physical accesses. For example, on most UNIX systems, the default number of bytes retrieved in a single physical access is 512. For a 1K page size, two physical accesses occur for every logical access. There is a tradeoff then between reading/writing the most data versus physical I/O. The proper page size will be determined by your database requirements, i.e., is the database mostly for reading, update intensive, or a combination? Is accessing BLOBS or ARRAYS a priority? What is the record size of your main table, the table that will be accessed most often?
Database page size will also influence the tuning of indices. The section on performance monitoring will review the tool called gstat that can analyze the layout of an index. If there are too many levels in the index then increasing the page size will flatten the index structures and usually improve performance. Another rule of thumb is to try to keep the indices on the main table to three or fewer levels.
The only way to change the database's page size after creation is to backup and then restore the database with a different page size. Page 110 in the Windows Client User's Guide details how to do this. Note that databases on Windows 3.1 and Windows NT can only have a page size of 1024.
The database can also be made up of many different files. This allows you to effectively use the available disk space on multiple volumes. The user always refers to the first file, the database name, and never has to know about the secondary files. This also allows a database to be larger than the operating system limit for a single file. This does not allow the DBA to specify in which file individual objects in the database may be placed. In other words, you cannot assign Relation A to the first file, Relation B to the second file and the indices for both to the third file. The files are used and filled in sequential order and can contain data from any table or index in the database.
The only way to change the number of database files after creation is to backup and then restore the database specifying the secondary files and the attributes. Page 109 in the Windows Client User's Guide details how to do this.
public void activateIndices(String database,
boolean activate)
throws SQLException
public void move(String database,
String newDatabase)
throws SQLException
Note: Move cannot be used to split a database or change its page size; Backup and restore must be used to split a database into multiple files or change its page size.
public void enableAutomaticSweeping(String database,
boolean on)
throws SQLException
Sweeping can be performed manually or automatically. By default, when the OIT is 20,001 transactions less then the Next Transaction number, which is also kept on the database header page, the process that tried to start the transaction will sweep the entire database and remove as many BDRs as possible. While this is happening, other users can continue to use the database.
If you are going to start the sweep manually then it is advised that you first make sure there is no one connected to the database. This will not only clean out the BDRs and clean out the erased records, but also update the OIT number on the header page to be one less than the Next Transaction number. It can do this because there are no other active transactions that might need to see any of the BDRs.
sweep(java.lang.String)public void sweep(String database)
throws SQLException
Even with our efficiencies in keeping the BDRs small, the database can still accumulate a great deal of unnecessary generations, i.e. garbage. There are two ways to clean out all the garbage from the database. The first is called Cooperative Garbage Collection. It happens automatically every time a record is touched, on a select, update, or delete operation. When the record is touched, the InterBase kernel follows the pointers to each BDR and compares it's transaction number with what's called the Oldest Interesting Transaction (OIT). This number is kept in the header page for the database. If the BDR's transaction number is less than the OIT, then the BDR can be purged from the database and the space reclaimed for new data. This will not clean up deleted records and their BDRs.
enableAutomaticSweeping(java.lang.String, boolean)public void setSweepInterval(String database,
int num)
throws SQLException
public void createShadow(String database,
String shadowURL)
throws SQLException
Another physical property is the ability to create shadows of the database. Shadows are carbon copies of the database, an exact duplicate. The main reason for shadows is to protect yourself from hardware failure. First you have to set up one or more shadows on other disk partitions or better still, other machines. The if your primary disk or server fails the users can reconnect to the shadow after the DBA has enabled it. This is much quicker than restoring from a backup.
Shadows can also be composed of multiple files just like normal databases.
The major drawback to shadows is that they increase the number of writes the database server does. If you have only one shadow then every write is duplicated. Two shadows and every write is tripled. This can cause performance problems.
public void createShadow(String database,
String shadowURL,
int pageSize)
throws SQLException
public void createShadow(String database,
String shadowURL,
int pageSize,
String[] secondaryFiles,
int[] lengths)
throws SQLException
public void dropShadow(String shadowURL)
throws SQLException
public void verify(String database)
throws SQLException
public void markAsDamaged(String database)
throws SQLException
Connection requests should throw a SQLException for damaged databases.
public void limitNumberOfConnections(String database,
int maxUsers)
throws SQLException
public void repair(String database)
throws SQLException
Note: Clearly this cannot repair corrupt databases in general.
public int[] getLimboTransactionIds(String database)
throws SQLException
public void rollbackLimboTransaction(String database,
int transactionId)
throws SQLException
public void commitLimboTransaction(String database,
int transactionId)
throws SQLException
Connection.getTransactionId()public void twoPhaseCommitLimboTransactions(String database)
throws SQLException
public String[] getSecondaryFiles(String database)
throws SQLException
public int[] getLengths(String database)
throws SQLException
public void setCacheBuffers(String database,
int buffers)
throws SQLException
By default, Server.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 (ServerProperties.setDefaultCacheBuffers(), and ConnectionProperties.setCacheBuffers()).
Superserver allocates a separate page buffer cache per database.
getCacheBuffers(java.lang.String),
ServerProperties.setDefaultCacheBuffers(int),
ConnectionProperties.setCacheBuffers(int)public int getCacheBuffers(String database)
throws SQLException
setCacheBuffers(java.lang.String, int)public int getDefaultPageSize(int pageSize)
throws SQLException
ServerProperties.setDefaultPageSize(int),
createDatabase(java.lang.String)public int getDefaultCacheBuffers()
throws SQLException
ServerProperties.setDefaultCacheBuffers(int),
getCacheBuffers(java.lang.String),
DatabaseMetaData.getCacheBuffers()public ServerStatistics getStatistics()
throws SQLException
public InputStream getLockActivity(String database)
throws SQLException
public SQLWarning getWarnings()
throws SQLException
Note: Subsequent warnings will be chained to this SQLWarning.
public void clearWarnings()
throws SQLException
protected void finalize()
throws Throwable
Therefore, it is recommended that server 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 (server != null)
try { server.close (); } catch (SQLException e) {}
}
Or alternatively, use the System.runFinalizersOnExit () method.
public void close()
throws SQLException
Note: A Server connection is automatically closed when it is garbage collected. Certain fatal errors also result in a closed Server.
public boolean isClosed()
throws SQLException
|
1.50.39 | ||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||