Reference | Help | Introduction | Slide Show | Class Hierarchy | InterClient
PREV | NEXT | FRAMES | NO FRAMES |  |

### DataSource and Connection Properties

The JDBC 2 Standard Extension DataSource facility provides an alternative to the JDBC DriverManager, essentially duplicating all of the driver manager’s useful functionality in the context of a Java Bean. Although, both mechanisms may be used by the same application if desired, JavaSoft encourages developers to regard the DriverManager as a legacy feature of the JDBC API. Applications should use the DataSource API whenever possible. The DriverManager, Driver, and DriverPropertyInfo interfaces may be deprecated in the future.

When using the JDBC 1 DriverManager/Driver API, connection properties are passed to the driver when a connection is requested with

- Driver.connect (databaseURL, java.util.Properties) or
- java.sql.DriverManager.getConnection (databaseURL, java.util.Properties).

When using the JDBC 2 Standard Extension API, connections are requested through a DataSource, and connection properties are set and retrieved using setter and getter methods of the DataSource bean. The DataSource, along with its properties, may be manipulated as a Java Bean or stored in a JNDI name service.

Regardless of the API used for establishing a connection, all DataSource properties are used to tailor a connection, and the connection only; these are not properties of the target database itself. Persistent properties of the database itself may be established using the ServerManager API.

Under the JDBC 1 DriverManager/Driver API, the `databaseName`, `serverName`, `networkProtocol`, and `portNumber` properties are specified as part of the database URL string. The JDBC 2 Standard Extension DataSource API does not use database URLs, and these properties are specified using the setter methods of a DataSource bean. The first table below indicates properties used by the DataSource API only.

DataSource API Connection Properties (not used by Driver API)

Property Key | Default | Description
--- | --- | ---
databaseName | null | Absolute path to a database on a server. If the database resides on a different machine than InterServer, then the database server name should also prefixed onto the database path as dictated by the InterBase remote database specification syntax.
JDBC 2 Standard Extension, proposed for InterClient 2.0, not yet supported
dataSourceName | null | An optional data source name; used to name an underlying XADataSource, or ConnectionPoolDataSource when pooling of connections is done. JDBC 2 Standard Extension, proposed for InterClient 2.0, not yet supported
description | null | An optional text description of the data source. JDBC 2 Standard Extension, proposed for InterClient 2.0, not yet supported
networkProtocol | jdbc:interbase: | An optional database protocol to use when communicating with InterServer. This can only be `jdbc:interbase:` for InterClient. JDBC 2 Standard Extension, proposed for InterClient 2.0, not yet supported
portNumber | 3060 | The TCP/IP port number where InterServer listens for connection requests on `serverName`. JDBC 2 Standard Extension, proposed for InterClient 2.0, not yet supported
serverName | null | The server name where InterServer resides. JDBC 2 Standard Extension, proposed for InterClient 2.0, not yet supported
serverManagerHost | null | The InterBase host to be serviced by a ServerManager. InterServer regulates the service requests to the `serverManagerHost`. See DataSource.getServerManager(). Extension, proposed for InterClient 2.0, not yet supported

DataSource and Driver API Connection Properties

Property Key | Default | Description
--- | --- | ---
user | null | The user name for the connection. JDBC 2 Standard Extension, proposed for InterClient 2.0, not yet supported
password | null | The user's password for the connection. JDBC 2 Standard Extension, proposed for InterClient 2.0, not yet supported
roleName | null | The user's SQL role name for the connection. This is optional. JDBC 2 Standard Extension, proposed for InterClient 2.0, not yet supported
charSet | NONE | The character encoding for the connection. All SQL and character input data will be sent to the database using the specified character encoding. All output data and InterBase messages retrieved from the database will also utilize the specified character encoding. InterClient messages do not utilize `charSet`, but derive from the resource bundle in use which is based on the locale-specific encoding of the client. The encoding specified must match one of the supported IANA character encoding names detailed in the CharacterEncodings class.
Extension, proposed for InterClient 2.0, not yet supported
interBaseLicense | null | The user's string authorization key for an InterBase software license. By default the license file from the InterBase home directory is used. Extension, proposed for InterClient 2.0, not yet supported
sweepOnConnect | false | Force garbage collection of outdated record versions 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.
Extension, proposed for InterClient 2.0, not yet supported
suggestedCachePages | 0 | 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 ServerManager.setDatabaseCachePages(database, pages), but takes precedence over the server-wide default set by `DATABASE_CACHE_PAGES` in the InterBase `ibconfig` startup file or by ServerManager.startInterBase(defaultCachePages, defaultPageSize).

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. So, although this is a transient property, once the cache size is increased, it stays that way as long as there are active connections. Once all connections to the database are closed, then subsequent connections will use the database-wide or server-wide defaults.

Note: Using this connection property 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.

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.

Also see DatabaseMetaData.getPersistentDatabaseCachePages(), and DatabaseMetaData.getActualCachePagesInUse().
Extension, proposed for InterClient 2.0, not yet supported

Reference | Help | Introduction | Slide Show | Class Hierarchy | InterClient
PREV | NEXT | FRAMES | NO FRAMES |  |

Send comments or suggestions to interclient@interbase.com