This chapter provides information on how to configure and use connection harvesting in your applications in WebLogic Server 12.1.3.
This chapter includes the following sections:
You can specify a number of reserved connections to be released when a data source reaches a specified number of available connections. Harvesting helps to ensure that a specified number of connections are always available in the pool and improves performance by minimizing connection initialization.
Connection harvesting is particularly useful if an application caches connection handles. Caching is typically performed for performance reasons because it minimizes the initialization of state necessary for connections to participate in a transaction. For example: A connection is reserved from the data source, initialized with necessary session state, and then held in a context object. Holding connections in this manner may cause the connection pool to run out of available connections. Connection harvesting appropriately reclaims the reserved connections and allows the connections to be reused.
Use the following steps to use connection harvesting in your applications:
The Connection Harvest Trigger Count attribute of a data source configuration is used to enable and specify a threshold to trigger connection harvesting. For example, if Connection Harvest Trigger Count is set to 10, connection harvesting is enabled and the data source begins to harvest reserved connections when the number of available connections drops to 10. A value of -1, the default, indicates that connection harvesting is disabled.
When connection harvesting is triggered, the Connection Harvest Max Count specifies how many reserved connections should be returned to the pool. The number of connections actually harvested ranges from 1 to the value of Connection Harvest Max Count, depending on how many connections are marked harvestable.
See "Configure connection harvesting for a connection pool" in Oracle WebLogic Server Administration Console Online Help.
When connection harvesting is enabled, all connections are initially marked harvestable. If you do not want a connection to be harvestable, you must explicitly mark it as unharvestable by calling the setConnectionHarvestable(boolean) method in the oracle.ucp.jdbc.HarvestableConnection interface with false as the argument value.
For example, use the following statements to prevent harvesting when a transaction is used within a transaction:
. . . Connection conn = datasource.getConnection(); ((HarvestableConnection) conn).setConnectionHarvestable(false); . . .
After work with the connection is completed, you can mark the connection as harvestable by setting setConnectionHarvestable(true) so the connection can be harvested if required. You can tell the harvestable status of a connection by calling isConnectionHarvestable().
When a connection is harvested, an application callback is executed to cleanup the connection if the callback has been registered. A unique callback must be generated for each connection; generally it needs to be initialized with the connection object. For example:
import java.sql.Connection;
. . .
public myHarvestingCallback implements ConnectionHarvestingCallback {
private Connection conn;
mycallback(Connection conn) {
this.conn = conn;
}
public boolean cleanup() {
try {
conn.close();
} catch (Exception ignore) {
return false;
}
return true;
}
}
. . .
Connection conn = ds.getConnection();
try {
(HarvestableConnection)conn).registerConnectionHarvestingCallback(
new myHarvestingCallback(conn));
(HarvestableConnection)conn).setConnectionHarvestable(true);
} catch (Exception exception) {
// This can't be from registration – setConnectionHarvestable must have failed.
// That most likely means that the connection has already been harvested.
// Do whatever logic is necessary to clean up here and start over.
throw new Exception("Need to get a new connection");
}
. . .
Note:
Consider the following:After a connection is harvested, an application can only call Connection.close.
If the connection is not closed by the application, a warning is logged indicating that the connection was forced closed if LEAK profiling is enabled.
If the callback throws an exception, a message is logged and the exception is ignored. Use JDBCCONN debugging to retrieve a full stack trace.
The return value of the cleanup method is ignored.
Connection harvesting releases reserved connections that are marked harvestable by the application when a data source falls to a specified number of available connections. By default, this check is performed every 30 seconds. You can tune this behavior using the weblogic.jdbc.harvestingFrequencySeconds system property which specifies the amount of time, in seconds, the system waits before harvesting marked connections. Setting this system property to less than 1 disables harvesting.