This document discusses migrating from OpenJPA to EclipseLink as the JPA provider. It provides an overview of key differences between OpenJPA and EclipseLink, differences in supported JPA versions and features. It also describes an investigation of migrating existing entities from OpenJPA to EclipseLink that uncovered issues like private accessors, missing constructors, collection mappings and JPQL differences. The document recommends continuing to use OpenJPA for existing applications and migrating to EclipseLink only for new applications due to potential changes needed in existing entities.

1. © 2015 IBM Corporation
AAI-2235
OpenJPA and EclipseLink
Usage Scenarios Explained
Kevin Sutter, STSM
WebSphere Java EE and JPA
Architect

2. Agenda
• OpenJPA and EclipseLink
• JPA version comparisons
• OpenJPA to EclipseLink Migration
• High level concepts
• OpenJPA to EclipseLink Investigation
• Specific differences
• Summary
• Q & A
2

3. OpenJPA and
EclipseLink

4. OpenJPA and EclipseLink
• Apache OpenJPA
• Basis for WebSphere’s JPA solution for JPA 1.0 and JPA
2.0
• EclipseLink
• JPA Reference Implementation – “gospel”
• Basis for WebSphere Liberty’s JPA solution for JPA 2.1
(Beta)
• Moving forward…
• OpenJPA will continue to be supported in WAS for many,
many years
• At least until JPA 2.0 is deprecated…
• Both WebSphere Full Profile and Liberty Profile
4

5. Multiple JPA Providers
• Do I need to switch providers?
• Absolutely not!
• If you are happy with the current OpenJPA offering,
there is no need to move to EclipseLink
• If you want to use the JPA 2.1 API or features, you *may*
need to change…
• Many of the JPA 2.1 features have corresponding
OpenJPA proprietary solutions
• Apache OpenJPA (ie. JPA 2.0) will “play nice” with other Java
EE 7 features
• Allows for an easier, more gradual JPA migration
5

6. Key JPA 2.1 Features available in OpenJPA
• Schema Generation (JPA 2.1 Spec, Section 9.4)
• Generates DDL or interacts directly with database to
define table schemas based on JPA Entity definitions
• Similar functionality provided by OpenJPA’s schema
mapper
• Entity Graphs (JPA 2.1 Spec, Section 3.7)
• Allows for specified fetching or processing of a graph of
Entity objects
• Similar functionality provided by OpenJPA’s FetchPlan
and FetchGroup
• Stored Procedure Queries (JPA 2.1 Spec, Section 3.10.17)
• Ability to invoke database stored procedures
• Similar functionality provided by OpenJPA’s Query
invocation
6

7. Additional JPA 2.1 Features available in OpenJPA
• Basic Attribute Type Conversion (JPA 2.1 Spec, Section 3.8)
• Similar functionality support provided by OpenJPA’s
Externalizer feature
• @Index and @ForeignKey annotations (JPA 2.1 Spec, Sections 11.1.19 and
11.1.23)
• Similar functionality provided by OpenJPA’s annotations
• Unwrap utility methods for EntityManager, Cache, etc (JPA 2.1 Spec
Sections 3.1.1 and 7.10)
• Similar functionality provided by OpenJPA’s
implementation -- EntityManagerImpl.unwrap() and
OpenJPAPersistence.cast()
• Object construction when mapping results from native SQL (JPA
2.1 Spec, Section 3.10.16.2.2)
• Similar functionality provided by OpenJPA’s internal
ResultShape object
7

8. Additional JPA 2.1 Features NOT available in OpenJPA
• Criteria API Updates (JPA 2.1 Spec, Sections 6.5.15 and 6.5.7)
• Bulk update/delete
• Support for TREAT, ON, and FUNCTION operators
• Unsynchronized Persistence Contexts (JPA 2.1 Spec, Section 7.6.1)
• Provides more control over when Persistence Contexts
are synchronized with a transaction. Useful for mobile
applications.
• EntityListeners and CDI (JPA 2.1 Spec, Section 3.5.1)
• EntityListeners can now use CDI for injection of objects
• JPQL Updates for JPA 2.1 (JPA 2.1 Spec, Chapter 4)
• Several extensions to JPQL in support of the other
features
• OpenJPA’s JPQL will stay at the JPA 2.0 level
8

