Child pages
  • Using the FusionReactor JDBC Wrapper
Skip to end of metadata
Go to start of metadata

Configuration Options

The FusionReactor JDBC Driver Wrapper is configured exclusively using JDBC URL driver parameters. The following parameters may be specified as pairs, separated by semicolons.  No parameters are mandatory. Parameter names are case-insensitive.

driver

Value: Fully-qualified Java class name
Default:  no underlying driver will be loaded.

This option instructs FusionReactor JDBC Driver Wrapper to load an underlying wrapped driver. 

This is not necessary only if the JVM is already aware of the target driver (i.e. it has already been loaded with Class.forName(“...”) ). Macromedia's own DataDirect drivers are loaded automatically by ColdFusion, so this option may not be necessary if you are using these drivers.  However, if you are using a user-specified driver (having a JDBC URL which does not start with jdbc:macromedia), you must supply this parameter. 

Since the registration of the driver is only ever performed once, regardless of how many connections the driver processes, this parameter can (and should) be specified on all FusionReactor wrapped Data Sources.

If you do not specify this option, and the JVM is not aware of the underlying driver, FusionReactor will raise an exception and the J2EE server will not verify the driver.

rowLimit

Value:  integer
Default:  0 (disabled).

This option instructs the FusionReactor JDBC Driver Wrapper to limit returned rows to the given value.

After the application has retrieved this number of rows from the result set, FusionReactor will discard any remaining rows.

notifyAfter

Value: integer
Default: 0 (disabled).

This option instructs the FusionReactor JDBC Driver Wrapper to output a notification after 'n' rows have been retrieved for the query.

remindAfter

Value: integer
Default: 0 (disabled).

This option instructs the FusionReactor JDBC Driver Wrapper to periodically output a query reminder every 'n' rows.  If notifyAfter is specified, FusionReactor JDBC Driver Wrapper will only begin reminding after the notification threshold has been reached.  

E.g. notifyAfter=1000, remindAfter=100, actual rowcount 1350.
Notification occurs at row 1000, reminders at 1100, 1200 and 1300.

inhibitReformat

Value: Boolean
Default: false.

When tracking queries, the FusionReactor JDBC Driver Wrapper will reformat them for logging and presentation by attempting to make them fit on a single line. 

This allows logs to be viewed more easily, but may hinder developers who are used to seeing queries formatted a certain way (as they are written in a ColdFusion page, for example).  Setting this option to 'true' stops FusionReactor JDBC Driver Wrapper reformatting statement text, and allows multi-line presentation in the FusionReactor interface and log.

logToFusionReactor

Value: Boolean
Default: true.

If set to true (the default) and the FusionReactor JDBC Driver Wrapper detects a running FusionReactor instance, it will log the execution of a query to FusionReactors 'jdbc-X.log' (where 'X' is the current rolling log number). 

If this option is enabled and FusionReactor was not detected, it has no effect.

interpretObjects

Value: Boolean
Default: true.

If set to true (the default), when a PreparedStatement attempts to bind an Object type to a positional parameter using one of the setObject(...) methods, the wrapper will attempt to interpret the data (for logging and reporting purposes only) by calling the toString() method on the object.  This value will then be used in the log and FusionReactor administrator, as if the application had called a setString(...) method.  If the object does not override the default toString() method, the default behavior is to return the hash code of the object. 

If this parameter is false, the wrapper will use the format

{OBJECT java.class.name xyz}

where xyz is the .toString() representation.  This makes it clear that the parameter is of type Object, but is perhaps less easy to read in the log and the Administrator.

name

Value: string
Default: empty

If specified, the driver wrapper will report metrics to FusionReactor with the given name.  These names will be reported in the JDBC logfile (or as an empty value if not set).  The name will also be reflected in the JDBC tab of the Request Details page, allowing the user to differentiate queries which ran against more than one datasource.  This is useful when multiple databases are being used to aggregate results, or when different drivers are being tested.

cp

Value: comma-delimited list of strings pointing to jar files
Default: empty.

If specified, the driver wrapper will extend the search for the specified driver class to the jars pointed to by the files of this property.  By default, the driver wrapper relies on the J2EE engine to locate individual driver classes, but if they are not visible to FusionReactor, you may receive the exception message "driver class (classname) could not be found and loaded."  In this case, you might try adding the jar containing your driver to the cp property.

Users who previously used the split-jar procedure to work around this issue should read the section FusionReactor 4.5.0: Upgrading to 4.5.0 from the Split-Jar Procedure.

autoCommit

Value: Boolean
Default: true

If specified, the JDBC wrapper will turn off autocommit for all statements, regardless of the current status of autocommit, or the existence of any transactions.  This option must be used with extreme caution as it alters the default behaviour of the JDBC system, and is provided as a workaround to J2EE servers which require it to be disabled.  We do not recommend using this option to defeat autocommit.  After enabling this option, you must verify the atomicity and transactional integrity of your application's JDBC statements.

 

How To Specify These Options

These options pertain to the FusionReactor JDBC Driver Wrapper, and should therefore be specified outside of the curly braces used to wrap the original JDBC URL.   Any options which are required by the original JDBC URL should remain within the braced section.

Here's an example of a wrapped SQL Server JDBC URL, using the Macromedia driver, to which a couple of FusionReactor JDBC Driver Wrapper options have been added.  The material in bold illustrates the additional wrapper syntax:

jdbc:fusionreactor:wrapper:{jdbc:macromedia:sqlserver://int0007:1433;databaseName=frtest};notifyAfter=1000;remindAfter=200;inhibitReformat=true;name=DataWarehouse

You can see that in this example, the notifyAfter, remindAfter, inhibitReform and name options have all been specified.  The databaseName option pertains to the Macromedia driver, and are therefore within the braced section.

Sample JDBC URLs

Here are a few examples of URLs, wrapped with the FusionReactor Driver Wrapper.  This section is not an exhaustive reference on the syntax of each URL - you should check the documentation for each individual driver.  ColdFusion users:  in general we recommend downloading and using vendor-specific drivers if possible.  

Oracle (Macromedia)

Using the Macromedia driver, with the notifyAfter FusionReactor Driver Wrapper option:

jdbc:fusionreactor:wrapper:{jdbc:macromedia:oracle://int0234:1521;SID=testdb};notifyAfter=10000

MySQL (Macromedia)

Using the MySQL GJT driver, with the inhibitReformat FusionReactor Driver Wrapper option:

jdbc:fusionreactor:wrapper:{jdbc:mysql://int0003:3306/webshopdb?defaultFetchSize=400};inhibitReformat=true;driver=org.gjt.mm.mysql.Driver

MySQL 4/5 (MySQL Commercial)

Using the MySQL commercial driver (for example, supplied by Adobe in c:/ColdFusion10/cfusion/lib/mysql-connector-java-commercial-5.1.17-bin.jar)

 

jdbc:fusionreactor:wrapper:{jdbc:mysql://int00d6.bbn.intergral.com:3306/TestApp?tinyInt1isBit=false&};driver=com.mysql.jdbc.Driver;name=mysqldb;cp=c:/ColdFusion10/cfusion/lib/mysql-connector-java-commercial-5.1.17-bin.jar

MySQL 5 Connector/J (MySQL)

Here's an example using the MySQL Connector/J driver, downloadable from mysql.com.  It's installed in c:/mysql/mysql-connector-java-5.1.20-bin.jar.

 

jdbc:fusionreactor:wrapper:{jdbc:mysql://int00d6.bbn.intergral.com:3306/TestApp};driver=com.mysql.jdbc.Driver;name=mysqlj;cp=c:/mysql/mysql-connector-java-5.1.20-bin.jar

Microsoft SQL Server (Macromedia)

Using the Macromedia driver, with the remindAfter FusionReactor Driver Wrapper option (we've named this data source too):

jdbc:fusionreactor:wrapper:{jdbc:macromedia:sqlserver://int0007:1433;DatabaseName=frtest};remindAfter=500;name=SQLServerDataSource

Microsoft JDBC Driver 4.0 for SQL Server (Microsoft)

Here's a URL using the Microsoft SQL Server 2005 JDBC Driver – which is not supplied by Macromedia, and so must therefore be explicitly specified as the driver together with its jar, which we've placed in c:\jdbc.

jdbc:fusionreactor:wrapper:{jdbc:sqlserver://int00d0:1433;databaseName=AdventureWorks};driver=com.microsoft.sqlserver.jdbc.SQLServerDriver;name=testdb;cp=c:/jdbc/sqljdbc4.jar

In this example, the username and password must be specified separately during the connection process.  In ColdFusion, for example, the two fields can be entered in the DataSource Manager.  Here's an example where the username and password is specified in the URL:

jdbc:fusionreactor:wrapper:{jdbc:sqlserver://int00d0:1433;databaseName=AdventureWorks;user=scott;password=tiger};driver=com.microsoft.sqlserver.jdbc.SQLServerDriver;name=testdb;cp=c:/jdbc/sqljdbc4.jar

N.b. this example won't work in ColdFusion, because the username and password must be separately specified.

You can see in these examples that we've used the cp option to specify the jar, where previously you would have had to use the split-jar process.  Because the driver is no longer reliant on the system-supplied classloader, JDBC drivers can be loaded from anywhere, and the split-jar process is no longer required.  

Derby Embedded (Apache Derby)

The Apache Derby embedded database is an in-process (no separate server) database.  When this database driver is loaded, the database is started in the JVM process itself, a procedure which may only occur one time, until the database is subsequently stopped.  You should therefore only used this database with a wrapped datasource; you should not mix wrapped and unwrapped access to this datasource.  If you do mix these datasources, FusionReactor will attempt to share the connection with the wrapped and unwrapped datasource - which works in most cases - though this is an unsupported configuration.

 See Technote FRS-289: Using the JDBC Wrapper with Apache Derby Database on ColdFusion for more information.  

This URL explicitly specifies the driver, together with its jar, and the autocommit option - also explained at the link above.

jdbc:fusionreactor:wrapper:{jdbc:derby:C:/ColdFusion10/cfusion/db/bookclub/;create=false;MaxPooledStatements=300};driver=org.apache.derby.jdbc.EmbeddedDriver;name=bookclubdb;cp=c:/ColdFusion10/cfusion/lib/derby.jar;autocommit=false

And Finally...

... and as a quick reminder, the FusionReactor Driver Wrapper driver class is:

com.intergral.fusionreactor.jdbc.Wrapper

  • No labels