Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "EclipseLink/Examples/JPA/Migration/OpenJPA/PersistenceXML"

< EclipseLink‎ | Examples‎ | JPA‎ | Migration‎ | OpenJPA
(New page: == OpenJPA to EclipseLink: Persistence Unit Properties == {|{{BMTableStyle}} |-{{BMTHStyle}} ! OpenJPA Property ! Description ! EclipseLink JPA Equivalent |- | openjpa.AutoClear || || ...)
 
(Other Properties)
(7 intermediate revisions by the same user not shown)
Line 1: Line 1:
== OpenJPA to EclipseLink: Persistence Unit Properties ==
+
== 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 [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=EclipseLink&bug_severity=enhancement documentation enhancement request] referencing this page and describe your migration challenge.
 +
 
 +
__TOC__
 +
 
 +
=== 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.
 +
 
 +
<source lang="xml">
 +
<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
 +
</source>
 +
 
 +
==== 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 [[Using_EclipseLink_JPA_Extensions_%28ELUG%29 | EclipseLink UserGuide (ELUG)]]'s extended JPA functionality for a description of all supported properties or see the [http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/config/PersistenceUnitProperties.html 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 uysing these in EclipseLink 1.2.0.''
  
 
{|{{BMTableStyle}}
 
{|{{BMTableStyle}}
Line 7: Line 45:
 
! EclipseLink JPA Equivalent
 
! EclipseLink JPA Equivalent
 
|-
 
|-
| openjpa.AutoClear ||  ||  
+
| openjpa.ConnectionDriverName ||  || EclipseLink 1.0-1.1.x: eclipselink.jdbc.driver <br> EclipseLink 1.2+: javax.persistence.jdbc.driver
 
|-
 
|-
| openjpa.AutoDetach ||  ||
+
| openjpa.ConnectionPassword ||  || EclipseLink 1.0-1.1.x: eclipselink.jdbc.password <br> EclipseLink 1.2+: javax.persistence.jdbc.password
 
|-
 
|-
| openjpa.BrokerFactory ||  ||
+
| openjpa.ConnectionURL ||  || EclipseLink 1.0-1.1.x: eclipselink.jdbc.url <br> EclipseLink 1.2+: javax.persistence.jdbc.url
 
|-
 
|-
| openjpa.BrokerImpl ||  ||
+
| openjpa.ConnectionUserName ||  || EclipseLink 1.0-1.1.x: eclipselink.jdbc.user <br> 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 ====
 +
 
 +
{|{{BMTableStyle}}
 +
|-{{BMTHStyle}}
 +
! OpenJPA Property
 +
! Description
 +
! EclipseLink JPA Equivalent
 +
| openjpa.Log || Possible values: openjpa, commons, log4j, none  || [[Using_EclipseLink_JPA_Extensions_(ELUG)#Using_EclipseLink_JPA_Extensions_for_Logging | 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.
 +
 
 +
{|{{BMTableStyle}}
 +
|-{{BMTHStyle}}
 +
! OpenJPA Property
 +
! Description
 +
! EclipseLink JPA Equivalent
 
|-
 
|-
| openjpa.ClassResolver || ||
+
| openjpa.DataCache || Cache implementation || Not Required
 
|-
 
|-
| openjpa.Compatibility || ||
+
| openjpa.DataCacheManager || Cache implementation || Not Required
 
|-
 
|-
| openjpa.ConnectionDriverName || || eclipselink.jdbc.driver
+
| 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 [[http://wiki.eclipse.org/Using_EclipseLink_JPA_Extensions_%28ELUG%29#How_to_Use_the_.40Cache_Annotation | UserGuide]].
 
|-
 
|-
| openjpa.ConnectionFactory ||  ||
+
| openjpa.QueryCache ||  || Eclipselink support query result caching using the query hint: [http://www.eclipse.org/eclipselink/api/latest/org/eclipse/persistence/config/QueryHints.html#QUERY_RESULTS_CACHE "eclipselink.query-results-cache"]
 
|-
 
|-
| openjpa.ConnectionFactoryName || ||
+
| openjpa.QueryCompilationCache || Caching of compiled queries || EclipseLink automatically caches generated SQL strings and prepared statements. The size of these caches is configurable.
 +
|}
 +
 
 +
==== Other Properties ====
 +
 
 +
{|{{BMTableStyle}}
 +
|-{{BMTHStyle}}
 +
! OpenJPA Property
 +
! Description
 +
! EclipseLink JPA Equivalent
 
|-
 
|-
| openjpa.ConnectionFactoryMode ||  ||
+
| openjpa.AutoClear ||  ||  
 
|-
 
|-
| openjpa.ConnectionFactoryProperties || ||
+
| 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.ConnectionPassword || || eclipselink.jdbc.password
+
| 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.ConnectionProperties || ||
+
| openjpa.BrokerImpl || A BrokerImpl is equivalent to EclipseLink's UnitOfWork. || Not possible to customize the UnitOfWork type used within JPA through XML.
 
|-
 
|-
| openjpa.ConnectionURL || || eclipselink.jdbc.url
+
| openjpa.ClassResolver || Used to convert class names to classes || EclipseLink offers support for specifying the [http://www.eclipse.org/eclipselink/api/1.2/org/eclipse/persistence/config/PersistenceUnitProperties.html#CLASSLOADER "eclipselink.classloader"] to be used or the conversion routines can be customized by creating a custom ConversionManager or DatabasePlatform.
 
|-
 
|-
| openjpa.ConnectionUserName || || eclipselink.jdbc.user
+
| openjpa.Compatibility || Compatibility with previous OpenJPA releases. || Not required when migrating.
 
|-
 
|-
| openjpa.Connection2DriverName ||  ||
+
| 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. <br/>'''DETACH_LOADED''': Serialization or copying using the same FetchGroup.<br/> '''DETACH_ALL''': Copy using full FetchGroup (no nesting)
 
|-
 
|-
| openjpa.Connection2Properties ||  ||
+
| openjpa.DynamicDataStructs ||  ||
|-
+
| openjpa.ConnectionFactory2Name ||  ||
+
 
|-
 
|-
| openjpa.ConnectionFactory2 ||  ||
+
| openjpa.FetchBatchSize ||  || EclipseLink batching and joining depth and size is configurable on queries instead of globally.
 
|-
 
|-
| openjpa.ConnectionFactory2Properties ||  ||
+
| 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.Connection2Password || ||
+
| 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.Connection2UserName || ||
+
|-
+
| openjpa.Connection2URL ||  ||
+
 
|-  
 
|-  
| openjpa.ConnectionRetainMode ||  ||
+
| 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.DataCache || ||
+
| 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.DataCacheManager || ||
+
| 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.DataCacheTimeout ||  ||
+
|-
+
| openjpa.DetachState ||  ||
+
|-
+
| openjpa.DynamicDataStructs ||  ||
+
|-
+
| openjpa.FetchBatchSize ||  ||
+
|-
+
| openjpa.FetchGroups ||  ||
+
|-
+
| openjpa.FlushBeforeQueries ||  ||
+
|-
+
| openjpa.IgnoreChanges ||  ||
+
|-
+
| openjpa.Id ||  ||
+
 
|-
 
|-
 
| openjpa.InverseManager ||  ||
 
| openjpa.InverseManager ||  ||
Line 81: Line 132:
 
| openjpa.LockTimeout ||  ||
 
| openjpa.LockTimeout ||  ||
 
|-
 
|-
| openjpa.Log || Possible values: openjpa, commons, log4j, none  || [[Using_EclipseLink_JPA_Extensions_(ELUG)#Using_EclipseLink_JPA_Extensions_for_Logging | eclipselink.logging.logger]] with values DefaultLogger, JavaLogger, ServerLogger, or custom
+
| 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.ManagedRuntime ||  ||
+
 
|-
 
|-
 
| openjpa.Mapping ||  ||
 
| openjpa.Mapping ||  ||
Line 102: Line 151:
 
|-
 
|-
 
| openjpa.ProxyManager ||  ||
 
| openjpa.ProxyManager ||  ||
|-
 
| openjpa.QueryCache ||  ||
 
|-
 
| openjpa.QueryCompilationCache ||  ||
 
|-
 
| openjpa.ReadLockLevel ||  ||
 
 
|-
 
|-
 
| openjpa.RemoteCommitProvider ||  ||
 
| openjpa.RemoteCommitProvider ||  ||

Revision as of 13:30, 29 June 2010

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.

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 uysing 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.LockManager
openjpa.LockTimeout
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

Back to the top