9. Feature Comparison Chart
9
Key JPA 2.1 Features Available in current OpenJPA solution?
Schema Generation Yes, SynchronizeMappings
Entity Graphs Yes, FetchPlans and FetchGroups
Stored Procedures Yes, Query interface
Basic Attribute Type Conversion Yes, Externalizer (and Factory)
@Index and @ForeignKey annotations Yes, proprietary @Index and @ForeignKey
annotations
Unwrap utility functions Yes, EntityManagerImpl.unwrap() and
OpenJPAPersistence.cast()
Object construction when mapping results with
native SQL
Yes, ResultShape (internal OpenJPA
implementation)
Criteria API updates No
Unsynchronized PersistenceContexts No
EntityListeners and CDI No
JPQL Updates in support of JPA 2.1 No

10. Bottom Line
• YOU DO NOT NEED TO MIGRATE
• Our Advice
• Continue using OpenJPA for your existing applications
• Use EclipseLink for your new applications
• But… If you want to use EclipseLink with existing applications,
the following slides will discuss what to look out for when
migrating existing applications
10

11. OpenJPA to
EclipseLink
Migration

12. Cache
• DataCache
• OpenJPA's L2 cache is disabled out of the box.
EclipseLink's L2 cache is enabled by default.
• If you are migrating an application that isn't using the
OpenJPA cache, it is highly recommended to disable the
EclipseLink cache using:
<shared-cache-mode>NONE</shared-cache-mode>
• Query (Results) Cache
• If QueryCache is enabled for OpenJPA, it will cache all
Named Queries and JPQL Statement Results
• EclipseLink only caches Named Queries Results
• More information on EclipseLink QueryCache here
12

13. Weaving/enhancement/transformation
• OpenJPA: Entities must be enhanced
• EclipseLink: Entities do not have to be enhanced
• Documented missing features (lazy loading, performance
gains, etc)
• WebSphere container hooks automatically weave/enhance
Entities for both OpenJPA and EclipseLink
• Applications packaged with entities pre-enhanced by OpenJPA
must be recompiled/repackaged
• Removes OpenJPA specific enhancement bytecode
13

14. OpenJPA to
EclipseLink
Investigation

15. Investigation
• Goal
• Find differences in behavior between OpenJPA and
EclipseLink
• OpenJPA → EclipseLink migration issues
• Data
• Entities from OpenJPA's testing framework (>700 entities)
• Process
• Auto generate databases tables using both providers
• Use tables created by OpenJPA for verification
• Database: DB2
• Results
• Errors (fix EclipseLink)
• Table differences
15

16. Private Accessor Methods
• JPA 2.1 Spec: property accessor methods must be public or
protected
• OpenJPA: ignores “private” fields
• EclipseLink: persists “private” fields
• Migrating issue: missing database column error
• Solution: Add @Transient to the method
– Forces EclipseLink to ignore the field
16
Add @Transient

17. Getter/Setter accessor methods
• Annotated getter method with no corresponding setter
• OpenJPA: silently ignores the field
• EclipseLink: throws an error during entity validation
• Solution: remove annotation
17
Missing setVersion method

18. No-arg Constructor
• JPA 2.1 Spec: an entity must have a no-arg constructor
• OpenJPA: if missing, generates a no-arg constructor.
• EclipseLink: throws an error only if the no-arg constructor
is missing, but other constructors exist.
• Solution: Add an empty no-arg constructor
18
Add no-arg
constructor

19. Unannotated Collections
• Unannotated fields of type java.util.Collection or any of it’s
subinterfaces (List<E>, Queue<E>, Set<E>, etc)
• OpenJPA: ignores fields
• EclipseLink: persists fields
• Solution: Add @javax.persistence.Transient
19
Add @Transient

