JDBCConnectionPoolMBean

Overview

This bean defines a JDBC connection pool.

Deprecated. 9.0.0.0 Replaced by JDBCSystemResourceMBean

Related MBeans

This section describes attributes that provide access to other MBeans.

Targets

You must select a target on which an MBean will be deployed from this list of the targets in the current domain on which this item can be deployed. Targets must be either servers or clusters. The deployment will only occur once if deployments overlap.

Attributes

This section describes the following attributes:

ACLName

The access control list (ACL) used to control access to this connection pool.

Permissions available to this ACL are:

• Reserve

  Allows users to get logical connections from this connection pool.

• Admin

  Allows all other operations on this connection pool, including: reset, shrink, shutdown, disable, and enable.

Lack of an ACL allows any user open access (provided that the user passes other WLS security controls).

CachingDisabled

Private property that disables caching in proxies.

CapacityIncrement

The increment by which this JDBC connection pool's capacity is expanded. In WebLogic Server 10.3.1 and higher releases, the capacityIncrement is no longer configurable and is set to a value of 1.

When there are no more available physical connections to service requests, the connection pool will create this number of additional physical database connections and add them to the connection pool. The connection pool will ensure that it does not exceed the maximum number of physical connections.

Deprecated. 10.3.6.0

For more information, see:

• getMaxCapacity

ConnectionCreationRetryFrequencySeconds

The number of seconds between when the connection pool retries to establish connections to the database. Do not enable connection retries for connection pools included in a High Availability MultiPool.

If you do not set this value, connection pool creation fails if the database is unavailable. If set and if the database is unavailable when the connection pool is created, WebLogic Server will attempt to create connections in the pool again after the number of seconds you specify, and will continue to attempt to create the connections until it succeeds.

Note: Do not enable connection creation retries for connection pools included in a High Availability MultiPool. Connection requests to the MultiPool will fail (not fail-over) when a connection pool in the list is dead and the number of connection requests equals the number of connections in the first connection pool, even if connections are available in subsequent connection pools in the MultiPool.

When set to 0, connection retry is disabled.

ConnectionReserveTimeoutSeconds

The number of seconds after which a call to reserve a connection from the connection pool will timeout.

When set to 0, a call will never timeout.

When set to -1, a call will timeout immediately.

For more information, see:

• getHighestNumWaiters

ConnLeakProfilingEnabled

Specifies that JDBC connection leak information is gathered. This option is required to view leaked connections from the connection pool.

A Connection leak occurs when a connection from the pool is not closed explicitly by calling close() on that connection.

When connection leak profiling is active, the connection pool will store the stack trace at the time the Connection object is allocated from the connection pool and given to the client. When a connection leak is detected (when the Connection object is garbage collected), this stack trace is reported.

This feature uses extra resources and will likely slow down connection pool operations, so it is not recommended for production use.

ConnProfilingEnabled

Specifies whether the connection pool detects local transaction work left incomplete by application code, which can interfere with subsequent operations related to global (XA) transactions.

When connection profiling is active, the pool will store the stack trace at the time the connection object is released back into the pool by the client. If an exception is thrown during a subsequent operation related to global (XA) transactions, this stack trace is reported.

This feature uses extra resources and will likely slowdown Connection Pool operations, so it is not recommended for production use.

CountOfRefreshFailuresTillDisable

The number of consecutive pool con refresh failures till we disable the pool.

If a pool loses DBMS connectivity, all the connections are dead and we won't be able to replace them till the DBMS is back. Applications that continue to ask the pool for connections will suffer slowness while the pool tries in vain to test dead connections and tries in vain to make a new one. Sometiimes this can take minutes. This setting tells the pool to disable itself so the applications will at least get a quick failure response, and if a multipool is involved, it can fail over to the next pool quickly. The self-disabled pool will periodically try to reconnect, and will re-enable itself asap.

Setting the count to zero means we will not disable.

CountOfTestFailuresTillFlush

The number of consecutive pool con test failures till we flush the pool.

If a pool temporarily loses DBMS connectivity, all the connections are probably dead. It is much faster to close them all, rather than have the pool test each one during a reserve, and then replace it. This setting tells the pool to flush all the connections in the pool after N consecutive times finding that a connection being tested is dead.

Setting the count to zero means we will not flush.

CredentialMappingEnabled

Returns the configured ignoreInUseConnectionsEnabled value.

DeploymentOrder

