This chapter provides information on how to configure and use connection harvesting in your applications. The chapter includes the following sections:
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.
Note:
In WebLogic Server 12.2.1.1.0 and earlier releases, do not enable harvesting on data sources that are referenced by WebLogic JDBC or TLOG-in-DB stores. Harvesting may destabilize such stores, which can in turn destabilize WebLogic JMS or WebLogic JTA. If you want to enable harvesting on a data source used by WebLogic JDBC or TLOG-in-DB stores in WebLogic Server 12.2.1.1.0 and earlier releases, contact Oracle Support for a patch that protects their store connections from getting harvested.Use the following steps to use connection harvesting in your applications:
To enable and specify a threshold to trigger connection harvesting, use Connection Harvest Trigger Count data source attribute.
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. See Connection Harvest Trigger Count
.
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.