Beta Draft: 2012-12-13

Implementing the Solution

This section contains the following tasks:

Task 1: Prerequsites
Task 2: Change the Provider and Persistence Unit Properties in persistence.xml
Task 3: Convert Query Hint Names Used in Named and Dynamic Queries
Task 4: Convert or Fix Nonstandard Mappings Available in OpenJPA
Task 5: Convert from OpenJPA Extended Features
Task 6: Take Advantage of EclipseLink Features

Task 1: Prerequsites

EclipseLink 2.4 or later.

Download EclipseLink from http://www.eclipse.org/eclipselink/downloads/.

Task 2: Change the Provider and Persistence Unit Properties in persistence.xml

Update the following properties in the persistence.xml file, as needed:

Provider

Set the JPA persistence provider to org.eclipse.persistence.jpa.PersistenceProvider, to ensure that EclipseLink JPA is used as the provider, in case multiple providers exist in the target container.

<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>

Note:

When using OpenJPA with Java SE, the provider resolver may continue to use OpenJPA, instead of the specified provider, if OpenJPA is encountered first on the classpath. If this happens, remove OpenJPA from the classpath of your application.

Persistence Unit Properties

Persistence unit properties are a standard mechanism for providing vendor-specific configuration. The following sections list OpenJPA persistence unit properties that must be replaced when migrating from OpenJPA to EclipseLink:

JDBC Properties
Caching Properties
Diagnostic Properties
Other Properties

Not all OpenJPA persistence unit properties have exact equivalents in EclipseLink, so you may have to consult the OpenJPA documenation and the EclipseLink documentation to determine a conversion strategy. For complete reference documentation on the EclipseLink extensions to standard JPA persistence properties, see "Persistence Property Extensions Reference" in Java Persistence API (JPA) Extensions Reference for EclipseLink. For complete EclipseLink Javadoc, see Java API Reference for EclipseLink.

JDBC Properties

JDBC properties are used to configure internal connection pooling typically used in Java SE or in containers where data sources are not available. Table 7-1, "JDBC Persistence Unit Properties" compares OpenJPA JDBC properties to the corresponding or related EclipseLink properties.

For information about the EclipseLink JDBC persistence properties, see "JDBC Configuration Options" in Java Persistence API (JPA) Extensions Reference for EclipseLink.

Note:

In JPA 2.0 several persistence unit properties for JDBC configuration were standardized. Therefore, beginning in EclipseLink 11.1.1.2, the equivalent EclipseLink properties were deprecated and replaced by the JPA 2.x standard ones. Both are shown in the EclipseLink JPA Equivalent column of Table 7-1.

Table 7-1 JDBC Persistence Unit Properties

OpenJPA Property	Description	EclipseLink JPA Equivalent
`openjpa.ConnectionDriverName`	The full class name of either the JDBC `java.sql.Driver` or a `javax.sql.DataSource` implementation to use to connect to the database.	EclipseLink 11.1.1.0 - 11.1.1.1: `eclipselink.jdbc.driver` EclipseLink 11.1.1.2 +: `javax.persistence.jdbc.driver`
`openjpa.ConnectionPassword`	The password for the user, specified in the `ConnectionUserName` property.	EclipseLink 11.1.1.0 - 11.1.1.1: `eclipselink.jdbc.password` EclipseLink 11.1.1.2 +: `javax.persistence.jdbc.password`
`openjpa.ConnectionURL`	The JDBC URL for the database.	EclipseLink 11.1.1.0 - 11.1.1.1: `eclipselink.jdbc.url` EclipseLink 11.1.1.2 +: `javax.persistence.jdbc.url`
`openjpa.ConnectionUserName`	The user name to use when connecting to the database.	EclipseLink 11.1.1.0 - 11.1.1.1: `eclipselink.jdbc.user` EclipseLink 11.1.1.2 +: `javax.persistence.jdbc.user`

Other JDBC issues to consider include:

The OpenJPA properties containing "2," for example openjpa.Connection2DriverName, are for the unmanaged connection pool. EclipseLink uses the same information for both managed and unmanaged connections. If separate login information is required for unmanaged connections, it must be configured in code.
Connection properties and custom connectors equivalent to OpenJPA connection factories are supported through DatabaseLogin, DatabasePlatform, and custom Connectors. These are generally not required with containers but can be configured using a SessionCustomizer, if needed.

Caching Properties

EclipseLink uses its own shared entity caching feature instead of a data cache requiring a 3rd party implementation. Table 7-2, "Caching Persistence Unit Properties" compares OpenJPA caching properties to the corresponding or related EclipseLink properties.

Table 7-2 Caching Persistence Unit Properties

OpenJPA Property	Description	EclipseLink JPA Equivalent
`openjpa.DataCache`	The data cache implementation to use for data caching.	Not Required
`openjpa.DataCacheManager`	The data cache manager to use for managing the system data caches.	Not Required
`openjpa.DataCacheTimeout`	The duration that data in the data cache is valid.	EclipseLink provides expiration and invalidation per entity cache, based on the time since it was read or on the time of day. Configure these by using a `@Cache` annotation on the entity. Alternatively, specify it in `eclipselink-orm.xml`.
`openjpa.QueryCache`	The query cache implementation to use for caching of queries loaded from the data store.	EclipseLink supports query result caching through the query hint `eclipselink.query-results-cache`.
`openjpa.QueryCompilationCache`	The map to use for caching data of compiled queries	EclipseLink automatically caches generated SQL strings and prepared statements. The size of these caches is configurable.

Diagnostic Properties

Table 7-3, "Diagnostic Properties" compares the OpenJPA logging property to the corresponding EclipseLink property.

Table 7-3 Diagnostic Properties

OpenJPA Property	Description	EclipseLink JPA Equivalent
`openjpa.Log`	The log factory to use for logging.	Use `eclipselink.logging.logger`.

Other Properties

Table 7-4, "Other Properties" compares miscellaneous other OpenJPA properties to the corresponding or related EclipseLink properties.

Table 7-4 Other Properties

