6.  OpenJPA JDBC Properties

6.1. openjpa.jdbc.ConnectionDecorators
6.2. openjpa.jdbc.DBDictionary
6.3. openjpa.jdbc.DriverDataSource
6.4. openjpa.jdbc.EagerFetchMode
6.5. openjpa.jdbc.FetchDirection
6.6. openjpa.jdbc.JDBCListeners
6.7. openjpa.jdbc.LRSSize
6.8. openjpa.jdbc.MappingDefaults
6.9. openjpa.jdbc.MappingFactory
6.10. openjpa.jdbc.QuerySQLCache
6.11. openjpa.jdbc.ResultSetType
6.12. openjpa.jdbc.Schema
6.13. openjpa.jdbc.SchemaFactory
6.14. openjpa.jdbc.Schemas
6.15. openjpa.jdbc.SQLFactory
6.16. openjpa.jdbc.SubclassFetchMode
6.17. openjpa.jdbc.SynchronizeMappings
6.18. openjpa.jdbc.TransactionIsolation
6.19. openjpa.jdbc.UpdateManager
6.20. Compatibility with Specification

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, or to plug in your own dictionary for a database OpenJPA does not support out-of-the-box. 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.