A priority that the server uses to determine when it deploys an item. The priority is relative to other deployable items of the same type.

For example, the server prioritizes and deploys all EJBs before it prioritizes and deploys startup classes.

Items with the lowest Deployment Order value are deployed first. There is no guarantee on the order of deployments with equal Deployment Order values. There is no guarantee of ordering across clusters.

DriverName

The full package name of JDBC driver class used to create the physical database connections in the connection pool. (Note that this driver class must be in the classpath of any server to which it is deployed.)

For example: oracle.jdbc.OracleDriver

It must be the name of a class that implements the java.sql.Driver interface. Check the documentation for the JDBC driver to find the full pathname.

EnableResourceHealthMonitoring

Returns whether JTA resource health monitoring is enabled for this XA connection pool.

This property applies to XA connection pools only, and is ignored for connection pools that use a non-XA driver.

HighestNumUnavailable

The maximum number of connections in the connection pool that can be made unavailable for use by an application. Connections become unavailable while being tested or refreshed.

Note that in cases likes the back end system being unavailable, this specified value could be exceeded due to factors outside the pool's control.

When set to 0, this feature is disabled.

HighestNumWaiters

The maximum number of connection requests that can concurrently block threads while waiting to reserve a connection from the connection pool.

For more information, see:

• getConnectionReserveTimeoutSeconds

IgnoreInUseConnectionsEnabled

Returns the configured ignoreInUseConnectionsEnabled value.

InactiveConnectionTimeoutSeconds

The number of inactive seconds on a reserved connection before WebLogic Server reclaims the connection and releases it back into the connection pool.

When set to 0, the feature is disabled.

InitialCapacity

The number of physical database connections to create when creating this JDBC connection pool. If unable to create this number of connections, creation of this connection pool will fail.

This is also the minimum number of physical connections the connection pool will keep available.

InitSQL

SQL statement to execute that will initialize a newly created physical connection. Start the statement with SQL followed by a space.

If the statement begins with "SQL ", then the rest of the string following that leading token will be taken as a literal SQL statement that will be used to initialize a connection. Else, the statement will be treated as the name of a table and the following SQL statement will be used to initialize a connection:
"select count(*) from InitSQL"

The table InitSQL must exist and be accessible to the database user for the connection. Most database servers optimize this SQL to avoid a table scan, but it is still a good idea to set InitSQL to the name of a table that is known to have few rows, or even no rows.

KeepLogicalConnOpenOnRelease

Specifies whether the logical JDBC connection is kept open when the physical XA connection is returned to the XA connection pool. Only applies to connection pools that use an XA driver.

Select this option if the XA driver used to create database connections or the DBMS requires that a logical JDBC connection be kept open while transaction processing continues (although the physical XA connection can returned to the XA connection pool).

Use this setting to work around specific problems with third party vendor's XA driver.

KeepXAConnTillTxComplete

Specifies whether the XA connection pool associates the same XA connection with the distributed transaction until the transaction completes. Only applies to connection pools that use an XA driver.

Use this setting to work around specific problems with third party vendor's XA driver.

LoginDelaySeconds

The number of seconds to delay before creating each physical database connection.

This delay supports database servers that cannot handle multiple requests for connections in rapid succession

The delay takes place both during initial pool creation and during the lifetime of the pool whenever a physical database connection is created.

MaxCapacity

The maximum number of physical database connections that this JDBC connection pool can contain.

Different JDBC Drivers and database servers may limit the number of possible physical connections.

MBeanInfo

Returns the MBean info for this MBean.

Deprecated.

Name

The user-specified name of this MBean instance.

This name is included as one of the key properties in the MBean's javax.management.ObjectName:
Name=user-specified-name

NeedTxCtxOnClose

Specifies whether the XA driver requires a distributed transaction context when closing various JDBC objects (result sets, statements, connections, and so on). Only applies to connection pools that use an XA driver.

When enabled, SQL exceptions that are thrown while closing the JDBC objects in no transaction context will be swallowed.

Use this setting to work around specific problems with third party vendor's XA driver.

NewXAConnForCommit

Specifies whether a dedicated XA connection is used for commit/rollback processing of a particular distributed transaction. Only applies to connection pools that use an XA driver.

Use this setting to work around specific problems with third party vendor's XA driver.

Notes

Optional information that you can include to describe this configuration.

WebLogic Server saves this note in the domain's configuration file (config.xml) as XML PCDATA. All left angle brackets (<) are converted to the XML entity <. Carriage returns/line feeds are preserved.