OpenJPA Property	Description	EclipseLink JPA Equivalent
`openjpa.AutoClear`	When to clear instance state: on entering a datastore transaction or on entering any transaction.
`openjpa.AutoDetach`	Events that cause managed instances to be detached.	Not applicable. Entities can be used with other entity mangers as detached at any time. However, they are always considered managed relative to the reading entity manger, as long as it is open and the entity has not been serialized.
`openjpa.BrokerFactory`	The broker factory to use.	The EclipseLink `ServerSession` is equivalent to the OpenJPA `BrokerFactory`. Direct configuration in XML is not supported. Custom server session types are supported through API only.
`openjpa.BrokerImpl`	The broker type to use at runtime.	The EclipseLink `UnitOfWork` is equivalent to the OpenJPA `BrokerImpl`. The `UnitOfWork` type cannot be customized in JPA through XML
`openjpa.ClassResolver`	The class resolver to use to resolve class names.	Specify the EclipseLink `eclipselink.classloader` to be used. Alternatively, create a custom `ConversionManager` or `DatabasePlatform` to customize conversion routines.
`openjpa.Compatibility`	Options to ensure compatibility with previous OpenJPA releases.	Not required when migrating.
`openjpa.DetachState`	Determines which fields are part of the detached graph and related options.	Use the JPA 2.0 `EntityManager`.`detach()` method o detach an entity. Alternatively, use a `CopyGroup` to detach a specified set of attributes and nested attributes. Serializing a partial entity loaded with a `FetchGroup` causes it to serialize the attributes that were fetched only.
`openjpa.DynamicDataStructs`	Whether to dynamically generate customized structs to hold persistent data.
`openjpa.FetchBatchSize`	The number of rows to fetch at a time when scrolling through a result set.	EclipseLink batching and joining depth and size is configurable on queries instead of globally.
`openjpa.FetchGroups`	Fetch groups to be loaded when retrieving objects from the datastore.	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`	Determines which fields are part of the detached graph and related options.	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`	Whether to flush changes made in the current transaction to the datastore before executing a query.	EclipseLink relies on the standard `FlushMode` as well as its support of in-memory 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. These take advantage of the shared cache.
`openjpa.Id`	Identifier for current configuration, for example, persistence unit name.	Equivalent to `eclipselink.session-name` property which simplifies looking up the underlying shared session in the native `SessionManager` singleton.
`openjpa.InverseManager`	Whether to consider changes to persistent objects made in the current transaction when evaluating queries.
`openjpa.LockManager`	The lock manager to use to use for acquiring locks on persistent instances during transactions.
`openjpa.LockTimeout`	Time to wait for an object lock before throwing an exception
`openjpa.ManagedRuntime`	The managed runtime implementation to use to obtain a reference to the transaction manager in an enterprise environment.	This is generally supported in EclipseLink through the `eclipselink.target-server` configuration of the `ServerPlatform`, but you can configure it separately using a custom `ExternalTransactionController`.
`openjpa.Mapping`	Name of the object-to-datastore mapping to use.
`openjpa.MaxFetchDepth`	The maximum depth of relations to traverse when eager fetching.
`openjpa.MetaDataFactory`	The metadata factory to use to store and retrieve metadata for persistent classes.
`openjpa.Multithreaded`	Whether persistent instances and components other than the entity manager factory are accessed by multiple threads simultaneously.
`openjpa.Optimistic`	Selects between optimistic and pessimistic (datastore) transactional modes.
`openjpa.OrphanedKeyAction`	The orphaned key action to invoke when OpenJPA discovers an orphaned datastore key.
`openjpa.NontransactionalRead`	Whether the runtime allows data to be read outside of a transaction.
`openjpa.NontransactionalWrite`	Whether persistent objects can be modified and whether persistence operations can be performed outside a transaction.
`openjpa.ProxyManager`	The proxy manager to use for proxying mutable second class objects.
`openjpa.RemoteCommitProvider`	The remote commit provider implementation to use for distributed event notification.
`openjpa.RestoreState`	Whether to restore managed fields to their pretransaction values when rolled back.
`openjpa.RetryClassRegistration`	Whether to defer registration instead of throwing an exception when a persistent class cannot be processed
`openjpa.SavepointManager`	The savepoint manager to use for managing transaction savepoints.
`openjpa.Sequence`	The kernel sequence implementation to use for the system sequence.
`openjpa.TransactionMode`	The default transaction mode to use.
`openjpa.WriteLockLevel`	The default level to use to lock objects changed during a non-optimistic transaction.

Task 3: Convert Query Hint Names Used in Named and Dynamic Queries

JPA applications can include query hints, which define provider-specific behavior. These hints can be specified in annotations, ORM XML files, or application code. The query hint names are strings and therefore do not typically force compile time dependencies on the provider. However, the values for these hints may introduce dependencies.

Table 7-5, "Query Hints" compares OpenJPA query hint to the corresponding or related EclipseLink features.

Table 7-5 Query Hints

