Data Source Connection Labeling
By Steve Felts-Oracle on Jul 27, 2014
The connection labeling feature was added in WLS release 10.3.6. This feature has the potential to reduce the overhead when there is work to initialize a connection for application use. Labeling connections allows an application to attach arbitrary name/value pairs to a connection. The application can request a connection with the desired label from the connection pool. By associating labels with connection states, an application can retrieve an already initialized connection from the pool and avoid the time and cost of re-initialization. This feature is described in good detail including an example at http://docs.oracle.com/middleware/1213/wls/JDBCA/ds_labeling.htm .
Connection Labeling is enhanced in release WLS 12.1.3. For some applications, it's possible that making a connection conform if it doesn't match can be so expensive that a new connection should be created instead of using an existing connection but only up to some threshold. The enhancement introduces the notion of a "high-cost connection". There are two new connection properties that can be configured on the data source descriptor.
|New Connection Property||Default Value||Usage|
|ConnectionLabelingHighCost||Integer.MAX_VALUE||If connection label cost >= this value, considered high-cost connection.|
|HighCostConnectionReuseThreshold||0||When > 0, number of connections in pool when high-cost connections are re-used|
This following list spells out the rules in more detail when getting a connection using labeling properties. All available connections are evaluated to get their cost using the registered labeling callback.
- If the cost for a connection is greater than or equal to ConnectionLabelingHighCost, it is a High-Cost Connection.
- When the lowest-cost available connection is a High-Cost Connection, test current pool size against Reuse High-Cost Connection Threshold and against minimum pool size.
- If the current connection count is less than the minimum or threshold values, return a new connection instead of the high-cost connection.
- Otherwise (current connection count is greater than or equal to the threshold), return the lowest-cost High-Cost Connection.
- Labeled connections with cost value Integer.MAX_VALUE will never be reused (same as prior release).
- The maximum pool size constraint still holds (i.e. if threshold > maximum pool size, maximum pool size governs).
- The minimum pool size constraint holds (i.e. if threshold < minimum pool size, minimum pool size governs).
- Leaving the threshold unset results in same behavior as threshold = minimum (i.e., if current >= minimum, return the lowest-cost connection, which in this case is a High-Cost Connection).
- When there are no available connections, use the standard behavior. That is, return a new connection subject to maximum pool size. If the current size is greater than or equal to the maximum pool size, wait for a connection to be available, subject to the timeout, etc.
Here is a simplified sample configuration file.
<name>highcost_ds</name> <jdbc-driver-params> <url>jdbc:oracle:@//url</url> <driver-name>drivername</driver-name> <properties> <property> <name>ConnectionLabelingHighCost</name> <value>5</value> </property> <property> <name>user</name> <value>username</value> </property> <property> <name>HighCostConnectionReuseThreshold</name> <value>20</value> </property> </properties> </jdbc-driver-params> <jdbc-connection-pool-params> <initial-capacity>0</initial-capacity> <max-capacity>25</max-capacity> <test-table-name>SQL ISVALID</test-table-name> <connection-labeling-callback>demo.ConnectionLabelingCallbackImpl </connection-labeling-callback> </jdbc-connection-pool-params> <jdbc-data-source-params> <jndi-name>highcost_ds</jndi-name> <global-transactions-protocol>None</global-transactions-protocol> </jdbc-data-source-params>
The connection labeling properties can be configured in the properties text box in the administration console or can be created using WLST. In this example, a high cost connection has a cost greater than or equal to 5. The threshold is 20 connections, which is greater than the initial capacity of 0 and less than the maximum capacity of 25 so there is no interference. Note that in the configuration above, the connection labeling callback is registered in the configuration file; alternatively it can be registered in the application code.
The following table describes the behavior when ConnectionLabelingHighCost=5 and HighCostConnectionReuseThreshold=20 for various values of connection labeling cost.
|Total Connections in Pool||Minimum cost connection available||Action|
|0-19||None available||Create new connection|
|0-19||0-4||Use existing connection|
|0-19||>=5||Create new connection; don't use high-cost connection|
|>=20||None available||Create new connection|
|>=20||0-4||Use existing connection|
|>=20||5||Use existing high-cost connection|
There is a sample program for handling PDB switching in a Multi-Tenant Database environment using connection labeling at https://blogs.oracle.com/WebLogicServer/entry/part_3_12c_database_and . The sample uses the label to keep track of the PDB associated with each connection. The sample can't take advantage of this new feature because it always returns Integer.MAX_VALUE for a mismatch so the connections will never be reused. Instead, we could return some value that is equal to the configured ConnectionLabelingHighCost. Just by changing Integer.MAX_VALUE to 5 in the callback, we will create new connections up to 19 connections and then start reusing connections.
The connection labeling feature processing isn't free. The connection cost is computed for all available connections every time a connection is reserved. But in the case that connection initialization is expensive, it can perform much better.