Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
EclipseLink/Examples/JPA/Migration/OpenJPA/PersistenceXML
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.
Contents
Provider
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.
<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
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.AutoClear | ||
| 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.DynamicDataStructs | ||
| 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 "eclipselink.read-only" 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.InverseManager | ||
| 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 "eclipselink.target-server" configuration of the ServerPlatform but can be separately configured using a custom ExternalTransactionController. |
| openjpa.Mapping | ||
| openjpa.MaxFetchDepth | ||
| openjpa.MetaDataFactory | ||
| openjpa.Multithreaded | ||
| openjpa.Optimistic | ||
| openjpa.OrphanedKeyAction | ||
| openjpa.NontransactionalRead | ||
| openjpa.NontransactionalWrite | ||
| openjpa.ProxyManager | ||
| openjpa.RemoteCommitProvider | ||
| openjpa.RestoreState | ||
| openjpa.RetainState | ||
| openjpa.RetryClassRegistration | ||
| openjpa.SavepointManager | ||
| openjpa.Sequence | ||
| openjpa.TransactionMode | ||
| openjpa.WriteLockLevel |
Examples
Setting Default Schema
| OpenJPA | EclipseLink |
|---|---|
<persistence-unit name="Sample">
<properties>
<property name="openjpa.jdbc.Schema" value="ADMIN" />
</properties>
</persistence-unit>
|
<persistence-unit name="Sample"> <mapping-file>orm.xml</mapping-file> </persistence-unit>
<persistence-unit-metadata>
<persistence-unit-defaults>
<schema>ADMIN</schema>
</persistence-unit-defaults>
</persistence-unit-metadata>
|