interbase.interclient
Class ConnectionProperties

java.lang.Object
  |
  +--java.util.Dictionary
        |
        +--java.util.Hashtable
              |
              +--java.util.Properties
                    |
                    +--interbase.interclient.ConnectionProperties

public final class ConnectionProperties

extends Properties

Properties used to tailor a connection.

This class is used to tailor connection properties before attaching to an InterBase database. Using this class is an alternative to configuring a java.util.Properties object directly. For example,

 Properties.put ("charSet", "SJIS")
 

is identical to

 ConnectionProperties.setCharacterEncoding ("SJIS")
 

.

Since:

Extension

See Also:

Driver.connect(java.lang.String,java.util.Properties), Serialized Form

Fields inherited from class java.util.Properties

defaults

Constructor Summary

ConnectionProperties()
Construct a default InterBase connection properties object.

Method Summary

void	allowAsynchronousDiskWrites(boolean asynchronous) Enable/disable synchronous writes to disk on commit.
void	disablePageStructureVerification() Reset verification requests.
void	enableHouseKeeping(boolean enable) Enable the server to perform periodic garbage collection automatically.
void	reserveNoSpaceForVersioning(boolean noreserve) Specify whether or not space is reserved on each newly created database page for anticipated record versions.
void	setCacheBuffers(int num) Set the suggested number of cache page buffers to use for this connection.
void	setCharacterEncoding(String encoding) Specify the character encoding for the connection.
void	setExclusiveAccess(boolean exclusive) Once a connection is established with this configuration, do not allow subsequent connections to the database.
void	setHouseKeepingSweepInterval(int interval) Specify the periodicity of automatic garbage collection.
void	setUser(String user, String password) Set the user and password for the pending connection.
void	sweep(boolean forceSweep) Force garbage collection of outdated records immediately upon connection.
void	verifyPageStructures(boolean checkAllRecords, boolean mend, boolean releaseFreePages) On connection, verify the database's internal page structures.

Methods inherited from class java.util.Properties

getProperty, getProperty, list, list, load, propertyNames, save, setProperty, store

Methods inherited from class java.util.Hashtable

clear, clone, contains, containsKey, containsValue, elements, entrySet, equals, get, hashCode, isEmpty, keys, keySet, put, putAll, rehash, remove, size, toString, values

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ConnectionProperties

public ConnectionProperties()

Construct a default InterBase connection properties object.

Since:

Extension

Method Detail

setUser

public void setUser(String user,
                    String password)

Set the user and password for the pending connection.

The corresponding connection property keys are "user" and "password".

Since:

Extension

setCharacterEncoding

public void setCharacterEncoding(String encoding)

Specify the character encoding for the connection. All SQL and data will be presented to the database using the specified character encoding.

The connection property key is "charSet".

Property values must match one of the supported IANA character encoding names specified in the CharacterEncodings class.

Since:

Extension, since 1.50

setExclusiveAccess

public void setExclusiveAccess(boolean exclusive)

Once a connection is established with this configuration, do not allow subsequent connections to the database.

The connection property key is TBD

Since:

Extension, proposed for future release, not yet supported

reserveNoSpaceForVersioning

public void reserveNoSpaceForVersioning(boolean noreserve)

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

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.

The connection property key is TBD

Since:

Extension, proposed for future release, not yet supported

See Also:

DatabaseMetaData.isSpaceReservedForVersioning()

allowAsynchronousDiskWrites

public void allowAsynchronousDiskWrites(boolean asynchronous)

Enable/disable synchronous writes to disk on commit.

If synchronous writes are not enabled, then even though InterBase performs a write, the data may not be physically written to disk, 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 slow performance. In particular, operations which involve data modification are slower.

The default for Unix is asynchronous and for NT it is synchronous. I think it's this way because it was thought people with PCs power off their machines whereas Unix users usually perform an orderly shutdown.

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.

The connection property key is TBD

Since:

Extension, proposed for future release, not yet supported

See Also:

DatabaseMetaData.isSynchronous()

verifyPageStructures

public void verifyPageStructures(boolean checkAllRecords,
                                 boolean mend,
                                 boolean releaseFreePages)

On connection, verify the database's internal page structures. By default, verification is not performed at connect time.

If the database structures are not verifiable then a SQLException will be thrown when the connection is attempted.

With this verification enabled, a subsequent connection request 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.

Here's the meaning of the two verification options

checkAllRecords

Validate all records. Without this switch, only page structures will be validated, which does involve some limited checking of records.

mend

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. If the mend option is disabled, then no database structures are updated.

The connection property key is TBD

Since:

Extension, proposed for future release, not yet supported

disablePageStructureVerification

public void disablePageStructureVerification()

Reset verification requests. By default, verification is not performed at connect time.

The connection property key is TBD

Since:

Extension, proposed for future release, not yet supported

setCacheBuffers

public void setCacheBuffers(int num)

Set the suggested number of cache page buffers to use for this connection.

This is a transient property of the connection and is overridden by the database-wide default set by Server.setCacheBuffers(database), but takes precedence over the server-wide default set by ServerProperties.setDefaultCacheBuffers().

On SuperServer, if a database cache already exists due to another attachment to the database then the cache size may be increased but not decreased.

Note: This method may jeopardize the performance of the server because an arbitrary user can connect and reserve 200MB for foo.gdb while corporate.gdb is forced to accept less.

The connection property key is TBD

Since:

Extension, proposed for future release, not yet supported

See Also:

DatabaseMetaData.getCacheBuffers(), Server.setCacheBuffers(java.lang.String, int), ServerProperties.setDefaultCacheBuffers(int)

sweep

public void sweep(boolean forceSweep)

Force garbage collection of outdated records immediately upon connection. See the InterBase Operations Guide for more 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.

The connection property key is TBD

Since:

Extension, proposed for future release, not yet supported

enableHouseKeeping

public void enableHouseKeeping(boolean enable)

Enable the server to perform periodic garbage collection automatically. See the InterBase Operations Guide for more details.

The connection property key is TBD

Since:

Extension, proposed for future release, not yet supported

setHouseKeepingSweepInterval

public void setHouseKeepingSweepInterval(int interval)

Specify the periodicity of automatic garbage collection. The interval specified is the number of transactions since the oldest interesting transaction and the most current transaction. The default interval is 20,000. See the InterBase Operations Guide for more details.

The connection property key is TBD

Since:

Extension, proposed for future release, not yet supported