6. OpenJPA JDBC Properties
Prev | Chapter 2. Configuration | Next

## 6. OpenJPA JDBC Properties

The following properties apply exclusively to the OpenJPA JDBC back-end.

### 6.1. openjpa.jdbc.ConnectionDecorators

Property name: `openjpa.jdbc.ConnectionDecorators`

Configuration API: `org.apache.openjpa.jdbc.conf.JDBCConfiguration.getConnectionDecorators`

Resource adaptor config-property: `ConnectionDecorators`

Default: -

Description: A comma-separated list of plugin strings (see Section 4, “ Plugin Configuration ”) describing `org.apache.openjpa.lib.jdbc.ConnectionDecorator` instances to install on the connection factory. These decorators can wrap connections passed from the underlying `DataSource` to add functionality. OpenJPA will pass all connections through the list of decorators before using them. Note that by default OpenJPA employs all of the built-in decorators in the `org.apache.openjpa.lib.jdbc` package already; you do not need to list them here.

### 6.2. openjpa.jdbc.DBDictionary

Property name: `openjpa.jdbc.DBDictionary`

Configuration API: `org.apache.openjpa.jdbc.conf.JDBCConfiguration.getDBDictionary`

Resource adaptor config-property: `DBDictionary`

Default: Based on the `openjpa.ConnectionURL` `openjpa.ConnectionDriverName`

Description: A plugin string (see Section 4, “ Plugin Configuration ”) describing the `org.apache.openjpa.jdbc.sql.DBDictionary` to use for database interaction. OpenJPA typically auto-configures the dictionary based on the JDBC URL, but you may have to set this property explicitly if you are using an unrecognized driver, to plug in your own dictionary for a database OpenJPA does not support out-of-the-box, or if you like to change the default configuration of an existing dictionary. See Section 4, “ Database Support ” for details.

### 6.3. openjpa.jdbc.DriverDataSource

Property name: `openjpa.jdbc.DriverDataSource`

Configuration API: `org.apache.openjpa.jdbc.conf.JDBCConfiguration.getDriverDataSource`

Resource adaptor config-property: `DriverDataSource`

Default: `auto`

Possible values: `auto`, `dbcp`, `simple`

Description: The alias or full class name of the `org.apache.openjpa.jdbc.schema.DriverDataSource` implementation to use to wrap JDBC Driver classes with javax.sql.DataSource instances. The `org.apache.openjpa.jdbc.schema.AutoDriverDataSource` implementation is the default and will select either the DBCPDriverDataSource or SimpleDriverDataSource based on if Apache Commons DBCP is available on the classpath. The `org.apache.openjpa.jdbc.schema.DBCPDriverDataSource` implementation requires Apache Commons DBCP to be available on the classpath and uses `org.apache.commons.dbcp.BasicDataSource` to provide connection pooling.

### 6.4. openjpa.jdbc.EagerFetchMode

Property name: `openjpa.jdbc.EagerFetchMode`

Configuration API: `org.apache.openjpa.jdbc.conf.JDBCConfiguration.getEagerFetchMode`

Resource adaptor config-property: `EagerFetchMode`

Default: `parallel`

Possible values: `parallel`, `join`, `none`

Description: Optimizes how OpenJPA loads persistent relations. This setting can also be varied at runtime. See Section 8, “ Eager Fetching ” for details.

### 6.5. openjpa.jdbc.FetchDirection

Property name: `openjpa.jdbc.FetchDirection`

Configuration API: `org.apache.openjpa.jdbc.conf.JDBCConfiguration.getFetchDirection`

Resource adaptor config-property: `FetchDirection`

Default: `forward`

Possible values: `forward`, `reverse`, `unknown`

Description: The expected order in which query result lists will be accessed. This property can also be varied at runtime. See Section 10, “ Large Result Sets ” for details.

### 6.6. openjpa.jdbc.JDBCListeners

Property name: `openjpa.jdbc.JDBCListeners`

Configuration API: `org.apache.openjpa.jdbc.conf.JDBCConfiguration.getJDBCListeners`

Resource adaptor config-property: `JDBCListeners`

Default: -

Description: A comma-separated list of plugin strings (see Section 4, “ Plugin Configuration ”) describing `org.apache.openjpa.lib.jdbc.JDBCListener` event listeners to install. These listeners will be notified on various JDBC-related events.

