Chapter 4. JDBC
Prev | Part 3. Reference Guide | Next

## Chapter 4. JDBC

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.

## 1. Using the OpenJPA DataSource

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.

### 1.1. Optional Connection Pooling

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 DBCP 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 DBCP, so you will need to include the `commons-dbcp.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 DBCP, 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.openjpa.jdbc.schema.DBCPDriverDataSource`

### 1.2. Configuring the OpenJPA DataSource

If you choose to use OpenJPA's `DataSource`, then you must specify the following properties:

- `openjpa.ConnectionUserName`: The JDBC user name for connecting to the database.

- `openjpa.ConnectionPassword`: The JDBC password for the above user.

- `openjpa.ConnectionURL`: The JDBC URL for the database.

- `openjpa.ConnectionDriverName`: The JDBC driver class.

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"/>

### 1.3. Configuring Apache Commons DBCP

Additional Commons DBCP arguments can be provided in `openjpa.connectionProperties`, such as:

        MaxActive=10,MaxIdle=5,MinIdle=2,MaxWait=60000

Please visit the Commons DBCP website for the entire list of configuration options and explanations.

Prev | Up | Next
8. OpenJPA Audit | Home | 2. Using a Third-Party DataSource