Cached connection manager in jboss/wildfly

Question

I have defined a datasource for JBoss AS 7.4, with min/max pool sizes, tracing of idle connections etc.

I am confused about the datasource use-ccm property.

• What does it do?
• Why use it?

I thought the datasource itself manages the connection pool.

Solution

What does it do?

It's just a useful debugging tool to detect connection leaks in manually managed transactions (BMT) by inspecting its logging. When turned on in debug mode, it will log all connections acquired and released by application code, along with the queries. This can be used to trackback connection leaks in application code.

The JBoss AS 5 Administration Guide does a better job in explaining this than the JBoss AS 7 Administration Guide and newer. It's even absent in WildFly documentation. Below extract is from the JBoss AS 5 guide:

3.1. Cached Connection Manager

The Cached Connection Manager is used for debugging data source connections and supporting lazy enlistment of a data source connection in a transaction, tracking whether they are used and released properly by the application. At the cost of some overhead, it can provide tracing of the usage, and make sure that connections from a data source are not leaked by your application. Although that seems like an advantage, in some instances it's considered an anti-pattern and so to be avoided.

[...]

In the default, standard and all configurations, the CachedConnectionManager is configured to be in the servlet container in debug mode. It's also configured in the production configuration but with debug mode off. If you do not use BMT, and/or you do not have the anti-pattern, described earlier, it's best to remove the CachedConnectionManager.

---

Why use it?

Only turn it on in debug mode when you aren't using container managed transactions (CMT), but are manually managing transactions (BMT) and you're having a connection leak problem which you couldn't nail down. Once found based on CCM's logging and fixed in application code, it is best to turn it back off to save performance.

If you're using CMT, i.e. you are nowhere in your application manually dealing with Connection and/or UserTransaction instances, but just letting EJB+JTA do their hard work, just keep it off.

---

I thought the datasource itself manages the connection pool.

It does that only between the server and the database. It does not do that between the server and the application code. When using CMT, this happens all automatically. When using BMT, the application code developer is responsible for that. When a connection leak is encountered in such case, CCM could be used to nail it down.

See also Mastertheboss.com - How to trace JDBC statements with JBoss and WildFly.

Comments

[assylias]

Thanks @BalusC. When turning it off I get a warning: "IJ000407: No lazy enlistment available for xxx". Can I safely ignore it?

[BalusC]

@assylias: You can ignore them. This is a known issue which is fixed in AS7. See also issue 1122 and the previous revision of this README (Ctrl+F on IJ000407)

[assylias]

I'm getting the warnings in wildfly 9 but, indeed, the link says that it can be ignored. Thanks.

[Chuck Doucette]

Without use-ccm, I run out of connections. When I add use-ccm="true", I do not run out of connections and I don't see any evidence of connection leak. Is it ok to leave use-ccm="true", or is there another way to find out where my connections are leaking?