Oracle GlassFish Server 3.0.1 Application Deployment Guide


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


resources (sun-resources.xml)


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

Table C–67 jdbc-connection-pool Subelements





zero or one 

Contains a text description of this element. 

property (with attributes)

zero or more 

Specifies a property or a variable. 


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 C–68 jdbc-connection-pool Attributes






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



(optional) 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.



(optional) Specifies the interface the data source class implements. The value of this attribute can be javax.sql.DataSource, javax.sql.XADataSource , javax.sql.ConnectionPoolDatasource, or java.sql.Driver. To support configuration of JDBC drivers and applications that use java.sql.Driver implementations, set this attribute to java.sql.Driver. This attribute must be specified to avoid ambiguity when a data source class implements two or more of these interfaces or when a driver-classname is specified. An error occurs if this attribute has a legal value and the indicated interface is not implemented by the data source class.



(optional) Specifies the vendor-supplied JDBC driver class name. This driver must implement the java.sql.Driver interface.



(optional) Specifies whether to ping the pool during pool creation or reconfiguration to identify and warn of any erroneous attribute values. 



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



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



(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.



(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.



(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. 

This timeout value must be kept shorter than the server side (database) timeout value to prevent the accumulation of unusable connections in the application. 


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.



(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.



(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. 



(optional) Legal values are as follows: 

  • auto-commit, 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

  • custom-validation, which uses a user-defined validation mechanism specified by the custom implementation class in validation-classname.

Because many JDBC drivers cache the results of auto-commit and meta-data calls, they do not always provide reliable validations. Check with the driver vendor to determine whether these calls are cached or not.

The table must exist and be accessible, but it doesn't require any rows. Do not use an existing table that has a large number of rows or a table that is already frequently accessed. More details can be found at Connection Validation in GlassFish JDBC.



(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.



(optional) Specifies the custom validation implementation class name. This parameter is mandatory if connection-validation-method is set to custom-validation. The classname provided must be accessible to the GlassFish Server. The specified class must implement the org.glassfish.api.jdbc.ConnectionValidation interface.



(optional) Specifies an SQL string to be executed whenever a connection is created (not reused) in the pool. This initializes the state of the connection. 



(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.



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



(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.



(optional) Specifies the time interval within which a connection is validated at most once. Minimizes the number of validation calls. A value of zero allows unlimited validation calls. 



(optional) 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. 

Use this attribute along with connection-leak-reclaim to avoid potential connection leaks from the application. More details are at Connection Leak Tracing.



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



(optional) Specifies the number of attempts to create a new connection in case of a failure. 



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



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

An abnormally long running JDBC query executed by an application may leave it in a hanging state unless a timeout is explicitly set on the statement. This attribute guarantees that all queries automatically time out if not completed within the specified period. When statements are created, the queryTimeout is set according to the value specified in this attribute. This works only when the underlying JDBC driver supports queryTimeout for Statement, PreparedStatement, CallableStatement, and ResultSet.



(optional) 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.



(optional) 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.



(optional) Specifies whether connections are associated with the thread to enable the thread to reuse the connections. If true, allows connections to be saved as ThreadLocal in the calling thread. Connections get reclaimed only when the calling thread dies or when the calling thread is not in use and the pool has run out of connections. If false, the thread must obtain a connection from the pool each time the thread requires a connection.

This attribute associates connections with a thread such that when the same thread is in need of connections, it can reuse the connections already associated with that thread. In this case, the overhead of getting connections from the pool is avoided. However, when this value is set to true, you should verify that the value of the max-pool-size attribute is comparable to the max-thread-pool-size attribute of the associated thread pool. If the max-thread-pool-size value is much higher than the max-pool-size value, a lot of time is spent associating connections with a new thread after dissociating them from an older one. Use this attribute in cases where the thread pool should reuse connections to avoid this overhead.



(optional) Specifies whether a connection that is selected from the pool should be matched with the connections with certain credentials. If true, enables connection matching. You can set to false if connections are homogeneous.

If the connection pool is used by applications that have multiple user credentials, match-connections must be true. The connection pool matches the request's credential with the connections in the pool and returns a matched connection for use. For new requests with different credentials, unmatched free connections are automatically purged to provide new connections to satisfy the new requests. This attribute need not be true if it is known that there is only one credential used by the applications and therefore the pool has homogeneous connections.



(optional) Specifies the number of times a connections is reused by the pool, after which it is closed. A zero value disables this feature. By limiting the maximum number of times a connection can be reused, you can avoid statement leaks if the application does not close statements. 



(optional) Specifies that SQL statements executed by applications need to be traced. Helps administrators analyze the statements. Expects as a value a comma-separated list of listener implementation class names. Enables easy filtering of log messages for the SQL statements. SQL trace listeners must implement the org.glassfish.api.jdbc.SQLTraceListener interface.



(optional) Specifies the number of statements to be cached using the lru (Least Recently Used) caching mechanism. The default value of 0 disables statement caching.



(optional) If false, disables connection pooling.



(optional) If true, wrapped JDBC objects are returned for Statement, PreparedStatement, CallableStatement, ResultSet, and DatabaseMetaData.

This option ensures that Statement.getConnection() is the same as DataSource.getConnection(). Therefore, this option should be true when both Statement.getConnection() and DataSource.getConnection() are done. The default is false to avoid breaking existing applications.


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 GlassFish 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 C–69 jdbc-connection-pool Properties




Specifies the user name for connecting to the database. 


Specifies the password for connecting to the database. 


Specifies the database for this connection pool. 


Specifies the database server for this connection pool. 


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


Specifies the communication protocol. 


Specifies the initial SQL role name. 


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


Specifies a text description. 


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