EclipseLink/Development/JPA 2.0/glassfish

Running JPA 2.0 API on Glassfish V3 (JEE6 RI) and V2 (JEE5 RI)

Test Conditions

• - verify JPA 2.0 interface call with implementation shipped in EclipseLink 1.2 = entityManager.getMetamodel()
• - verify JPA 2.0 interface call with implementation only in EclipseLink 2.0 = entityManager.getCriteriaBuilder()
• - verify use of JPA 2.0 XSD and properties like <shared-cache-mode>NONE</shared-cache-mode> in persistence.xml

Glassfish V3

• EclipseLink 1.2 and 2.0+ fully implement the JPA 2.0 specification via enhancement # 248291 and are the RI for the GlassFish V3 JEE6 server.

Glassfish V2

• Glassfish V2.1.1 ships with JPA 1.0 support - in order to use JPA 2.0 on this older server some overrides will be required.
• Ideally,we want a way for end users to override the JPA 1.0 library shipped with Glassfish V2 2.1.1 without modifying the server and affecting other applications.

V2.1 Results Matrix

• The following table summarizes the type of test, Glassfish V2.1 server modifications and results

UC#	Test Example-Description	Container-Managed vs Application-Managed	Injected-EMF vs Persistence bootstrap	Entities, PU in utility JAR	Entities, PU in EJB JAR	Entities, PU in WAR	EAR application xml override	Ability to run persistence.xml 1.0 vs 2.0 tags	Weaving entities	Runs JPA2 Impl in EclipseLink 1.2	Runs JPA2 Impl in EclipseLink 2.0 only
1	Application_Managed EAR(WAR only) - working	application	Persistence bootstrap			PU in WAR	no	none	1.0 - no 2.0	no - off	Y	Y
2	App-Managed case pending... - unknown	application	injected @PersistenceUnit EMF on Servlet	PU in utility JAR			no	none	?	???	???	???
3	Container-Managed EAR(EJB,WAR) - in progess	container	injected @PersistenceContext EM on Stateless Session Bean (EM is proxied, em.getClass().toString = $Proxy84)		PU in EJB			domain.xml (both javax and eclipselink jar refs)	1.0 - no 2.0	???	Y	Y
4	Container-Managed EAR(EJB,WAR) as PS2 with override in EAR descriptor - pending	container	injected @PersistenceContext EM on SSB		PU in EJB		no	none	???2.0	???yes	???	???

Problem

• This document details a solution for enabling JPA 2.0 API functionality for various enterprise application use cases involving application-managed EntityManagers.
• The page is geared to both end users and internal eclipselink.jpa.test server test implementors.
  • 1) End users of Glassfish V2 2.1.1
    • This involves configuring the server for JPA 1.0 permanently or per-deployment
    • Note: This procedure is for application managed deployments - container managed injection will still default to JPA 1.0 for servers that do not ship with 2.0 out of the box
  • 2) EclipseLink JPA test users on Glassfish V2 2.1.1
    • This involves temporarily configuring the server per-test-deployment

Analysis

• EclipseLink 1.2 and 2.0+ fully implement the JPA 2.0 specification via enhancement # 248291 and are the RI for the GlassFish V3 JEE6 server. In order to use this functionality the 2.0 version of the JPA specification jar - javax.persistence.jar must be added higher in the Glassfish server classpath see enhancement # 296269.

Running with the JPA 2.0 XSD in persistence.xml

• We get the following only on V2.1

deploy:
     [exec] CLI171 Command deploy failed : Deploying application in domain failed; Error loading deployment descriptors for module [org.eclipse.persistence.example.jpa.server.glassfishv2.EnterpriseEAR] Line 19 Column 248 -- Deployment descriptor file META-INF/persistence.xml in archive [classes].  cvc-complex-type.3.1: Value '2.0' of attribute 'version' of element 'persistence' is not valid with respect to the corresponding attribute use. Attribute 'version' has a fixed value of '1.0'.

Use Cases

• Use case partitioning criteria
  • Application managed EM
    • @PersistenceUnit EMF or static bootstrap Persistence.createEntityManagerFactory EMF
      • Global scoped datasource
        • UC 1 : JTA global scoped datasource
        • UC 2 : non-JTA global scoped datasource
        • UC 3 : RESOURCE_LOCAL jdbc connector
      • Application scoped datasource
        • UC 11 : JTA global scoped datasource
        • UC 12 : non-JTA global scoped datasource
        • UC 13: RESOURCE_LOCAL jdbc connector
  • Container managed EM
    • @PersistenceUnit EMF and/or @PersistenceContext EM injection on session bean
      • Global scoped datasource
        • UC 21 : JTA global scoped datasource
        • UC 22 : non-JTA global scoped datasource
        • UC 23 : RESOURCE_LOCAL jdbc connector - invalid
      • Application scoped datasource
        • UC 31 : JTA global scoped datasource
        • UC 32 : non-JTA global scoped datasource
        • UC 33 : RESOURCE_LOCAL jdbc connector - invalid

Design

Design Issue 1: JSR-317 JPA 2.0 EJB 3.1 Support

DI 1: Problem

• The libs currently shipped with Glassfish 2.1.1 are the following JPA 1.0 compatible versions - these must be overriden in order to run JPA 2.0 API.
  • lib/javaee.jar (the javax.persistence package)
  • lib/toplink-essentials.jar
  • lib/toplink-essentials-agent.jar
• The toplink-essentials jars are no problem as long as we specify the eclipselink persistence provider in all persistence units.

DI 1: Alternative 1: Manual overwrite of eclipselink and javax.persistence libraries in server/lib

• this will not place the JPA 2.0 higher - deprecated

DI 1: Alternative 2: Reference higher in the server classpath via domain.xml

• Add classpath-prefix="${com.sun.aas.installRoot}/lib/eclipselink.jar;${com.sun.aas.installRoot}/lib/javax.persistence_2.0.0.v200911041116.jar"

DI 1: 4 GBI XML shared-library

..doc in progress...

• Workable solution but it has issues
  • The server now runs a single version of the two libraries for all applications - this may not be compatible with older applications or other JPA providers running on the server.

Resources

• [V2|JPA Web Application Tutorial]
• [V2|JPA Web Application Tutorial]