Note:

If you create or edit a note from the Administration Console, the Administration Console does not preserve carriage returns/line feeds.

ObjectName

Returns the ObjectName under which this MBean is registered in the MBean server.

Deprecated.

Parent

Return the immediate parent for this MBean

Password

The database password.

The value of this attribute can be set indirectly by passing it as a key=value pair by passing it to the MBean server's setAttribute method for the Properties attribute. However, Oracle recommends that you set the value directly by passing it to the MBean server's setAttribute method for this (PasswordEncrypted) attribute.

When you set the value of this attribute, WebLogic Server does the following:

1. Encrypts the value.

2. Sets the value of the PasswordEncrypted attribute to the encrypted value.

Using this Password attribute is a potential security risk because the String object (which contains the unencrypted password) remains in the JVM's memory until garbage collection removes it and the memory is reallocated. Depending on how memory is allocated in the JVM, a significant amount of time could pass before this unencrypted data is removed from memory.

Instead of using this attribute, use PasswordEncrypted.

For more information, see:

• getProperties
• getPasswordEncrypted

PasswordEncrypted

The encrypted database password.

The value of this attribute can be set indirectly by passing it as a key=value pair by passing it to the MBean server's setAttribute method for the Properties attribute. However, Oracle recommends that you set the value directly by using weblogic.management.EncryptionHelper.encrypt() to encrypt the value. Then set this attribute to the output of the encrypt() method. Doing so overrides the corresponding key=value pair in Properties if you set one.

To compare a password that a user enters with the encrypted value of this attribute, go to the same WebLogic Server instance that you used to set and encrypt this attribute and use weblogic.management.EncryptionHelper.encrypt() to encrypt the user-supplied password. Then compare the encrypted values.

PreparedStatementCacheSize

The number of prepared statements stored in the cache. (This might increase server performance.)

WebLogic Server can reuse prepared statements in the cache without reloading them, which can increase server performance. Setting the size of the prepared statement cache to 0 turns it off.

Properties

The list of properties passed to the JDBC driver that are used to create physical database connections. List each property=value pair on a separate line.

For example: server=dbserver1.

The list consists of attribute=value tags, separated by semi-colons. For example user=scott;server=myDB.

Note: Oracle recommends that you do not store passwords in this properties list. Instead, store them in PasswordEncrypted so that the value is encrypted in config.xml and in the Administration Console display.

For more information, see:

• getPasswordEncrypted

RefreshMinutes

The number of minutes between database connection tests. (Requires that you specify a Test Table Name.)

At the specified interval, unused database connections are tested. Connections that do not pass the test will be closed and reopened to re-establish a valid physical database connection.

For more information, see:

• getTestTableName

Registered

Returns false if the MBean represented by this object has been unregistered.

Deprecated.

RemoveInfectedConnectionsEnabled

Specifies whether a connection will be removed from the connection pool when the application asks for the underlying vendor connection object.

If you use this setting, you must make sure that the database connection is suitable for reuse by other applications.

When enabled, the physical connection is not returned to the connection pool after the application closes the logical connection. Instead, the physical connection is closed and recreated.

When not enabled, when you close the logical connection, the physical connection is returned to the connection pool.

For more information, see:

• WLConnection#getVendorConnection

RollbackLocalTxUponConnClose

Specifies whether the WLS connection pool will call rollback() on the connection before putting it back in the pool.

Enabling this attribute will have a performance impact as the rollback call requires communication with the database server.

SecondsToTrustAnIdlePoolConnection

The number of seconds within the use of a pooled connection that WebLogic Server trusts that the connection is still viable and will skip connection testing.

If an application requests a connection within the time specified since the connection was tested or successfully used and returned to the connection pool, WebLogic Server skips the connection test before delivering it to an application (if TestConnectionsOnReserve is enabled).

WebLogic Server also skips the automatic refresh connection test if the connection was successfully used and returned to the connection pool within the time specified (if TestFrequencySeconds is specified).

SecondsToTrustAnIdlePoolConnection is a tuning feature that can improve application performance by minimizing the delay caused by database connection testing, especially during heavy traffic. However, it can reduce the effectiveness of connection testing, especially if the value is set too high. The appropriate value depends on your environment and the likelihood that a connection will become defunct.

ShrinkFrequencySeconds

The number of seconds before WebLogic Server shrinks the connection pool to the original number of connections or number of connections currently in use. (Requires that you enable connection pool shrinking.)