20. @javax.persistence.ElementCollection
• @ElementCollection generates a Separate table
• Two columns: id, value
• Different value column name
• OpenJPA: 'element'
– CREATE TABLE EntityA_LISTOFSTRINGS (ENTITYA_ID
INTEGER, element VARCHAR(254))
• EclipseLink: field name
– CREATE TABLE EntityA_LISTOFSTRINGS (EntityA_ID
INTEGER, LISTOFSTRINGS VARCHAR(255))
• Solution
20
Add @Column

21. Behavior Mismatch: @GeneratedValue
• Generate values for primary keys
• Strategies: TABLE, SEQUENCE, IDENTITY, AUTO
• No Strategy or 'AUTO': JPA provider picks the strategy
– Good news: OpenJPA and EclipseLink default to
'TABLE' strategy
– Bad news: different table schemas are created
• Solution
• Change entity to explicitly use 'TABLE' strategy
• Map to existing OpenJPA table
21

22. Java Persistence Query Language (JPQL)
• @NamedQuery: specify named query in JPQL
• OpenJPA: ignores invalid unused JPQL statements
• EclipseLink: validates all JPQL statement by default
• Solutions
• Solution 1: fix JPQL statements
• Solution 2: set eclipselink's invalid JPQL tolerance
property to true
22

23. Unique Names
• Tables, NamedQuery, SQLResultSetMapping must have unique
names
• OpenJPA behavior is undefined
– Example: tables with same name are combined
• EclipseLink throws an error during entity validation
• Solution: review entities (manual process)
23

24. Summary

25. Summary
• Do I want to utilize my existing database tables?
• Modifications to the entities may be necessary
• Database tables previously created (by OpenJPA) may
not match EclipseLink’s generated tables
• OpenJPA may have been more lenient with spec
violations than Eclipselink is
• Recommendation
• Continue using OpenJPA for existing applications
• Migrate to EclipseLink only for new applications
25

26. Resources

27. Tools: Integrity Checker
• EclipseLink provides a way to verify descriptor's metadata against
database metadata
• Setup the integrity checker using a session customizer (link)
• Catches missing tables or columns without having to persist
• Example: private getter methods
• setShouldCatchExceptions(true) - find all entities with missing
columns
• Cons: doesn't catch everything or maybe anything…
• Failed to catch @ElementColumn resulting in a different column
name in the separate table, @GeneratedValue looking for a
different table
• Doesn't compare column types
• Better than nothing, but it missed many common issues
27

28. Tools: Migration toolkit
• Migration toolkit
• Detect scenarios that result in different behavior between
providers
• Alert users when migrating from OpenJPA to EclipseLink
28

29. Useful Links
• EclipseLink JPA provider for Liberty profile article
https://developer.ibm.com/wasdev/blog/2014/05/28/eclipseli
nk-jpa-provider-liberty-profile/
• EclipseLink Migration Wiki Page
https://wiki.eclipse.org/EclipseLink/Examples/JPA/Migration/
OpenJPA
29

30. Sampling of Related Sessions…
• AAI-1713A: Introduction to Java EE 7
• Monday, 2-3pm, Mandalay Bay, Reef Ballroom E
• AAI-1641A: Introduction to Web Sockets
• Monday, 5-6pm, Mandalay Bay, Reef Ballroom E
• AAI-1313A: Agile Development Using Java EE 7 with WebSphere Liberty Profile (LAB)
• Tuesday, 8-10am, Mandalay Bay, South Seas Ballroom D
• AAI-2236A: Using the New Java Concurrency Utilities with IBM WebSphere
• Tuesday, 2-3pm, Mandalay Bay, Reef Ballroom D
• AAI-2235A: OpenJPA and EclipseLink Usage Scenarios Explained
• Wednesday, 5:30-6:30pm, Mandalay Bay, Surf Ballroom A
• AAI-1610A: Configuring IBM WebSphere Application Server for Enterprise Messaging
Needs
• Wednesday, 5:30-6:30pm, Mandalay Bay, Surf Ballroom E
• AAI-3085A: Don’t Wait! Develop Responsive Applications with Java EE7 Instead
• Thursday, 10:30-11:30am, Mandalay Bay, Lagoon L
30

