Table of Contents
OpenJPA uses a relational database for object persistence. It communicates with the database using the Java DataBase Connectivity (JDBC) APIs. This chapter describes how to configure OpenJPA to work with the JDBC driver for your database, and how to access JDBC functionality at runtime.
OpenJPA defines a org.apache.openjpa.jdbc.schema.DriverDataSource interface, which provides a simple javax.sql.DataSource wrapper implementation for the normal cases where openjpa.ConnectionDriverName refers to a java.sql.Driver.
See
openjpa.jdbc.DriverDataSource for the list of
provided implementations.
Starting with OpenJPA 2.1, a new org.apache.openjpa.jdbc.schema.AutoDriverDataSource
is provided as the default, which will automatically
select between the old SimpleDriverDataSource and a new
DBCPDriverDataSource implementation based on if
Apache Commons DBCP2
has been provided on the classpath and OpenJPA is not running in a container
managed mode or with managed transactions. Note, that only the
openjpa-all.jar includes Commons DBCP2, so you will need to
include the commons-dbcp2.jar from the OpenJPA binary
distribution if you are using the normal openjpa.jar.
To disable the automatic usage of Apache Commons DBCP when it is discovered
on the classpath, set
openjpa.jdbc.DriverDataSource=simple, which will revert
OpenJPA to the prior behavior of using org.apache.openjpa.jdbc.schema.SimpleDriverDataSource
To force usage of Apache Commons DBCP2, which will cause a fatal exception to
be thrown if it cannot be loaded from the classpath, set
openjpa.jdbc.DriverDataSource=dbcp, which will cause
OpenJPA to use org.apache.commons.dbcp2.BasicDataSource
If you choose to use OpenJPA's DataSource,
then you must specify the following properties:
To configure advanced features, use the following optional properties. The syntax of these property strings follows the syntax of OpenJPA plugin parameters described in Section 4, “ Plugin Configuration ”.
openjpa.ConnectionProperties: If the listed driver is an
instance of java.sql.Driver, this string will be parsed
into a Properties instance, which will then be used to
obtain database connections through the Driver.connect(String url,
Properties props) method. If, on the other hand, the listed driver
is a javax.sql.DataSource, the string will be treated
as a plugin properties string, and matched to the bean setter methods of the
DataSource instance.
openjpa.ConnectionFactoryProperties: OpenJPA's built-in
DataSource allows you to set the following options via
this plugin string:
QueryTimeout: The maximum number of seconds the JDBC driver
will wait for a statement to execute.
PrettyPrint: Boolean indicating whether to pretty-print
logged SQL statements.
PrettyPrintLineLength: The maximum number of characters in
each pretty-printed SQL line.
PrintParameters: A boolean indicating whether SQL parameter
values will be included in exception text and when logging is enabled. Since
the parameter values may contain sensitive information the default value is
false.
Example 4.1. Properties for the OpenJPA DataSource
<property name="openjpa.ConnectionUserName" value="user"/>
<property name="openjpa.ConnectionPassword" value="pass"/>
<property name="openjpa.ConnectionURL" value="jdbc:hsqldb:db-hypersonic"/>
<property name="openjpa.ConnectionDriverName" value="org.hsqldb.jdbcDriver"/>
<property name="openjpa.ConnectionFactoryProperties"
value="PrettyPrint=true, PrettyPrintLineLength=80, PrintParameters=true"/>
Additional Commons DBCP arguments can be provided in
openjpa.connectionProperties, such as:
MaxTotal=10,MaxIdle=5,MinIdle=2,MaxWait=60000
Please visit the Commons DBCP website for the entire list of configuration options and explanations.