JBoss.orgCommunity Documentation
The Query Engine logically obtains and releases a connection for each command that is executed.
However many enterprise sources maintain persistent connections that are expensive to create. For these situaions, Teiid provides a transparent connection pool to reuse rather than constantly release connections. The connection pool is highly configurable through configuration properties and extension APIs for Connections and Connectors
Many built-in connector types take advantage of pooling, including JDBC, Salesforce, and LDAP connectors.
The table below lists the role of each class in the framework.
Table 7.1. Responsibilities of Connection Pool Classes
|
Class |
Type |
Description |
|---|---|---|
|
PoolAwareConnection |
Interface |
This interface is an extension of the Connection interface and provides hooks to better interact with Connection pooling. |
|
ConnectorIdentityFactory |
Interface |
Defines a factory for creating ConnectorIdentities. This can optionally be implemented by the concrete Connector class to properly segregate Connections in the pool. If this class is not implemented by the Connector, then SingleIdentity support will be assumed. |
|
ConnectorIdentity |
Interface |
This interface corresponds to an identifier for a connection in the pool. Changing the identity implementation changes the basis on which connections are pooled. Connections that have equal identity objects (based on the equals() method) will be in the same pool. |
|
SingleIdentity |
Class |
This implementation of the identity class makes all connections equivalent, thus creating a single pool. |
|
UserIdentity |
Class |
This implementation of the identity class makes all connections equivalent for a particular user, thus creating a set of per-user connection pools. |
|
ConnectionPooling |
Annotation |
This optional Annotation can be used on the Connector implementation class to indicate configure pooling. This can be especially useful to indicate that automatic ConnectionPooing should not be used regardless of the connector binding property settings. |
Automatic connection pooling does not require any changes to basic Connector development. It can be enabled by setting the Connector binding Property ConnectionPoolEnabled=true or by adding the ConnectionPooling annotation, which defaults to enabled=true, to the Connector implementation class. Automatic Connection pooling can be disabled if either setting is false.
Connector developers can optionally utilize the PoolAwareConnection and ConnectorIdentityFactory interfaces to refine the Connector's interactions with Connection pooling. It is important to consider providing an implementation for PoolAwareConnection.isAlive to indicate that a Connection is no longer viable and should be purged from the pool. Connection testing is performed upon leases from the pool and optionally at a regular interval that will purge idle Connections. It is also important to consider having the concrete Connector class implement ConnectorIdentity factory if Connections are made under more than just a single identity.
These steps occur when connection pooling is enabled:
If the Connector implements ConnectorIdentityFactory, the ConnectorManager asks the Connector to generate a ConnectorIdentity for the given SecurityContext, else SingleIdentity is assumed. The ConnectorIdentity is then stored on the SecurityContext.
The ConnectorManager asks for a Connection from the pool that pertains to the ConnectorIdentity.
The ConnectionPool returns a Connection that was either pulled from the pool (and passes the isAlive check) or was created by the Connector if necessary.
After the ConnectorManager has used the Connection to execute a command, it releases the Connection. This call is intercepted by the pool and the method PoolAwareConnection.releaseCalled is invoked on the Connection instead. If the Connection does not implement PoolAwareConnection, it is assumed no action is needed.
When the Connection fails an isAlive check or becomes too old with pool shrinking enabled, it is purged from the pool and Connection.release is called.
The usage of XAConnections (that provide XAResources) typically come with additional limitations about how those Connections can be used once they are enlisted in a transaction. When enabled, automatic connection pooling will perform these additional features with XAConnections:
The pool will return the same XAConnection for all executions under a given transaction until that transaction completes. This implies that all executions to a given XAConnector under the same connection will happen serially.
XAConnections enlisted in a transaction will return to the pool once a transaction completes.
Two separate pools will be maintained. One for Connections that have not and will not be used in a transaction, and one for XAConnections that have an will be used in a transaction. Each pool will be configured based upon the same set of configuration properties - it is not possible to independently control pool sizes, etc.
The ConnectionPool has a number of properties that can be configured via the connector binding expert properties.
Table 7.2. Connection Pool Properties
|
Name |
Key |
Default Value |
Description |
|---|---|---|---|
|
Connection Pool Enabled |
ConnectionPoolEnabled |
Explicitly enables or disables connection pooling. | |
|
Data Source Test Connect Interval (seconds) |
SourceConnectionTestInterval |
600 |
How often (in seconds) to create test connections to the underlying source to see if it is available. |
|
Pool Maximum Connections |
com.metamatrix.data. ~pool.max_connections |
20 |
Maximum number of connections total in the pool. This value should be greater than 0. |
|
Pool Maximum Connections for Each ID |
com.metamatrix.data. ~pool.max_connections_for_each_id |
20 |
Maximum number of connections per ConnectorIdentity object. This value should be greater than 0. |
|
Pool Connection Idle Time (seconds) |
com.metamatrix.data. ~pool.live_and_unused_time |
60 |
Maximum idle time (in seconds) before a connection is closed if shrinking is enabled. |
|
Pool Connection Waiting Time (milliseconds) |
com.metamatrix.data. ~pool.wait_for_source_time |
120000 |
Maximum time to wait (in milliseconds) for a connection to become available. |
|
Pool cleaning Interval (seconds) |
com.metamatrix.data. ~pool.cleaning_interval |
60 |
Interval (in seconds) between checking for idle connections if shrinking is enabled. |
|
Enable Pool Shrinking |
com.metamatrix.data. ~pool.enable_shrinking |
true |
Indicate whether the pool is allowed to shrink. |