OpenJPA Property	Description	EclipseLink JPA Equivalent
`openjpa.hint.OracleSelectHint`	Specifies an Oracle-specific query hint to be generated.	Use `eclipselink.sql.hint` to include a hint in the SQL for a query.
`openjpa.FetchPlan.ReadLockMode`	Values= `READ` or `WRITE`	Use JPA 2.0 `Query.setLockMode(LockModeType)` to set the lock mode.
`openjpa.hint.OptimizeResultCount`	Sets the size for a query result set.	Use `QueryHints.JDBC_FETCH_SIZE` to configure the JDBC fetch size for the queries result set.
`openjpa.FetchPlan.Isolation`	Specifies the isolation level using the `SQL WITH <isolation>` clause for those databases that support it.
`openjpa.FetchPlan.MaxFetchDepth`	The maximum depth of relations to traverse when eager fetching.	Specify `FetchGroup` depth using attributes, not numeric depth.
`openjpa.FetchPlan.FetchBatchSize`	The number of rows to fetch at once when scrolling through a result set.	Use `Query.setMaxResultsQueryHints.JDBC_MAX_ROWS`.
`openjpa.FetchPlan.LockTimeOut`	Time to wait to acquire a lock.	Use `QueryHints.PESSIMISTIC_LOCK_TIMEOUT`.
`openjpa.FetchPlan.EagerFetchMode`	Determines how to eager-fetch a field.	EclipseLink fetch group loading is done based on the attributes specified for the fetch group. In the case of the default `FetchGroup`, loading is based on the lazy configuration of the mappings.
`openjpa.FetchPlan.SubclassFetchMode`	Determines how to eager-fetch subclass data.	Fetch group attributes can be assigned to any mapped attribute in the target entity or its mapped parent classes.

Task 4: Convert or Fix Nonstandard Mappings Available in OpenJPA

Note:

Using a JPA mapping tool such as Oracle JDeveloper or Oracle Enterprise Pack for Eclipse (OEPE) makes mapping entities easier and less error-prone. Such tools provide validation and configuration assistance to address many common mapping errors.

The following are some mapping scenarios you might encounter when migrating from OpenJPA to EclipseLink.

@Column in Relationship Mappings

When defining relationship mappings involving foreign keys (@OneToOne and @ManyToOne), JPA supports the specification of non-default column names using @JoinColumn and @JoinColumns. OpenJPA allows the specification of @Column. Since this has no defined meaning in JPA, EclipseLink throws a validation exception to assist customers in identifying this incorrect mapping configuration.

Solution

Convert all @OneToOne and @ManyToOne mappings that have an @Column configuration to use @JoinColumn. If the target class of the relationship has a composite identifier (primary key) you must use @JoinColumns.

If the relationship defined by the @JoinColumn(s) involves columns which are also mapped as identifiers (primary key columns), make sure they are mapped with @Id and that the duplicate mappings are properly mapped and managed in the entity class.

@Transient with Relationship Mappings

The JPA specification does not define whether mappings (@Basic, @OneToOne, @ManyToOne, @OneToMany, @ManyToMany, etc.) can be specified to be transient. While OpenJPA allows this, EclipseLink correctly throws an exception. Transient configuration on an attribute is intended to prevent default mappings from being applied when calculating the mappings for an entity. With default mappings, unmapped attributes are assumed to be mapped according to the specification. @Transient prevents these assumptions, which may not be the desired behavior.

Solution

Determine which configuration you want. If you want mapping, remove @Transient. If the intention was to avoid the default mapping, then either remove or comment out the mapping configuration.

Task 5: Convert from OpenJPA Extended Features

OpenJPA offers some extended functionality that goes beyond the JPA specification. The following sections describe these features and how you can migrate to the corresponding functionality in EclipseLink.

BigCollection

FetchPlan/Group

Inheritance Casting

Native SQL with POJO results

Detached (Serialized) entities & relationships

Task 6: Take Advantage of EclipseLink Features

After completing the conversion to EclipseLink JPA it is also very important to harness the additional features available. The most commonly used features include:

Caching - Make sure you understand and optimize your cache configuration to work with your locking policies and the volatility of your underlying database tables:
- Shared (L2) versus Isolated (EntityManager/TX)
- Shared type, size, and expiration/invalidation
- Cache coordination (where applicable)
Query Optimization - Minimize the amount of data loaded and cached for greater performance and optimal cache usage:
- Batch and Joined (multi-level) for graph retrieval
- Cache usage and refreshing
- Data projections for data loading on searches where full entities are not required
- Paged data/entity loading
- Fetch Groups
Weaving - Ensure weaving is enabled for change tracking, lazy loading, and fetch groups capabilities .