Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: for the plan.

Jump to: navigation, search


< EclipseLink‎ | Examples‎ | JPA‎ | Migration‎ | OpenJPA
Revision as of 15:08, 3 May 2016 by (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Migration from OpenJPA to EclipseLink: Persistence XML

NOTE: Under Construction

When migrating it is important to first address the changes required in the persistence.XML file. If you encounter any migration issues in the persistence.xml file not covered here or incomplete please log a documentation enhancement request referencing this page and describe your migration challenge.


The JPA persistence provider typically needs to be set during any migration to ensure the EclipseLink JPA provider is used in case multiple providers exist in the target container.


JavaSE USage

It has been reported that in JavaSE usage of OpenJPA the provider resolver functionality may continue to use OpenJPA if it is encountered first on the classpath and ignore the specified <provider>. If this is encountered the best solution is to remove OpenJPA from the classpath of your application or test harness.

PU Properties

Persistence Unit properties are a standard mechanism for providing vendor specific configuration. They are most common used to handle the configuration of:

  • JDBC pooling
  • Cache configuration and usage

The following table captures the OpneJPA persistence unit properties and their corresponding EclipseLink JPA properties.

NOTE: This is complex mapping task requiring knowledge of both solutions. Not all properties will have a direct mapping.

Please refer to the EclipseLink UserGuide (ELUG)'s extended JPA functionality for a description of all supported properties or see the PersistenceUnitProperties JavaDocs.

JDBC Properties

These properties are used to configure internal connection pooling typically used in JavaSE or containers where data sources are not available.

Please refer to the [Using_EclipseLink_JPA_Extensions_(ELUG)#Using_EclipseLink_JPA_Extensions_for_JDBC EclipseLink User Guide on JDBC Pooling] for complete information about what is supported.

Note: As of JPA 2.0 several of the persistence unit properties for JDBC configuration have been standardized. EclipseLink deprecated its own and started using these in EclipseLink 1.2.0.

OpenJPA Property Description EclipseLink JPA Equivalent
openjpa.ConnectionDriverName EclipseLink 1.0-1.1.x: eclipselink.jdbc.driver
EclipseLink 1.2+: javax.persistence.jdbc.driver
openjpa.ConnectionPassword EclipseLink 1.0-1.1.x: eclipselink.jdbc.password
EclipseLink 1.2+: javax.persistence.jdbc.password
openjpa.ConnectionURL EclipseLink 1.0-1.1.x: eclipselink.jdbc.url
EclipseLink 1.2+: javax.persistence.jdbc.url
openjpa.ConnectionUserName EclipseLink 1.0-1.1.x: eclipselink.jdbc.user
EclipseLink 1.2+: javax.persistence.jdbc.user

Additional Notes:

  • The OpenJPA properties containing '2' are for the unmanaged connection pool. EclipseLink uses the same information for both managed and unmanaged connections. If a separate set of login info is required for the unmanaged this would need to be configured in code.
  • Connection properties and custom connectors equivalent to OpenJPA connection factories are supported through the DatabaseLogin/Platform and custom Connectors. These are not required with leading containers but can easily be configured using a SessionCustomizer.

Diagnostic Properties

OpenJPA Property Description EclipseLink JPA Equivalent openjpa.Log Possible values: openjpa, commons, log4j, none eclipselink.logging.logger with values DefaultLogger, JavaLogger, ServerLogger, or custom

Caching Properties

EclipseLink leverages an out of the box shared entity caching solution instead of a data cache solution requiring a 3rd party implementation.

OpenJPA Property Description EclipseLink JPA Equivalent
openjpa.DataCache Cache implementation Not Required
openjpa.DataCacheManager Cache implementation Not Required
openjpa.DataCacheTimeout Cache Timeout EclipseLink offers expiration/invalidation per entity cache based on time since read or time of day. These can be configured using an @Cache annotation on the entity or specified in eclipselink-orm.xml. See [| UserGuide].
openjpa.QueryCache Eclipselink support query result caching using the query hint: "eclipselink.query-results-cache"
openjpa.QueryCompilationCache Caching of compiled queries EclipseLink automatically caches generated SQL strings and prepared statements. The size of these caches is configurable.

Other Properties

OpenJPA Property Description EclipseLink JPA Equivalent
openjpa.AutoDetach Events where an entity will be detached Not Applicable: Entities can be used with other EM's as detached at any time but are always considered managed relative to the reading EM as long as it is open and the entity has not been serialized.
openjpa.BrokerFactory A BrokerFactory is equivalent to EclipseLink's ServerSession. No direct configuration in XML. Custom server session types are supported through API only.
openjpa.BrokerImpl A BrokerImpl is equivalent to EclipseLink's UnitOfWork. Not possible to customize the UnitOfWork type used within JPA through XML.
openjpa.ClassResolver Used to convert class names to classes EclipseLink offers support for specifying the "eclipselink.classloader" to be used or the conversion routines can be customized by creating a custom ConversionManager or DatabasePlatform.
openjpa.Compatibility Compatibility with previous OpenJPA releases. Not required when migrating.
openjpa.DetachState DETACH_ALL, DETACH_FETCH_GROUPS, DETACH_LOADED To detach an entity with EclipseLink the JAP 2.0 EntityManager detach method can be used or a CopyGroup can be used to detach a specified set of attributes and nested attributes. Serializing a partial entity loaded with a FetchGroup will cause it to only serialize the attributes that were fetched.
DETACH_LOADED: Serialization or copying using the same FetchGroup.
DETACH_ALL: Copy using full FetchGroup (no nesting)
openjpa.FetchBatchSize EclipseLink batching and joining depth and size is configurable on queries instead of globally.
openjpa.FetchGroups EclipseLink's default fetch group is determined by the fetchType on an entity's mappings but can be customized on individual queries using the "eclipselink.fetch-group" query hint.
openjpa.DetachState specifies attributes in detached state. EclipseLink determines detached state based on usage along with lazy loading configurations and dynamic fetch groups. Lazy relationships can always be retrieved until the entity is truly detached through serialization or copying.
openjpa.FlushBeforeQueries EclipseLink relies on the standard FlushMode as well as its support of in-memopry querying to minimize the need to flush before executing a query. For large transactions consider using "eclipselink.flush-clear.cache".
openjpa.IgnoreChanges Avoid tracking changes EclipseLink provides similar support using @ReadOnly as well as the "" query hint. This allows the shared entity cache to be leveraged.
openjpa.Id identifier for persistence unit Equivalent to "eclipselink.session-name" property which simplifies looking up the underlying shared session in the native SessionManager singleton.
openjpa.jdbc.Schema Used to set the default schema name EclipseLink provides support through an orm.xml entity mapping file. This schema name is controlled with the "entity-mappings/persistence-unit-metadata/persistence-unit-defaults/schema" value. Add the schema name to a new or existing orm.xml file, at the
openjpa.LockManager No direct configuration in XML. Use the lock API provided in the JPA specification (i.e. Query.setLockMode(LockModeType lockMode))
openjpa.LockTimeout Replace with javax.persistence.lock.timeout defined in the JPA specification.
openjpa.ManagedRuntime plugin for looking up the TransactionManager This is generally supported in EclipseLink through the "" configuration of the ServerPlatform but can be separately configured using a custom ExternalTransactionController.


Setting Default Schema

OpenJPA EclipseLink
  • persistence.xml
<persistence-unit name="Sample">
        <property name="openjpa.jdbc.Schema" value="ADMIN" />
  • persistence.xml
<persistence-unit name="Sample">
  • orm.xml

Back to the top