Skip to main content
Jump to: navigation, search

EclipseLink/Development/JPA 2.0/weblogic

< EclipseLink‎ | Development‎ | JPA 2.0
Revision as of 00:08, 20 January 2010 by (Talk | contribs) (Container Managed Clients)

Running JPA 2.0 API on WebLogic 10.3

WebLogic ships with the JPA 1.0 specification jar - we would like to run JPA 2.0 API on WebLogic. This document describes the solution to container-managed and application managed deployments and the details in getting their use cases running.

Results Matrix

  • The following table summarizes the type of test, server modifications and results
UC# DI# Test Example-Description Container-Managed vs Application-Managed Injected-EMF vs Persistence bootstrap JTA, non-JTA, RESOURCE _LOCAL Datasource Entities, PU in utility JAR Entities, PU in EJB JAR Entities, PU in WAR EAR wls:prefer- application-packages mod? Server modifications? 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 PU EAR(WAR only) - working application Persistence bootstrap JTA PU in WAR Yes none 1.0 no - off Y Y
2 App-Managed case pending... - unknown application injected @PersistenceUnit EMF on Servlet  ? PU in utility JAR  ?Yes none ?  ???  ???  ???
3 Container-Managed PU in EAR(EJB,WAR) - working but with server modifications container injected @PersistenceContext EM on Stateless Session Bean (EM is proxied, em.getClass().toString = $Proxy84) JTA PU in EJB commEnv.cmd (both javax and eclipselink jar refs) 1.0 Weaved Y Y
4 Container-Managed PU in EAR(EJB,WAR) with override in EAR descriptor (no server modifications) - pending container injected @PersistenceContext EM on SSB JTA PU in EJB Yes (javax.persistence.* only) none ???2.0 ???yes  ???  ???

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

Results Summary

  • Container-managed JPA 2.0 entity managers work with the following modifications and constraints.
    • Add both the javax and eclipselink jars to the top of the server classpath
    • Weaving and the new JPA 2.0 interface changes between EclipseLink 1.2 and 2.0 work - see logs
      • [EL Finest]: 2009-12-10 15:05:17.055--ServerSession(11840499)--Thread(Thread[[STANDBY] ExecuteThread: '1' for queue: 'weblogic.kernel.Default (self-tuning)',5,Pooled Threads])--Begin weaver class transformer processing class [].
      • [EL Finest]: 2009-12-10 15:05:17.055--ServerSession(11840499)--Thread(Thread[[STANDBY] ExecuteThread: '1' for queue: 'weblogic.kernel.Default (self-tuning)',5,Pooled Threads])--Weaved persistence (PersistenceEntity) [].
      • [EL Finest]: 2009-12-10 15:05:17.055--ServerSession(11840499)--Thread(Thread[[STANDBY] ExecuteThread: '1' for queue: 'weblogic.kernel.Default (self-tuning)',5,Pooled Threads])--Weaved fetch groups (FetchGroupTracker) [].
    • persistence.xml 2.0 changes will not pass deployment validation


  • 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 WebLogic
      • 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 WebLogic
      • This involves temporarily configuring the server per-test-deployment

  • This page is slated for immediate editing over 20090120-11 to make the conclusions more clear - however we have the following result for container-managed EM's
    • EclipseLink JPA 2.0 code (CriteriaBuilder and weaving work)
      • [EL Example]: enterprise: JPA 2.0 CriteriaBuilder: org.eclipse.persistence.internal.jpa.querydef.CriteriaBuilderImpl@2225ece
    • The EM is a proxy
      • EM: class $Proxy84
    • But, persistence.xml 2.0 tags like <shared-cache-mode>NONE</shared-cache-mode>

will not pass validation on the server Caused By: weblogic.deployment.EnvironmentException: Error loading the persistence descriptor META-INF/persistence.xml from the module org.eclipse.persistence.example.jpa.server.weblogic.enterpriseEJB.jar. See the following stack trace for nested errors: weblogic.descriptor.DescriptorException: VALIDATION PROBLEMS WERE FOUND

 F:\view_w35d\examples\org.eclipse.persistence.example.jpa.server.weblogic.enterpriseEJB\build\classes\META-INF\persistence.xml:19:3:19:3: problem: cvc-attribute.4: The value '2.0' does not equal the fixed value '1.0' of attribute 'version':<F:\view_w35d\examples\org.eclipse.persistence.example.jpa.server.weblogic.enterpriseEJB\build\classes/META-INF/persistence.xml:19:3>
 F:\view_w35d\examples\org.eclipse.persistence.example.jpa.server.weblogic.enterpriseEJB\build\classes\META-INF\persistence.xml:28:11:28:11: problem: cvc-complex-type.2.4a: Expected elements 'class@ exclude-unlisted-classes@ properties@' instead of 'shared-cache-mode@' here in element persistence-unit@<F:\view_w35d\examples\org.eclipse.persistence.example.jpa.server.weblogic.enterpriseEJB\build\classes/META-INF/persistence.xml:28:11>

  • We want a way for end users to override the JPA 1.0 library shipped with WebLogic Server without modifying the server and affecting other applications.


  • 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 WebLogic
      • 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 WebLogic
      • This involves temporarily configuring the server per-test-deployment


  • 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 WebLogic server classpath see enhancement # 296271.
  • Now, you may have noticed that the modules/org.eclipse.persistence_1.0.0.0_1-2-0.jar jar contains JPA 2.0 API implementation classes such as org.eclipse.persistence.internal.jpa.metamodel - however this API is not available through interface classes (because only the javax.persistence 1.0 jar is present) and we also are missing the services file for Criteria/Metamodel - in any case a predeploy should fail where the EAR contains JPA 2.0 API out of the box.

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 - alternative #3
          • 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 Issue 1: JSR-317 JPA 2.0 EJB 3.1 Support

