[frs-240] Standalone FR JDBC Wrapper Driver (for MySQL Connector/J etc.)

FusionReactor 4.5.0+…

Customers using FusionReactor 4.5.0 and above must not apply this technote. This issue has been resolved with the addition of a cp option to the JDBC driver wrapper. See Using the FusionReactor Driver Wrapper for more information.

Customers who have already applied FRS-240 to versions of FusionReactor prior to 4.5.0, and who plan to upgrade to 4.5.0 or greater should read FRS-296: "FusionReactor 4.5.0: Briefer for Split-Jar JDBC Wrapper Users".

Please Note…

This article applies to FusionReactor 3.5.x and 4.0.x. Customers with FusionReactor 3.0.1 should use Hotfix FR-1643.


Customers using FusionReactor in environments where the FusionReactor JDBC Driver Wrapper (and subsequent wrapped driver) is loaded by a different classloader than that used to load the FusionReactor system filter may observe one or more of the following issues:

  • The J2EE engine fails to find the FusionReactor JDBC Driver Wrapper (ClassNotFoundException).
  • The J2EE engine finds the FusionReactor JDBC Driver Wrapper but the wrapper cannot find an in-memory accessible instance of the FusionReactor system; in which case the wrapper will degrade to logging to the console.
  • The J2EE engine finds the FusionReactor JDBC Driver Wrapper, and the wrapper does locate an in-memory accessible instance of the FusionReactor system, but when attempting to send JDBC metrics to the system, encounters a class type mismatch (ClassCastException).
  • Customers attempting to verify their wrapped drivers with their J2EE engines (e.g. from within the ColdFusion Administrator) may receive the message Driver could not be found and loaded

These symptoms occur mostly in situations where:

  • FusionReactor has been deployed manually, or
  • Customers are using third-party JDBC driver jars in JRun/ColdFusion, which previously had to have been copied to SERVER-INF/lib


The problem is due to the way J2EE engines partition their classloaders. The FusionReactor system filter must be loaded either at the same level of a classloader hierarchy as JDBC Driver Wrapper or a higher level. If this invariant is not satisfied, the exceptions mentioned above may be raised.

In the past, we have encouraged customers using ColdFusion to transition to third-party drivers, where their location and position within the classloader hierarchy can be fully controlled, and to install the jars for these drivers alongside the installed fusionreactor.jar. However, certain customers who are using Macromedia (Merant/Data-Direct) drivers are unable to move these drivers because of a licensing restriction imposed on Adobe by the supplier of these drivers. This problem usually occurs in environments where ColdFusion has been installed as an EAR/WAR deployment within a J2EE engine.

We have resolved this issue by re-writing the interface between the FusionReactor system filter and the FusionReactor JDBC Driver Wrapper to be independent of classloader. As long as the FusionReactor system filter has been loaded by the same (or higher) classloader as the FusionReactor JDBC Driver Wrapper and subsequent wrapped driver, there should be no issues concerning communication between the two.

Third-Party (OEM) JDBC Driver Jars

It is no longer necessary to move third-party driver JAR files (e.g. MySQL Connector/J, JTDS etc.) to the SERVER-INF/lib folder. After updating the system fusionreactor.jar using the procedure below, the The fusionreactor-jdbc.jar file should be installed in ColdFusion/lib alongside the third-party JDBC driver jar file. The wrapped datasource should then verify correctly.


Customers with FusionReactor 3.5.0 or later only should perform the following procedure. This consists of installing a new system fusionreactor-core.jar (with which you should replace your existing copy of fusionreactor.jar) and a new fusionreactor-jdbc.jar. This latter file should be placed in the same folder as your JDBC drivers.

  1. Ensure the J2EE engine can locate, load and use the unwrapped data source.
  2. Locate the two new split jars within your /FusionReactor/etc/lib folder. These are named fusionreactor-core.jar and fusionreactor-jdbc.jar.
  3. Locate the existing installed fusionreactor.jar file, for example ColdFusion9/runtime/servers/coldfusion/SERVER-INF/lib/fusionreactor.jar
  4. Stop your J2EE (e.g. ColdFusion Application Server) engine.
  5. Make a copy of the installed .../SERVER-INF/lib/fusionreactor.jar and store this safely, in case a rollback is required.
  6. Remove the installed .../SERVER-INF/lib/fusionreactor.jar file and replace it with the fusionreactor-core.jar file, renaming it fusionreactor.jar after copying.
  7. Copy the fusionreactor-jdbc.jar to the same location as the jar containing your unwrapped JDBC driver.
  8. Restart the engine and attempt to verify the datasource.

Issue Details

Type: Technote
Issue Number: FRS-240
Components: JDBC
Resolution: Fixed
Last Updated: 14/May/12 4:54 PM
Affects Version: 3.5
Fixed Version: 3.5, 4.0.0
Server: JBoss, Jetty, JRun 4, Railo, Resin, Tomcat, WebSphere, WebLogic
Related Issues:

FRS-258: Updating a FusionReactor 3.x split-jar installation to 4.x