ShrinkingEnabled

Specifies whether the JDBC connection pool can shrink back to its initial capacity or to the current number of connections in use if it detects that connections created during increased traffic are not being used.

When shrinking, the number of connections is reduced to the greater of either the initial capacity or the current number of connections in use.

ShrinkPeriodMinutes

The number of minutes to wait before shrinking a connection pool that has incrementally increased to meet demand. (Requires that you enable connection pool shrinking.)

For more information, see:

• isShrinkingEnabled

SqlStmtProfilingEnabled

Specifies whether the connection pool stores SQL statement text, execution time and other metrics.

This is a resource-consuming feature, so it's recommended that it's turned off on a production server.

StatementCacheSize

The number of prepared and callable statements stored in the cache. (This might increase server performance.)

WebLogic Server can reuse statements in the cache without reloading them, which can increase server performance. Each connection in the pool has its own cache of statements.

Setting the size of the statement cache to 0 turns it off.

StatementCacheType

The algorithm used for maintaining the prepared statements stored in the cache.

Connection pools support the following cache types:

• LRU

  replaces the least recently used statements when new statements are used.

• FIXED

  keeps the first fixed number of statements in the cache.

StatementTimeout

The time after which a statement currently being executed will be timed-out.

Efficacy of this feature relies on underlying JDBC driver support. WebLogic Server passes the time specified to the JDBC driver using the java.sql.Statement.setQueryTimeout() method. If your JDBC driver does not support this method, it may throw an exception and the timeout value is ignored.

A value of -1 disables this feature.

A value of 0 means that statements will not time out.

TestConnectionsOnCreate

Specifies whether WebLogic Server tests a connection after creating it but before adding it to the list of connections available in the pool. (Requires that you specify a Test Table Name.)

The test adds a small delay in creating the connection, but ensures that the client receives a working connection (assuming that the DBMS is available and accessible).

For more information, see:

• getTestTableName

TestConnectionsOnRelease

Specifies whether WebLogic Server tests a connection before returning it to this JDBC connection pool. (Requires that you specify a Test Table Name.)

If all connections in the pool are already in use and a client is waiting for a connection, the client's wait will be slightly longer while the connection is tested.

For more information, see:

• getTestTableName

TestConnectionsOnReserve

Specifies whether WebLogic Server tests a connection before giving it to the client. This test is required for connection pools used within a MultiPool that use the High Availability algorithm. (Requires that you specify a Test Table Name.)

The test adds a small delay in serving the client's request for a connection from the pool, but ensures that the client receives a working connection (assuming that the DBMS is available and accessible).

For more information, see:

• getTestTableName

TestFrequencySeconds

The number of seconds between when WebLogic Server tests unused database connections. (Requires that you specify a Test Table Name.)

Connections that fail the test are closed and reopened to re-establish a valid physical database connection. If the test fails again, the connection is closed.

When set to 0, periodic testing is disabled.

For more information, see:

• getTestTableName
• JDBCConnectionPoolMBean#setHighestNumUnavailable(int)

TestStatementTimeout

The time after which the test statement (configured by applications using the pool attribute Test Table Name) or initialization statement (configured by applications using the pool attribute InitSQL) currently being executed will be timed out.

Efficacy of this feature relies on underlying JDBC driver support. WebLogic Server passes the time specified to the JDBC driver using the java.sql.Statement.setQueryTimeout() method. If your JDBC driver does not support this method, it may throw an exception and the timeout value is ignored.

A value of -1 disables this feature.

A value of 0 means that statements will not time out.

For more information, see:

• getTestTableName
• getInitSQL

TestTableName

The name of the database table to use when testing physical database connections. This name is required when you specify a Test Frequency and enable Test Reserved Connections, Test Created Connections, and Test Released Connections.

The default SQL code used to test a connection is

Most database servers optimize this SQL to avoid a table scan, but it is still a good idea to set the Test Table Name to the name of a table that is known to have few rows, or even no rows.

If the name begins with "SQL ", then the rest of the string following that leading token will be taken as a literal SQL statement that will be used to test a connection.

Type

Returns the type of the MBean.

URL

The URL of the database to connect to. The format of the URL varies by JDBC driver.

The URL is passed to the JDBC driver to create the physical database connections.

XAEndOnlyOnce

Specifies that XAResource.end() is called only once for each pending XAResource.start(). The XA driver will not call XAResource.end(TMSUSPEND), XAResource.end(TMSUCCESS) successively. Only applies to connection pools that use an XA driver.