DI 1.1: Problem

  • The modules currently shipped with WebLogic (Patch Set 1) in are the following JPA 1.0 compatible versions - these must be overriden in order to run JPA 2.0 API.
    • modules/org.eclipse.persistence_1.0.0.0_1-2-0.jar
    • modules/javax.persistence_1.0.0.0_1-0-2.jar
DI 1.1: Alternative 1: Manual overwrite of eclipselink and javax.persistence libraries in modules
  • Current solution - this should be deprecated.
DI 1.1: Alternative 2: Reference higher in the server classpath via commEnv.cmd
  • 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.
DI 1.1: Solution
  • In <WEBLOGIC_HOME>\wlserver_10.3\common\bin\commEnv.cmd
    • change
      • set WEBLOGIC_CLASSPATH=%JAVA_HOME%\lib\tools.jar...
    • To
      • set WEBLOGIC_CLASSPATH=F:/view_w35d/jpa/plugins/javax.persistence_2.0.0.*.jar;%JAVA_HOME%\lib\tools.jar...
      • where F:/view_w35d == %SVN_TRUNK
  • Note: do not use the javax.persistence_2.0_preview.jar - the dated javax.persistence_2.0.0.*.jar one is the final PFD version for the JPA 2.0 specification.
DI 1.1: Alternative 3: Application Level Shared Library - In Use

This example uses an application-managed EE injected EMF.

  • 20091202 working standalone Eclipse EAR (WAR only) prototype attached bug 296271 - this procedure has been verified on 2 separate servers on separate machines (in order to filter out any possible leftover configuration experimentation that could skew results)
  • The following artifacts and modifications are required (failure of any one of these will result in a Persistence Unit not found during deployment or runtime)
  • 1) Start with an EAR project containing only a WAR (no ejb-jar) - Eclipse can generate one for you after you install the WebLogic Eclipse Plugin
  • 2) Ship EclipseLink 2.0 and JPA 2.0 in the EAR project (not the WAR)
    • 2a) Add eclipselink.jar V2 (OSGI version is org.eclipse.persistence_1.0.0.0_2-0-0.jar) to EarContent\APP-INF\lib - this will override org.eclipse.persistence_1.0.0.0_1-2-0.jar in the modules dir on the server
    • 2b) Add the JPA 2.0 specification jar - this will override javax.persistence_1.0.0.0_1-0-2.jar.
  • 3) Update the .MANIFEST where the root of the entity classes managed by the EntityManager reside (here the src\META-INF off the WAR) to point to these included jars (relative paths not required if they are in the classpath - which they are)
    • Class-Path: javax.persistence_2.0.0.v200911041116.jar eclipselink.jar
  • 4) Place your persistence.xml descriptor as usual for an application-managed entityManager in the WAR also at the classes root in src\META-INF - this will be exported to the server as classes. (Normally for a container-managed entityManager we would place persistence.xml and all entities in the ejb jar)
    • 4a) make sure to modify the Entity package paths as we are dealing with an SE persistence unit here
  • 5) Add the prefer-application-packages element to weblogic-application.xml so the internal WebLogic API FilteredClassLoader places our library ahead of the modules directory.
  • 6) The EMF is either EE injected or obtained via a static SE Persistence call
    private EntityManagerFactory emf;
    private EntityManagerFactory emf;
    emf  = Persistence.createEntityManagerFactory("example);
  • 7) The following configuration elements are not present in this procedure
    • - no web.xml persistence-context-ref
    • - no weblogic-application.xml 'wls:library-ref
    • - no global shared-library EAR on the server either via the console or via the Eclipse IDE.
    • - no overriding javax.persistence or eclipselink.jar in the modules, domain/lib, wlserver_10.3/common/lib or wlserver_10.3/server/lib directories
    • - no scripted override on either wlserver_10.3/common/bin/commEnv.cmd or base_domain/bin/startWebLogic.cmd
  • Note: at this time there is no requirement to add WebLogic platform specific handling for the FilteredClassLoader - we are ok with the XML EAR deployment descriptor change.
