The ConnectionFactory class provides JDBC connection objects to the DbForms client (specifically, to the org.dbforms.util.DbConnection class). It gives a common interface to retrieve connection objects, but defer the database interaction to specialized connectionProvider classes.
The connectionFactory use is optional and must be enabled
to work, so it will not be used if the new properties are not declared as shown below.
dbconnection configuration is still compatible with
previous means such as:
<dbconnection
name = "java:comp/env/jdbc/resource"
isJndi = "true" />
where jdbc/resource should match a
resource defined in the servlet container and
<dbconnection
name = "jdbc:mysql://localhost/test"
isJndi = "false"
conClass = "org.gjt.mm.mysql.Driver"
username = "somename"
password = "somepass" />
The connectionFactory package provides three connectionProvider classes; the jars for these classes need to be downloaded and put in your applications WEB-INF/lib directory.
Protomatter rquires protomatter.jar
JakartaConnectionPool requires commons-dbcp.jar
ProtomatterConnectionProvider
Provides connection objects using the Protomatter Connection Pool library
http://protomatter.sourceforge.net/
class name: org.dbforms.conprovider.ProtomatterConnectionProvider
JakartaConnectionProvider
Provides connection objects using the Jakarta commons-dbcp ConnectionPool library
http://jakarta.apache.org/commons/index.html
class name:
org.dbforms.conprovider.JakartaConnectionProvider
SimpleConnectionProvider
Provides connection objects, but does not use connection pool components.
class name:
org.dbforms.conprovider.SimpleConnectionProvider
The examples below show how to configure the "dbconnection" xml element contained in the dbforms-config.xml file.
<!--
- uses the Protomatter ConnectionPool
-
- see http://protomatter.sourceforge.net/ for further information
-->
<dbconnection
id = "protomatter"
isJndi = "false"
isPow2 = "true"
default = "true"
connectionProviderClass = "org.dbforms.conprovider.ProtomatterConnectionProvider"
connectionPoolURL = "jdbc:protomatter:pool:postgresPool"
conClass = "org.postgresql.Driver"
name = "jdbc:postgresql://localhost/myDatabase?charSet=ISO-8859-1"
username = "postgres"
password = ""/>
<!-
- uses the Jakarta commons-dbcp ConnectionPool
-
- see http://jakarta.apache.org/commons/index.html for further informations
-
- Note: this provider does NOT use the connectionPoolURL attribute.
-->
<dbconnection
id = "jakarta-commons-dbcp"
isJndi = "false"
isPow2 = "true"
default = "false"
connectionProviderClass = "org.dbforms.conprovider.JakartaConnectionProvider"
connectionPoolURL = ""
conClass = "org.postgresql.Driver"
name = "jdbc:postgresql://localhost/myDatabase?charSet=ISO-8859-1"
username = "postgres"
password = ""/>
<!-
- DOES NOT use connection pooling !!!
-
- Note: this provider does NOT use the connectionPoolURL attribute.
-->
<dbconnection
id = "simple"
isJndi = "false"
isPow2 = "true"
connectionProviderClass = "org.dbforms.conprovider.SimpleConnectionProvider"
connectionPoolURL = ""
conClass = "org.postgresql.Driver"
name = "jdbc:postgresql://localhost/myDatabase?charSet=ISO-8859-1"
username = "postgres"
password = ""/>
| id | string identifier for the dbconnection element. Gives the dbconnection an alpha-numeric name. Otherwise it is referred to by the order it was configured with the first 'dbconnection' starting at zero. |
| default | boolean value, specify that the current 'dbconnection'element specifies the default connection. The default connection is used by all the data access tags that don't specify a 'dbConnectionName' attribute value. |
| isJndi | boolean value, specify that the connection objects are retrieved using a JNDI service. |
| isPow2 | boolean value, specify that the connectionFactory class will be used to objain jdbc connection objects [better to use “useConnectionFactory”, don't you think so ?]. |
| connectionProviderClass | the full qualified class name of the connectionProvider class. |
| connectionPoolURL | the connection pool url string. Used by ProtomatterConnectionProvider class. |
| conClass | the JDBC driver connection class string |
| name | the JDBC URL string |
| username | database user name value |
| password | database password value |
To set jdbc properties in jdbc drivers that can't specify properties using the JDBC url, you can nest property tags inside the dbconnection tag:
<dbconnection> <property name="charSet" value="8859_1" /> </dbconnection>
This properties will result in a DriverManager.getConnection(url, properties) call. It is not necessary to include the username and the password in the property list, this will be handled by the connection class.
Currently properties are supported for native connections (isJNDI=false, isPow2=false) and for connection with the Connection factory (isPow2=true). Example:
<dbconnection id = "simple" isPow2 = "true" connectionProviderClass = "org.dbforms.conprovider.SimpleConnectionProvider" connectionPoolURL = "" name = "jdbc:mysql://localhost/test" isJndi = "false" conClass = "org.gjt.mm.mysql.Driver" username = "secret" password = "howdidyoufindout"> <property name="useUnicode" value="true" /> <property name="characterEncoding" value="Shift_JIS" /> </dbconnection>