<font color="red">Note: This tutorial' is under construction for the next week as of 2010415 under bug# '''[http://bugs.eclipse.org/309201 309201]'''.</font>

+

−

+

−

If you want to get a small web application running quickly on WebSphere 7.0 you can use Eclipse to create the EAR and [[EclipseLink/Examples/JPA/WebSphere7_Web_Tutorial#Remote_Debugging_EclipseLink_in_WebSphere_7.0_from_Eclipse_3.4|attach to a running WebSphere instance in debug mode on port 7781]].

+

−

+

−

This basic example details how to use Eclipse to run/debug a minimum J2EE web application servlet using EclipseLink JPA as the persistence provider. The goal of this example is to detail the minimum steps required to run EclipseLink inside the [http://www.ibm.com/developerworks/downloads/ws/was/?S_TACT=105AGX28&S_CMP=DLMAIN&S_CMP=rnav IBM WebSphere Application Server 7.0] server using the Eclipse IDE. At this point no presentation/controller layer such as JSF, Spring or Struts will be used beyond a basic HttpServlet so we can concentrate on the the integration layer JPA setup.

+

−

+

−

The [http://wiki.eclipse.org/Dali DALI] project can be used to generate Entities from a schema with sequences already populated.

+

−

+

−

Tables can be populated by persisting an instance of the mode in an SE JPA persistence unit with DDL generation turned on.

+

−

+

−

'''The recommended configuration for running EclipseLink as the JPA provider on WebSphere 7 are the following [http://wiki.eclipse.org/EclipseLink/Examples/JPA/WebSphere7_Web_Tutorial#Container_Managed_and_Application_Managed_Scenarios container managed scenarios] below.'''

*I am running this on both a 32-bit P630 2Gb machine and a Corei7 64-bit Windows7 12Gb machine - Note: '''installing the 32 bit version of WebSphere 7 on a 64-bit OS will require a full reboot of the server before you can start the container'''.

+

−

*Note: Developing/Debugging an enterprise application works excellent if you use IBM Rational Developer as the Eclipse based IDE where 7.0 server support currently exists. However if you wish to debug from an unenhanced standard Eclipse 3.5 EE IDE you must run through some hoops and export your EAR manually, deploy/update it in the admin console and attach to the debuggable process manually. In other application servers such as WebLogic, OC4J, Glassfish, Tomcat and even WebSphere 6.0 this process is handled automatically for you via an eclipse plugin.

+

−

+

−

==Prerequisites==

+

−

===<font color="green">Install Eclipse EE</font>===

+

−

*I installed a clean version of Eclipse Galileo 3.5 SR2 EE Edition (32-bit) (April 2010) on a Window 7 64-bit install where the default JRE was the 64-Bit server version of the SUN JVM. I therefore needed to override the default ''java.exe'' by specifying the following shortcut override

*Default [[EclipseLink/Development/Testing/Prereq#Recommended_eclipse.ini_settings_for_EclipseLink|eclipse.ini]] settings must be modified as referenced.

+

−

+

−

===<font color="green">Install a Database</font>===

+

−

*We will be using a remote '''Oracle 11''' instance as well as a ''local'' '''[[EclipseLink/Examples/JPA/Derby|Derby 10.5.3.0]]''' instance or the embedded '''Derby''' instance that comes with WebSphere.

+

−

+

−

===<font color="green">Install WebSphere 7.0</font>===

+

−

*I installed the commercial '''7.0.0.0''' version of IBM WebSphere 7 and then the '''7.0.0.5''' '''fixpack in 7.0.0-WS-WAS-WinX32-FP0000005.pak''' using the ''7.0.0.5-WS-UPDI-WinIA32.zip'' installer.

+

−

*[[Image:Ibm_websphere_fixpack_7001_result.JPG]]

+

−

+

−

===Install WebSphere Eclipse 3.4 Server Plugin - unusable===

+

−

We will first see if the WebSphere 6.0 or 6.1 plugin works with WebSphere 7.0 - it fails on missing jar files that are not present in 7.0.

+

−

The WebSphere 6.1 Eclipse WTP server plugin is not shipped by default with Eclipse (WebSphere 6.0 for JEE 1.4 is).

+

−

*'''Note: The WebSphere 6.1 plugin for Eclipse WTP is currently being developed - see the following [http://bugs.eclipse.org/160220 Eclipse WTP enhancement request 160220 in progress].

+

−

*We are not blocked from using Eclipse WTP to manage the WebSphere 6.1 server, but without this plugin we will need to attach manually to port 7781 of a running WebSphere server that was started in debug mode outside of the Eclipse IDE - we will use this alternate debug approach.

+

−

*<font color="red">If you try to stub out the 73 jars required by the WebSphere 6.0 plugin to make it work with a WebSphere 7.0 server - you will get the following exception '''starting''' WebSphere from Eclipse.</font> - ''so don't do it''

at com.ibm.ws.runtime.WsServerImpl.bootConfigService(WsServerImpl.java:335)

+

−

at com.ibm.ws.runtime.WsServerImpl.start(WsServerImpl.java:171)

+

−

</source>

+

−

+

−

==WebSphere Configuration Changes==

+

−

*WebSphere configuration modifications can be done on the admin console .

+

−

**http://localhost:9060/ibm/console/

+

−

**Which redirects to

+

−

***https://localhost:9043/ibm/console/login.do?action=secure

+

−

***or if a secure login was not selected

+

−

***http://localhost:9060/ibm/console/unsecureLogon.jsp

+

−

+

−

==JNDI Datasource Setup==

+

−

+

−

===Global Scoped Datasource Setup===

+

−

*We will ''for now'' use the already configured JNDI name '''"DefaultDatasource"'''.

+

−

*Note the check box '''"Use this data source in container managed persistence (CMP)"''' that allows us to use this TX datasource for all our container managed deployments below.

+

−

[[Image:DefaultDatasource_derby_on_websphere7.JPG]]

+

−

+

−

==Downloading EclipseLink Libraries==

+

−

===Download EclipseLink using HTTP - recommended===

+

−

*Proceed to the following URL and download the latest eclipselink.zip which contains everything you need.

+

−

**http://www.eclipse.org/eclipselink/downloads/index.php

+

−

***'''Click on the "EclipseLink Installer Zip''' link which resolves to http://www.eclipse.org/downloads/download.php?file=/rt/eclipselink/releases/n.n.n/eclipselink-n.n.n.zip

+

−

*Expand the zip file and get the following 2 files

+

−

**eclipselink-*\eclipselink\jlib\eclipselink.jar

+

−

**eclipselink-*\eclipselink\jlib\jpa\javax.persistence_*.jar

+

−

===Download EclipseLink using Maven===

+

−

See the repository on http://www.eclipse.org/eclipselink/downloads/index.php

+

−

===Download EclipseLink using SVN - developers only===

+

−

*Get the following ''<font color="blue">eclipselink.jar</font>'' and ''<font color="blue">javax.persistence*.jar</font>'' from http://www.eclipselink.org ready for your EclipseLink shared library.

+

−

**The following page details four different ways to either obtain the binary jars or download the source and build them yourself with an anon account.

+

−

**http://wiki.eclipse.org/EclipseLink/Source

+

−

+

−

=Container Managed and Application Managed Scenarios=

+

−

*The steps below detail what needs to be done to migrate an existing JPA enterprise application to use a JPA provider other than the shipped '''OpenJPA''' - like the '''org.eclipse.persistence.jpa.PersistenceProvider''' provider.

*<font color="red">'''This section is currently undergoing review and minor editing as more deployment scenarios are tested today (20100419)'''</font>

+

−

*The following section details investigations on what configurations work when using the '''EclipseLink''' JPA provider on the '''IBM WebSphere 7''' Application Server. The test deployments are configured around ''<font color="green">container managed</font>'' EARs that require server modification such as creating a global shared library or placing the eclipselink.jar library directly in the '''%SERVER%/lib''', and ''<font color="blue">application managed</font>'' EARs that do not require any server modification as they ship the required libraries as part of the EAR.

+

−

===EAR Source===

+

−

*The following [https://bugs.eclipse.org/bugs/attachment.cgi?id=165341 EAR attachment] for bug# [http://bugs.eclipse.org/309201 309201] can be used as source until this project is checked into SVN.

+

−

*Note: eclipselink.jar must be readded to the EAR in the position of '''EAR/APP-INF/lib/eclipselink.jar'''

*Placing the eclipselink.jar library directly on the server in the '''%SERVER%/lib''' directory and restarting the server will allow container managed deployments of EclipseLink applications following the JPA 1.0 specification to inject and function correctly.

*This is an interesting use case where the eclipselink JPA library is included locally in the EAR ''(requiring no server modifications)'' but the persistence unit itself is container managed by '''@PersistenceUnit''' injection on a ''stateless session bean''.

+

−

*The following [https://bugs.eclipse.org/bugs/attachment.cgi?id=165341 EAR attachment] for bug# [http://bugs.eclipse.org/309201 309201] can be used as source until this project is checked into SVN.

+

−

*Note: eclipselink.jar must be readded to the EAR in the position of '''EAR/APP-INF/lib/eclipselink.jar'''

+

−

====Injected EntityManager on the SSB====

+

−

*We get a <font color="green">'''JPATxEntityManager@14001400'''</font> entityManager instance injected from the WebSphere container - this looks like a proxy wrapper for our EntityManagerImpl. - Normally I would '''<font color="orange">debug</font>''' this to verify but I am having difficulty attaching to port 7777 using my own instructions for WebSphere 6.1

*None - I did not override the '''Class Loader Order''' - it is still set to ''Classes loaded with parent class loader first''.

+

−

=====EclipseLink library in EAR=====

+

−

*org.eclipse.persistence.example.jpa.server.websphere.EnterpriseEAR

+

−

**EarContent

+

−

***APP-INF

+

−

****lib

+

−

*****'''<font color="red">eclipselink.jar</font> - note there is no eclipselink.jar on the server.

+

−

+

−

======MANIFEST.MF======

+

−

*Place the following path to the included '''eclipselink.jar''' in your ejb.jar's <font color="green">'''ejbModule/META-INF/MANIFEST.MF'''</font> file. This is the recommended approach where you update the manifest that is at the root of where your '''entities'' are - in this case as part of the ejb.jar.

+

−

*In my example application, there are 3 MANIFEST.MF files, one on the WAR, one on the ejb.jar and one on the EAR.

+

−

**''EAR/META-INF/MANIFEST.MF''

+

−

**'''EJB/ejbModule/META-INF/MANIFEST.MF''' - update this one to point to the eclipselink.jar in the ''EAR/APP-INF/lib'' directory.

+

−

**''WAR/WebContent/META-INF/MANIFEST.MF''

+

−

*As a recommended test I removed all 3 manifest entries below and received an expected <font color="red">Injection failure</font>

[4/19/10 12:56:52:458 EDT] 0000001a EJBContainerI I CNTR0167I: The server is binding the org.eclipse.persistence.example.jpa.server.business.ApplicationServiceLocal interface of the ApplicationService enterprise bean in the org.eclipse.persistence.example.jpa.server.websphere.EnterpriseEJB.jar module of the org.eclipse.persistence.example.jpa.server.websphere.EnterpriseEAR application. The binding location is: ejblocal:org.eclipse.persistence.example.jpa.server.websphere.EnterpriseEAR/org.eclipse.persistence.example.jpa.server.websphere.EnterpriseEJB.jar/ApplicationService#org.eclipse.persistence.example.jpa.server.business.ApplicationServiceLocal

===<font color="red">''No EclipseLink library on the Server or the EAR''</font>===

+

−

*This is not a valid configuration because the EclipseLink JPA provider library is needs to be added either on the server or via the APP-LIB directory of the EAR for Container or Application managed scenarios.

+

−

*You will see the following exception if you attempt to use the '''org.eclipse.persistence.jpa.PersistenceProvider''' in this case. This forms a good base case failure test upon which the other valid scenarios can be verified against.

+

−

**javax.ejb.EJBException: Injection failure; nested exception is: java.lang.IllegalStateException: EntityManagerFactory has not been created for PU : PuId=org.eclipse.persistence.example.jpa.server.websphere.EnterpriseEAR#org.eclipse.persistence.example.jpa.server.websphere.EnterpriseEJB.jar#example

+

−

+

−

==Application Managed==

+

−

*The primary use case that requires an appplication managed entityManager is one where the application developer does not have access to the server to create global or local scope '''Shared Libraries'''. In this case all library configuration and classloader scope changes must be done inside the EAR itself.

+

−

*For either the developer that has access to the deployment workflow on the WAS console - We can modify the classloader to load the '''parent last''' using the following [http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/topic/com.ibm.websphere.zseries.doc/info/zseries/ae/trun_classload_entapp.html procedure from DeveloperWorks].

*placing the eclipselink.jar in the EAR and attempting to use the SE Persistence bootstrap class to create an EMF on a '''Stateless Session Bean - in the EJB.jar''' - ''(on the EJB container instead of the WEB container)'' does not work because the classloader position of the eclipselink.jar is not visible to the '''JPA 1.0 persistence library''' that ships with the server higher up.

[4/16/10 11:23:09:218 EDT] 0000001d SystemErr R WARNING: Found unrecognized persistence provider "org.eclipse.persistence.jpa.PersistenceProvider" in place of OpenJPA provider. This provider's properties will not be used.

*The following logs show evidence of '''Weaving''' ''(bytecode instrumentation for change tracking and cache performance)'', '''EntityManagerFactory''' and '''EntityManager''' ''EclipseLink'' JPA provider instances and their usage.

*The following screen capture illustrates the fact that 5 entities were read from in this case a Derby 10.5.3.0 database using a RESOURCE_LOCAL @PersistenceUnit injected EMF on a Servlet client as part of the WAR in an EAR that contains the eclipselink.jar library embedded - essentially an SE application.

[org.xml.sax.SAXParseException: 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'.]

+

−

at javax.xml.bind.helpers.AbstractUnmarshallerImpl.createUnmarshalException(AbstractUnmarshallerImpl.java:326)

+

−

Caused by: org.xml.sax.SAXParseException: 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'.

+

−

at org.apache.xerces.util.ErrorHandlerWrapper.createSAXParseException(Unknown Source)

+

−

</source>

+

−

[[Image:App_managed_jpa2_ear_fails_to_deploy_on_websphere_7.JPG]]

+

−

*Also, if we try using JPA 2.0 API via a persistence.xml that is defined as JPA 1.0 so it passed deployment - we will still get an expected runtime exception when we try to use JPA 2.0 commands.

+

−

<source lang="java">

+

−

[4/16/10 16:08:47:578 EDT] 0000001b servlet E com.ibm.ws.webcontainer.servlet.ServletWrapper service SRVE0068E: Uncaught exception created in one of the service methods of the servlet FrontController in application org.eclipse.persistence.example.jpa.server.websphere.EnterpriseEAR. Exception created : java.lang.NoSuchMethodError: javax/persistence/EntityManager.getMetamodel()Ljavax/persistence/metamodel/Metamodel;

+

−

at org.eclipse.persistence.example.jpa.server.business.ApplicationManagedService.getMetamodel(ApplicationManagedService.java:139)

+

−

</source>

+

−

+

−

==Persistence JAR location==

+

−

*Where does the standard library '''plugins/com.ibm.ws.jpa.jar''' and '''runtimes/com.ibm.ws.jpa.thinclient_7.0.0.jar''' fit in? Is this a JPA spec jar or an '''OpenJPA''' implementation?

+

−

+

−

==JDBC JAR location==

+

−

*If you are using a JDBC provider other than the 3 provided by WebSphere, you must defined all of the '''JDBC Providers''', the '''Data sources''' and the secondary '''JAAS-J2C authentication data''' sections in the admin console for your new datasource.

+

−

[[Image:Was_console_oracle_datasource1.JPG]]

+

−

+

−

==Remote Debugging EclipseLink in WebSphere 7.0 from Eclipse 3.4==

+

−

The following procedure details how to attach to a debug version of IBM WebSphere 7.0 with the Eclipse 3.4 IDE.

+

−

+

−

Note: we will not be modifying startServer.bat. The java process in that script is only for server startup - if you need to debug this part of the server.

+

−

===Modify console setup to start server in debug mode===

+

−

*Login to the console using your admin login or a default username like ''system''