Output 1.3
  • Note that the entityManager.getMetamodel() JPA 2.0 call in the application is resolved correctly with this fix.

Weblogic app managed em ear jpa2 server classpath override browser output 296271.JPG

DI 1.1: Alternative 4: Global Level Shared Library

Weblogic shared libraries in eclipse preferences.jpg

  • In this scenario we will require the creation of an EAR deployment application that can be referenced from any other EAR application that requires the EclipseLink override.
DI 1.1: Alternative 5: Domain Extension Template
  • 20091202 - This one suggested by Doug - similar to what is done for other vendor libraries.
  • This method involves copying the JPA 2.0 libraries to the lib directory off the current domain
    • example: %WEBLOGIC_HOME%\user_projects\domains\base_domain\lib
    • is below
    • %WEBLOGIC_HOME%\modules
  • The domain lib override alternative will not work because this lib is below the server classpath and has no effect after 10.3.0.
  • Our current weblogic.xml test script copies the xdb, spatial, jdbc, junit, xmlparserv2 and trunk eclipselink.jar to the domain lib - however this only works if no library is in modules that will override these domain libs.

Since 10.3.1 the user still needs to apply a patch to override modules libs in these lib cases. Therefore this option is deprecated for 10.3.1 and 10.3.2 since we started shipping with the eclipselink jar.

  • Potential modification to weblogic.xml:weblogic-install is (without $ variable prefix)
  <copy file="F:/view_w35d/jpa/plugins/javax.persistence_2.0.0.v200911041116.jar" todir="${weblogic.domain}/lib"/>
  • Another issue to solve is the absence of OSGI functionality - fixed by editing the .MANIFEST - see bug# 296733
<2-Dec-2009 1:09:45 o'clock PM EST> <Notice> <WebLogicServer> <BEA-000395> <Following extensions directory contents added to the end of the classpath:
<2-Dec-2009 1:09:45 o'clock PM EST> <Critical> <WebLogicServer> <BEA-000386> <Server subsystem failed. Reason: 
java.lang.NoClassDefFoundError: org/osgi/framework/BundleActivator
java.lang.NoClassDefFoundError: org/osgi/framework/BundleActivator
DI 1.1: Alternative 6: Use -Dweblogic.ext.dirs override
  • Like alternative #5 - this one is also appended to the end of the server classpath - so is not of use.
  • base_domain/bin/startWebLogic.cmd
    • JAVA_OPTIONS=%JAVA_OPTIONS% -Dweblogic.ext.dirs=F:/view_w35d/jpa/plugins/javax.persistence_2.0.0.v*.jar

DI 1.2:

DI 1.2: Alternative 1:

DI 1.3:

DI 1.3: Alternative 1:

DI 1.4:

DI 1.4: Alternative 1:


Application Managed Clients

  • The shared-library approach has been prototyped as Alternative #3 and functions fine for EARs that utilize application managed entitymanagers - the Eclipse 1.2 and JPA 1.0 libraries shipped with WebLogic are overriden by the supplied EclipseLink 2.0 and JPA 2.0 libraries in the EAR.
  • See the development bug #296271 for attached EAR test archives.

Container Managed EM Clients

  • Support for container managed EM applications is as-is with out of the box JPA 1.0 API functionality - however the alternatives above give WebLogic server administratiors options for setting the JPA 2.0 specification library ahead of the shipped 1.0 jar in the server classpath.

Eclipse IDE Project Details

  • When creating an EAR project in Eclipse that targets a WebLogic runtime and uses JPA 2.0 functionality - you will receive a compile error on the new JPA 2.0 interface changes for EntityManager and EntityManagerFactory unless you put the JPA 2.0 specification library higher in your compile classpath than the default WebLogic Container Libraries.

Eclipse ejb project jpa2 library above weblogic system library.JPG


  • 20091201: Start investigation
  • 20091202: Scope of this issue has been reduced to the application managed EAR level - @PersistenceContext injection of a 2.0 EM is not supported for EE servers that do not support JPA 2.0 out of the box.
    • The example used for EAR testing uses a container-managed EM via the following injected bean - this will be modified
@Local @Stateless
public class ApplicationService implements ApplicationServiceLocal {
	@PersistenceContext(unitName="example", type=PersistenceContextType.TRANSACTION)	
	private EntityManager entityManager;
  • 20100112: returning to this issue after a hold on 20091218

Meeting Minutes


  • Application Managed
    • JPA 2.0 EM is ok with alternative #3 (<prefer-application-packages>) workaround.
  • Container Managed
    • Need to debug server $Proxy code and verify that we get proxies for all EntityManagerFactory, EntityManager, Query and EntityManagerTransaction?
      • This will aide us in determining where the server group can return us a proper error message for mixed JPA 1.0 and 2.0 configurations.


Back to the top