Sun GlassFish Enterprise Server 2.1 Administration Reference

jdbc-connection-pool

Defines the properties that are required for creating a JDBC connection pool.

Superelements

resources

Subelements

The following table describes subelements for the jdbc-connection-pool element.

Table 1–86 jdbc-connection-pool Subelements

Element 

Required 

Description 

description

zero or one 

Contains a text description of this element. 

property

zero or more 

Specifies a property or a variable. 

Attributes

The following table describes attributes for the jdbc-connection-pool element. Changing the following attributes requires a server restart: datasource-classname, associate-with-thread, lazy-connection-association, and lazy-connection-enlistment.

Table 1–87 jdbc-connection-pool Attributes

Attribute 

Default 

Description 

name

none 

Specifies the name of the connection pool. A jdbc-resource element’s pool-name attribute refers to this name.

datasource-classname

none 

Specifies the class name of the associated vendor-supplied data source. This class must implement javax.sql.DataSource, javax.sql.XADataSource , javax.sql.ConnectionPoolDatasource, or a combination.

res-type

javax.sql.DataSource

(optional) Specifies the interface the data source class implements. The value of this attribute can be javax.sql.DataSource, javax.sql.XADataSource , or javax.sql.ConnectionPoolDatasource. If the value is not one of these interfaces, the default is used. An error occurs if this attribute has a legal value and the indicated interface is not implemented by the data source class.

steady-pool-size

8

(optional) Specifies the initial and minimum number of connections maintained in the pool. 

max-pool-size

32

(optional) Specifies the maximum number of connections that can be created to satisfy client requests. 

max-wait-time-in-millis

60000

(optional) Specifies the amount of time, in milliseconds, that the caller is willing to wait for a connection. If 0, the caller is blocked indefinitely until a resource is available or an error occurs.

pool-resize-quantity

2

(optional) Specifies the number of idle connections to be destroyed if the existing number of connections is above the steady-pool-size (subject to the max-pool-size limit).

This is enforced periodically at the idle-timeout-in-seconds interval. An idle connection is one that has not been used for a period of idle-timeout-in-seconds. When the pool size reaches steady-pool-size, connection removal stops.

idle-timeout-in-seconds

300

(optional) Specifies the maximum time that a connection can remain idle in the pool. After this amount of time, the pool can close this connection. 

transaction-isolation-level

default JDBC driver isolation level 

(optional) Specifies the transaction isolation level on the pooled database connections. Allowed values are read-uncommitted, read-committed , repeatable-read, or serializable.

Applications that change the isolation level on a pooled connection programmatically risk polluting the pool, which can lead to errors. See is-isolation-level-guaranteed for more details.

is-isolation-level-guaranteed

true

(optional) Applicable only when transaction-isolation-level is explicitly set. If true, every connection obtained from the pool is guaranteed to have the desired isolation level. This might impact performance on some JDBC drivers. Only set this attribute to false if you are certain that the hosted applications do not return connections with altered isolation levels.

is-connection-validation-required

false

(optional) Specifies whether connections have to be validated before being given to the application. If a resource’s validation fails, it is destroyed, and a new resource is created and returned. 

connection-validation-method

auto-commit

(optional) Legal values are as follows: 

  • auto-commit (default), which uses Connection.setAutoCommit(Connection.getAutoCommit())

  • meta-data, which uses Connection.getMetaData()

  • table, which performs a query on a table specified in the validation-table-name attribute

validation-table-name

none 

(optional) Specifies the table name to be used to perform a query to validate a connection. This parameter is mandatory if and only if connection-validation-method is set to table.

fail-all-connections

false

(optional) If true, closes all connections in the pool if a single validation check fails. This parameter is mandatory if and only if is-connection-validation-required is set to true.

non-transactional-connections

false

(optional) If true, non-transactional connections can be made to the JDBC connection pool. These connections are not automatically enlisted with the transaction manager.

allow-non-component-callers

false

(optional) If true, non-Java-EE components, such as servlet filters, lifecycle modules, and third party persistence managers, can use this JDBC connection pool. The returned connection is automatically enlisted with the transaction context obtained from the transaction manager. Standard Java EE components can also use such pools. Connections obtained by non-component callers are not automatically closed at the end of a transaction by the container. They must be explicitly closed by the caller.

connection-leak-timeout-in-seconds

0

Detects potential connection leaks by the application. A connection that is not returned back to the pool by the application within the specified period is assumed to be potentially leaking, and a stack trace of the caller is logged. A zero value disables leak detection. A nonzero value enables leak tracing. 

connection-leak-reclaim

false

If true, the pool will reclaim a connection after connection-leak-timeout-in-seconds occurs.

connection-creation-retry-attempts

0

Specifies the number of attempts to create a new connection. 

connection-creation-retry-interval-in-seconds

10

Specifies the time interval between attempts to create a connection when connection-creation-retry-attempts is greater than 0.

validate-atmost-once-period-in-seconds

0

Specifies the time interval within which a connection is validated at most once. Minimizes the number of validation calls. 

statement-timeout-in-seconds

-1

Sets the query timeout property of a statement to enable termination of abnormally long running queries. The default value of -1 disables this feature.

lazy-connection-enlistment

false

If true, a connection is not enlisted in a transaction until it is used. If false, any connection object available to a transaction is enlisted in the transaction.

lazy-connection-association

false

If true, a physical connection is not associated with a logical connection until it is used. If false, a physical connection is associated with a logical connection even before it is used.

associate-with-thread

false

If true, allows a connection to be saved as a ThreadLocal in the calling thread. This connection gets reclaimed only when the calling thread dies or when the calling thread is not in use and the pool has run out of connections.

match-connections

false

If true, enables connection matching. You can set to false if connections are homogeneous.

max-connection-usage-count

0

Specifies the number of times a connections is reused by the pool, after which it is closed. A zero value disables this feature. 

wrap-jdbc-objects

false

If true, the application returns wrapped JDBC objects for Statement, PreparedStatement, CallableStatement, ResultSet, and DatabaseMetaData.

Properties

Most JDBC drivers allow use of standard property lists to specify the user, password, and other resource configuration information. Although properties are optional with respect to the Enterprise Server, some properties might be necessary for most databases. For details, see the JDBC 4.0 Standard Extension API.

When properties are specified, they are passed to the vendor’s data source class (specified by the datasource-classname attribute) as is using setName(value) methods.

The user and password properties are used as the default principal if container managed authentication is specified and a default-resource-principal is not found in the application deployment descriptors.

The following table describes some common properties for the jdbc-connection-pool element.

Changing JDBC driver properties requires a server restart.

Table 1–88 jdbc-connection-pool Properties

Property 

Description 

user

Specifies the user name for connecting to the database. 

password

Specifies the password for connecting to the database. 

databaseName

Specifies the database for this connection pool. 

serverName

Specifies the database server for this connection pool. 

port

Specifies the port on which the database server listens for requests. 

networkProtocol

Specifies the communication protocol. 

roleName

Specifies the initial SQL role name. 

datasourceName

Specifies an underlying XADataSource, or a ConnectionPoolDataSource if connection pooling is done.

description

Specifies a text description. 

url

Specifies the URL for this connection pool. Although this is not a standard property, it is commonly used. 

LazyConnectionEnlistment

Deprecated. Use the equivalent attribute. 

LazyConnectionAssociation

Deprecated. Use the equivalent attribute. 

AssociateWithThread

Deprecated. Use the equivalent attribute. 

MatchConnections

Deprecated. Use the equivalent attribute.