JBoss.orgCommunity Documentation
The Query Engine logically obtains and closes a connection for each command.
However many enterprise sources connections can be persistent and expensive to create. For these situations, Teiid provides a transparent connection pool to reuse, rather than constantly close, 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 6.1. Responsibilities of Connection Pool Classes
|
Class |
Type |
Description |
|---|---|---|
|
Connection |
Interface |
The isAlive and closeCalled methods are used for pool interaction. |
|
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 ConnectorIdentity makes all connections equivalent, thus user scoping of connection is ignored. |
|
MappedUserIdentity |
Class |
This implementation of ConnectorIdentity makes all connections equivalent for a particular user allowing for 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.
It is important to consider providing an implementation for Connection.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 for multiple identities. Note that setting connector binding property UseCredentialMap to true will allow connectors extending BasicConnector to have their ConnectorIdentity automatically set based upon the user CredentialMap.
These steps occur when connection pooling is enabled:
The ConnectorManager asks the Connector to generate a ConnectorIdentity for the given ExecutionContext. The ConnectorIdentity is then stored on the ExecutionContext.
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 Connection.closeCalled is invoked on the Connection instead. Note that for many sources no action is necessary on closeCalled.
When the Connection fails an isAlive check or becomes too old with pool shrinking enabled, it is purged from the pool and Connection.close 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. Note *. indicates that the property prefix is com.metamatrix.data.pool.
Table 6.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 |
*.max_connections |
20 |
Maximum number of connections total in the pool. This value should be greater than 0. |
|
Pool Maximum Connections for Each ID |
*.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) |
*.live_and_unused_time |
60 |
Maximum idle time (in seconds) before a connection is closed if shrinking is enabled. |
|
Pool Connection Waiting Time (milliseconds) |
*.wait_for_source_time |
120000 |
Maximum time to wait (in milliseconds) for a connection to become available. |
|
Pool cleaning Interval (seconds) |
*.cleaning_interval |
60 |
Interval (in seconds) between checking for idle connections if shrinking is enabled. |
|
Enable Pool Shrinking |
*.enable_shrinking |
true |
Indicate whether the pool is allowed to shrink. |