DataSource Configuration
Frequently an application only needs to access a single database in the course of a transaction. In these circumstances, you can avoid the overhead of a full XA transaction by using a local- or no- transaction configuration.
To provide maximum compatibility with drivers, his type of configuration uses the JDBC Driver type configuation mechanism rather than a DataSource.
Connection Transaction Types
A datasource is configued in a -ds.xml file using a or element.
A does not support transactional behaviour; all operations are atomic in themselves just as if autoCommit was true for the underlying JDBC Connection.
A supports transactional behaviour by delegating the transaction to the underlying database. However, the duration of the transaction is determined by the Transaction Manager and the commit and rollback methods must not be used by an application.
Connection Properties
The following elements are used to configure the JDBC connection:
|
Required
Once |
The name with which this DataSource will be bound into JNDI. A value of "MyDS" will be bound to the absolute name "java:/MyDS". |
|
Required
Once |
The JDBC connection URL to use when creating a connection. The syntax of the URL is driver specific. |
|
Required
Once |
The fully qualified class name for the JDBC driver. |
|
Optional
Multiple |
Additional property values that will be supplied to the JDBC driver when obtaining a connection. For example:
myDatabase
|
|
Required*
Once |
The username to be used when obtaining a connection. This element is required unless other security is configured. |
|
Required*
Once |
The password to be used when obtaining a connection. This element is required unless other security is configured. |
An example of a very simple configuration for connecting to an Oracle database would be:
MyOracleDS
jdbc:oracle:thin:@host:1521:sid
oracle.jdbc.driver.OracleDriver
scott
tiger
Connection Management
Once a connection has been obtained, the following elements can be used to determine how it is managed by the connector:
|
Default 0
Once |
The minimum number of connections that will be retained in the connection pool. |
|
Default 20
Once |
The maximum number of connections that will be entered in the connection pool. |
|
Default 5000
Once |
The amount of time that a thread will wait for a connection to be released if the pool is full. If less than connections have been allocated, the thread nevers blocks but instead allocates a new connection. |
|
Default 15
Once |
The approximate time that a connection will remain idle before being closed. Idle connections are checked for at an interval of half the lowest value for all connection pools; thus a connection may actually remain in the pool for between 1 and 1.5 times this value.
This value can be used to prevent errors when the underlying driver automatically closes idle connections.
|
|
Optional
Once |
The isolation level to use for this connection.
This can be specified using the constants defined in java.sql.Connection:
- TRANSACTION_READ_UNCOMMITTED
- TRANSACTION_READ_COMMITTED
- TRANSACTION_REPEATABLE_READ
- TRANSACTION_REPEATABLE_READ
Alternatively an integer value can be used to specify driver-specific levels.
If omitted, this will default to the default isolation level provided by the database and driver.
|
|
Optional
Once |
An SQL statement that will be executed immediately after a connection is created. |
|
Optional
Once |
An SQL statement that will be executed whenever a connection is obtained from the pool to determine if it is still usable. Any SQLException thrown will cause the connection to be discarded before it is returned to the application.
See Handling Connection Errors for more information.
|
|
Optional
Once
|
The fully qualifed name of a class which can be used to detect SQLExceptions that indicate unusable connections. Should such an SQLException be thrown, then the connection will immediately be discarded from the pool.
See Handling Connection Errors for more information.
|
|
