Flush strategies for datasource connection pools in JBoss EAP

Environment

• Red Hat JBoss Enterprise Application Platform (EAP)
  • 6
  • 7
• Use of the flush-strategy attribute as defined by the following schemas in <JBOSS HOME>/docs/schema:
  • jboss-as-datasources_1_0.xsd
  • jboss-as-datasources_1_1.xsd
  • jboss-as-datasources_1_2.xsd
  • jboss-as-resource-adapters_1_0.xsd
  • jboss-as-resource-adapters_1_1.xsd

Issue

• What flush strategy should I use?
• What are the FLUSH strategies in JBoss datasource connection pools?
• When does JBoss flush the pool?
• If we set the the flush strategy on the pool to EntirePool, does that interrupt or force-close active connections that are otherwise functional?
• What are the implications of using the flush operation for datasources via the Jboss Management console?

Resolution

JBoss will flush one or more connections when an error indicating a loss of connectivity to the backing resource (as detected by the configured exception sorter) is detected on a single connection while the connection is in-use by application components (i.e. while it is reserved/checked out from the pool).

Note that a single JBoss managed datasource may be associated with multiple sets of connections when different credentials are used to Content from docs.oracle.com is not included.authenticate with the specified datasource. The sets are, thus, divided based on credentials. Some of the flush strategies below are limited to the set of connections which share the same credentials as the connection on which failure was initially detected.

JBoss EAP 6 supports three options for flush strategies as detailed in the This content is not included.pooling section of the Administration and Configuration guide.

• FailingConnectionOnly (default)
  • The failing connection is removed, no other connections are affected.
• IdleConnections
  • The failing connection is removed along with idle connections for the datasource which share the same credentials as the failing connection.
• EntirePool
  • The failing connection is removed along with idle and active connections for the datasource which share the same credentials as the failing connection.
  • Termination of active connections may result in application errors (which may include deadlocks depending on the underlying driver implementation) as connections may be closed while they are in use by application code.
  • This setting is usually not appropriate for production systems and is not recommended for such.

JBoss EAP 7 and later releases add (to the above) the following additional strategies

• AllIdleConnections
  • Same as IdleConnections but not limited to connections using the same credentials as the failing connection.
• InvalidIdleConnections
  • The failing connection is removed along with any idle connections which are found to be invalid based on the return of javax.resource.spi.ValidatingManagedConnectionFactory.getInvalidConnections(...) if they also share the the credentials used by the failing connection.
• AllInvalidIdleConnections
  • Same as InvalidIdleConnections but not limited to connections using the same credentials as the failing connection.
• AllConnections
  • Same as EntirePool but not limited to connections using the same credentials as the failing connection.
  • This setting is usually not appropriate for production systems and is not recommended for such.
• Gracefully
  • The failing connection is removed along with all idle connections which share the same credentials as the failing connection.
  • Connections active at the time of flush which share the same credentials as the failing connection will be destroyed upon return to the pool.
• AllGracefully
  • Same as Gracefully but not limited to connections using the same credentials as the failing connection.

For manually flushing the connection pool please see flush a datasource connection pool in JBoss EAP.

Update via CLI (standalone configuration)

# Use <tab> after typing 'value' to list supported flush mechanisms
[standalone@localhost:9990 /] /subsystem=datasources/data-source=ExampleDS:write-attribute(name=flush-strategy, value=
AllConnections             AllIdleConnections         EntirePool                 Gracefully                 InvalidIdleConnections
AllGracefully              AllInvalidIdleConnections  FailingConnectionOnly      IdleConnections            

# Apply the 'AllIdleConnections' strategy
[standalone@localhost:9990 /] /subsystem=datasources/data-source=ExampleDS:write-attribute(name=flush-strategy, value=AllIdleConnections)
{
    "outcome" => "success",
    "response-headers" => {
        "operation-requires-reload" => true,
        "process-state" => "reload-required"
    }
}

# Reload the configuration (reload required to apply pool configuration changes)
[standalone@localhost:9990 /] reload

Example XML

<datasource jndi-name="java:jboss/datasources/ExampleDS" pool-name="ExampleDS" enabled="true" use-java-context="true">
    <connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE</connection-url>
        <driver>h2</driver>
        <pool>
            ....
	    <flush-strategy>AllIdleConnections</flush-strategy>
   	</pool>
	...
</datasource>

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.