31. Notices and Disclaimers
Copyright © 2015 by International Business Machines Corporation (IBM). No part of this document may be reproduced or
transmitted in any form without written permission from IBM.
U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with
IBM.
Information in these presentations (including information relating to products that have not yet been announced by IBM) has been
reviewed for accuracy as of the date of initial publication and could include unintentional technical or typographical errors. IBM
shall have no responsibility to update this information. THIS DOCUMENT IS DISTRIBUTED "AS IS" WITHOUT ANY WARRANTY,
EITHER EXPRESS OR IMPLIED. IN NO EVENT SHALL IBM BE LIABLE FOR ANY DAMAGE ARISING FROM THE USE OF
THIS INFORMATION, INCLUDING BUT NOT LIMITED TO, LOSS OF DATA, BUSINESS INTERRUPTION, LOSS OF PROFIT
OR LOSS OF OPPORTUNITY. IBM products and services are warranted according to the terms and conditions of the
agreements under which they are provided.
Any statements regarding IBM's future direction, intent or product plans are subject to change or withdrawal without
notice.
Performance data contained herein was generally obtained in a controlled, isolated environments. Customer examples are
presented as illustrations of how those customers have used IBM products and the results they may have achieved. Actual
performance, cost, savings or other results in other operating environments may vary.
References in this document to IBM products, programs, or services does not imply that IBM intends to make such products,
programs or services available in all countries in which IBM operates or does business.
Workshops, sessions and associated materials may have been prepared by independent session speakers, and do not
necessarily reflect the views of IBM. All materials and discussions are provided for informational purposes only, and are neither
intended to, nor shall constitute legal or other guidance or advice to any individual participant or their specific situation.
It is the customer’s responsibility to insure its own compliance with legal requirements and to obtain advice of competent legal
counsel as to the identification and interpretation of any relevant laws and regulatory requirements that may affect the customer’s
business and any actions the customer may need to take to comply with such laws. IBM does not provide legal advice or
represent or warrant that its services or products will ensure that the customer is in compliance with any law.

32. Notices and Disclaimers (con’t)
Information concerning non-IBM products was obtained from the suppliers of those products, their published
announcements or other publicly available sources. IBM has not tested those products in connection with this
publication and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM
products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.
IBM does not warrant the quality of any third-party products, or the ability of any such third-party products to
interoperate with IBM’s products. IBM EXPRESSLY DISCLAIMS ALL WARRANTIES, EXPRESSED OR IMPLIED,
INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE.
The provision of the information contained herein is not intended to, and does not, grant any right or license under any
IBM patents, copyrights, trademarks or other intellectual property right.
•IBM, the IBM logo, ibm.com, Bluemix, Blueworks Live, CICS, Clearcase, DOORS®, Enterprise Document
Management System™, Global Business Services ®, Global Technology Services ®, Information on Demand, ILOG,
Maximo®, MQIntegrator®, MQSeries®, Netcool®, OMEGAMON, OpenPower, PureAnalytics™, PureApplication®,
pureCluster™, PureCoverage®, PureData®, PureExperience®, PureFlex®, pureQuery®, pureScale®, PureSystems®,
QRadar®, Rational®, Rhapsody®, SoDA, SPSS, StoredIQ, Tivoli®, Trusteer®, urban{code}®, Watson, WebSphere®,
Worklight®, X-Force® and System z® Z/OS, are trademarks of International Business Machines Corporation,
registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other
companies. A current list of IBM trademarks is available on the Web at "Copyright and trademark information" at:
www.ibm.com/legal/copytrade.shtml.

33. Thank You
Your Feedback is
Important!
Access the InterConnect 2015
Conference CONNECT Attendee
Portal to complete your session
surveys from your smartphone,
laptop or conference kiosk.

34. Backup

35. Differences in Column Types
• Mapping fields to columns
• Example: java.lang.String fields
– OpenJPA: VARCHAR(254)
– EclipseLink: VARCHAR(255)
• Mostly non-problematic
• Exception: java.util.Locale fields
– OpenJPA: VARCHAR(254)
– EclipseLink: BLOB(64000)
– Solution
– Use a type converter (introduced in JPA 2.1)
– BLOB (object) ↔ VARCHAR (database)
35