### 6.7. openjpa.jdbc.LRSSize

Property name: `openjpa.jdbc.LRSSize`

Configuration API: `org.apache.openjpa.jdbc.conf.JDBCConfiguration.getLRSSize`

Resource adaptor config-property: `LRSSize`

Default: `query`

Possible values: `query`, `last`, `unknown`

Description: The strategy to use to calculate the size of a result list. This property can also be varied at runtime. See Section 10, “ Large Result Sets ” for details.

### 6.8. openjpa.jdbc.MappingDefaults

Property name: `openjpa.jdbc.MappingDefaults`

Configuration API: `org.apache.openjpa.jdbc.conf.JDBCConfiguration.getMappingDefaults`

Resource adaptor config-property: `MappingDefaults`

Default: jpa

Description: A plugin string (see Section 4, “ Plugin Configuration ”) describing the `org.apache.openjpa.jdbc.meta.MappingDefaults` to use to define default column names, table names, and constraints for your persistent classes. See Section 5, “ Mapping Factory ” for details.

### 6.9. openjpa.jdbc.MappingFactory

Property name: `openjpa.jdbc.MappingFactory`

Configuration API: `org.apache.openjpa.jdbc.conf.JDBCConfiguration.getMappingFactory`

Resource adaptor config-property: `MappingFactory`

Default: -

Description: A plugin string (see Section 4, “ Plugin Configuration ”) describing the `org.apache.openjpa.meta.MetaDataFactory` to use to store and retrieve object-relational mapping information for your persistent classes. See Section 5, “ Mapping Factory ” for details.

### 6.10. openjpa.jdbc.QuerySQLCache

Property name: `openjpa.jdbc.QuerySQLCache`

Resource adaptor config-property: `QuerySQLCache`

Default: `true`.

Description: A plugin string (see Section 4, “ Plugin Configuration ”) describing the options to cache and reuse SQL statements generated for JPQL queries. See Section 3, “Prepared SQL Cache” for details.

### 6.11. openjpa.jdbc.ResultSetType

Property name: `openjpa.jdbc.ResultSetType`

Configuration API: `org.apache.openjpa.jdbc.conf.JDBCConfiguration.getResultSetType`

Resource adaptor config-property: `ResultSetType`

Default: `forward-only`

Possible values: `forward-only` , `scroll-sensitive`, `scroll-insensitive`

Description: The JDBC result set type to use when fetching result lists. This property can also be varied at runtime. See Section 10, “ Large Result Sets ” for details.

### 6.12. openjpa.jdbc.Schema

Property name: `openjpa.jdbc.Schema`

Configuration API: `org.apache.openjpa.jdbc.conf.JDBCConfiguration.getSchema`

Resource adaptor config-property: `Schema`

Default: -

Description: The default schema name to prepend to unqualified table names. Also, the schema in which OpenJPA will create new tables. See Section 11, “ Default Schema ” for details.

### 6.13. openjpa.jdbc.SchemaFactory

Property name: `openjpa.jdbc.SchemaFactory`

Configuration API: `org.apache.openjpa.jdbc.conf.JDBCConfiguration.getSchemaFactory`

Resource adaptor config-property: `SchemaFactory`

Default: `dynamic`

Possible values: `dynamic`, `native`, `file`, `table`, others

Description: A plugin string (see Section 4, “ Plugin Configuration ”) describing the `org.apache.openjpa.jdbc.schema.SchemaFactory` to use to store and retrieve information about the database schema. See Section 12.2, “ Schema Factory ” for details.

### 6.14. openjpa.jdbc.Schemas

Property name: `openjpa.jdbc.Schemas`

Configuration API: `org.apache.openjpa.jdbc.conf.JDBCConfiguration.getSchemas`

Resource adaptor config-property: `Schemas`

Default: -

Description: A comma-separated list of the schemas and/or tables used for your persistent data. See Section 12.1, “ Schemas List ” for details.

### 6.15. openjpa.jdbc.SQLFactory

Property name: `openjpa.jdbc.SQLFactory`

Configuration API: `org.apache.openjpa.jdbc.conf.JDBCConfiguration.getSQLFactory`

Resource adaptor config-property: `SQLFactory`

Default: `default`