Use this setting to work around specific problems with third party vendor's XA driver.

XAPassword

The password that is used to create physical XA database connections.

The value of this attribute can be set indirectly by passing it as a key=value pair by passing it to the MBean server's setAttribute method for the Properties attribute. However, Oracle recommends that you set the value directly by passing it to the MBean server's setAttribute method for this (XAPassword) attribute.

When you set the value of this attribute, WebLogic Server does the following:

1. Encrypts the value.

2. Sets the value of the XAPasswordEncrypted attribute to the encrypted value.

Using this XAPassword attribute is a potential security risk because the String object (which contains the unencrypted password) remains in the JVM's memory until garbage collection removes it and the memory is reallocated. Depending on how memory is allocated in the JVM, a significant amount of time could pass before this unencrypted data is removed from memory.

Instead of using this attribute, use XAPasswordEncrypted.

For more information, see:

• getProperties
• getXAPasswordEncrypted

XAPasswordEncrypted

The password that is used to create physical XA database connections.

The value of this attribute can be set indirectly by passing it as a key=value pair by passing it to the MBean server's setAttribute method for the Properties attribute. However, Oracle recommends that you set the value directly by using weblogic.management.EncryptionHelper.encrypt() to encrypt the value. Then set this attribute to the output of the encrypt() method. Doing so overrides the corresponding key=value pair in Properties if you set one. It also causes WebLogic Server to encrypt the value and set the attribute to the encrypted value.

To compare a password that a user enters with the encrypted value of this attribute, go to the same WebLogic Server instance that you used to set and encrypt this attribute and use weblogic.management.EncryptionHelper.encrypt() to encrypt the user-supplied password. Then compare the encrypted values.

XAPreparedStatementCacheSize

The maximum number of prepared statements cached by this particular XA connection pool. Only applies to connection pools that use an XA driver.

If set to 0, caching is turned off.

XARetryDurationSeconds

Determines the duration in seconds for which the transaction manager will perform recover operations on the resource. A value of zero indicates that no retries will be performed.

XARetryIntervalSeconds

Determines the time in seconds between XA retry operations if the XARetryDurationSeconds attribute is set to a positive value.

XASetTransactionTimeout

When set to true, the WebLogic Server Transaction Manager calls XAResource.setTransactionTimeout() before calling XAResource.start, and passes either the XATransactionTimeout or the global transaction timeout in seconds.

When set to false, the Transaction Manager does not call setTransactionTimeout().

This property applies to XA connection pools only, and is ignored for connection pools that use a non-XA driver.

XATransactionTimeout

Determines the number of seconds to pass as the transaction timeout value in the XAResource.setTransactionTimeout() method. When this property is set to 0, the WebLogic Server Transaction Manager passes the global WebLogic Server transaction timeout in seconds in the method.

If set, this value should be greater than or equal to the global WebLogic Server transaction timeout.

XASetTransactionTimeout must be set to "true" or this property is ignored.

This property applies to XA connection pools only, and is ignored for connection pools that use a non-XA driver.

Operations

This section describes the following operations:

addTarget

You can add a target to specify additional servers on which the deployment can be deployed. The targets must be either clusters or servers.

freezeCurrentValue

If the specified attribute has not been set explicitly, and if the attribute has a default value, this operation forces the MBean to persist the default value.

Unless you use this operation, the default value is not saved and is subject to change if you update to a newer release of WebLogic Server. Invoking this operation isolates this MBean from the effects of such changes.

Note:

To insure that you are freezing the default value, invoke the restoreDefaultValue operation before you invoke this.

This operation has no effect if you invoke it on an attribute that does not provide a default value or on an attribute for which some other value has been set.

Deprecated. 9.0.0.0

isSet

Returns true if the specified attribute has been set explicitly in this MBean instance.

removeTarget

Removes the value of the addTarget attribute.

For more information, see:

• addTarget

restoreDefaultValue

If the specified attribute has a default value, this operation removes any value that has been set explicitly and causes the attribute to use the default value.

Default values are subject to change if you update to a newer release of WebLogic Server. To prevent the value from changing if you update to a newer release, invoke the freezeCurrentValue operation.

This operation has no effect if you invoke it on an attribute that does not provide a default value or on an attribute that is already using the default.

Deprecated. 9.0.0.0

unSet

Restore the given property to its default value.