Description: A plugin string (see Section 4, “ Plugin Configuration ”) describing the `org.apache.openjpa.jdbc.sql.SQLFactory` to use to abstract common SQL constructs.

### 6.16. openjpa.jdbc.SubclassFetchMode

Property name: `openjpa.jdbc.SubclassFetchMode`

Configuration API: `org.apache.openjpa.jdbc.conf.JDBCConfiguration.getSubclassFetchMode`

Resource adaptor config-property: `SubclassFetchMode`

Default: `parallel`

Possible values: `parallel`, `join`, `none`

Description: How to select subclass data when it is in other tables. This setting can also be varied at runtime. See Section 8, “ Eager Fetching ”.

### 6.17. openjpa.jdbc.SynchronizeMappings

Property name: `openjpa.jdbc.SynchronizeMappings`

Configuration API: `org.apache.openjpa.jdbc.conf.JDBCConfiguration.getSynchronizeMappings`

Resource adaptor config-property: `SynchronizeMappings`

Default: -

Description: Controls whether OpenJPA will attempt to run the mapping tool on all persistent classes to synchronize their mappings and schema at runtime. Useful for rapid test/debug cycles. See Section 1.3, “ Runtime Forward Mapping ” for more information.

### 6.18. openjpa.jdbc.TransactionIsolation

Property name: `openjpa.jdbc.TransactionIsolation`

Configuration API: `org.apache.openjpa.jdbc.conf.JDBCConfiguration.getTransactionIsolation`

Resource adaptor config-property: `TransactionIsolation`

Default: `default`

Possible values: `default`, `none`, `read-committed`, `read-uncommitted`, `repeatable-read`, `serializable`

Description: The JDBC transaction isolation level to use. See Section 5, “ Setting the Transaction Isolation ” for details.

### 6.19. openjpa.jdbc.UpdateManager

Property name: `openjpa.jdbc.UpdateManager`

Configuration API: `org.apache.openjpa.jdbc.conf.JDBCConfiguration.getUpdateManager`

Resource adaptor config-property: `UpdateManager`

Default: `batching-constraint`

Possible values: `default`, `operation-order`, `constraint`, `batching-constraint`, `batching-operation-order`

Description: The full class name of the `org.apache.openjpa.jdbc.kernel.UpdateManager` to use to flush persistent object changes to the datastore. The provided default implementation is `org.apache.openjpa.jdbc.kernel.BatchingConstraintUpdateManager` .

### 6.20. Compatibility with Specification

The default behavior of certain OpenJPA API methods can evolve to align with the behaviors defined in JPA specification. To maintain backward compatibility, OpenJPA allows configuration options such that while the default behavior changes to align with current JPA specification, the previous behaviors can always be emulated.

For example, JPA 2.0 specification introduces a new API `void EntityManager.detach(Object entity)` that detaches the given entity from the current persistence context. OpenJPA has provided similar feature via `<T> T OpenJPAEntityManager.detach(T entity)` prior to JPA 2.0. OpenJPA `detach()`, however, has different default behavior than what JPA 2.0 specification mandates. Firstly, OpenJPA creates a copy of the given entity as a detached instance and returns it, whereas JPA 2.0 behavior requires the same given entity instance be detached. Secondly, the given instance is removed from the persistence context for JPA 2.0, whereas OpenJPA `detach()` method, prior to JPA 2.0, does not remove the instance from the persistence context as a copy is returned. Thirdly, OpenJPA will flush before detaching a dirty instance so that the detached instance can later be merged, whereas JPA 2.0 `detach()` semantics does not require a dirty instance be flushed before detach.

A user application running with OpenJPA that is compliant to a specific version of JPA specification can emulate the older behavior by configuring OpenJPA compatibility options. For example, `openjpa.Compatibility=FlushBeforeDetach=false,CopyOnDetach=true` will emulate the older behavior of detach even when running with OpenJPA that is compliant to JPA 2.0 specification. The configuration can also be set to a different version of the specification. For example, `openjpa.Specification="JPA 1.0"` configuration setting will emulate default OpenJPA behavior as it were for JPA specification version 1.0. Setting `openjpa.Specification` is a shorthand for more fine-grained control available via `openjpa.Compatibility`.

Prev | Up | Next
5. OpenJPA Properties | Home | Chapter 3. Logging and Auditing