Jump to: navigation, search

EclipseLink/Examples/JPA/OC4J Web Tutorial

< EclipseLink‎ | Examples‎ | JPA
Revision as of 13:49, 26 February 2009 by Michael.obrien.oracle.com (Talk | contribs) (Document History)

EclipseLink JPA Deployed on OC4J using Eclipse WTP

Document History

Date Author Version Description & Notes
20080414 Michael O'Brien Initial version covering Oracle OC4J and
20090217 Michael O'Brien Update for version or 10.1.4 - In progress as of 20090223

If you want to get a small web application running quickly on OC4J use the services provided by the Web Tools Project plugin in the Eclipse IDE to take care of deployment details for you.

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 needed to run EclipseLink inside OC4J 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 DALI project was used to generate Entities from a schema with sequences already populated.

Development Environment

Hardware: Windows Vista SP1, Core2Duo E8400 45nm, 3.0Ghz, 3Gb Ram

Software: Eclipse IDE for Java EE 3.4 Ganymede (SR1 Oct 2008), Oracle 11g DB, Java JDK 1.6.0_07, OC4J 20080709

This example will run fine with any DB that EclipseLink supports via the eclipselink.target-database tag.


  • Install Eclipse
    • I installed a clean version of Eclipse Ganymede M5 with all of WTP 3.0
  • Install a Database
    • In this example I am using Oracle 11g, the table schemas have already been created manually and all entity java classes have been generated using the Eclipse DALI tool.

Verify OC4J Installation

  • Before we add EclipseLink and our own JTA datasource to OC4J, lets verify the installation outside of eclipse before adding the server to the IDE.

Start OC4J the first time Outside Eclipse

  • If this is the first time you are running your OC4J server, you will want to login from a CMD prompt - to set the admin password.
  • The ORACLE_HOME environment variable should also be set to a truncated OC4J_HOME or c:\opt\oc4j1014
  • Launch server via CMD prompt - and create your admin password.
C:\opt\oc4j1014\bin>oc4j -start
Starting OC4J from c:\opt\oc4j1014\j2ee\home ...
2009-02-18 14:15:03.406 NOTIFICATION Auto-unpacking C:\opt\oc4j1014\j2ee\home\applications\dms.war...
Feb 18, 2009 2:15:09 PM com.evermind.server.XMLApplicationServerConfig randomizeJtaAdminPassword
INFO: Updating JtaAdmin account
09/02/18 14:15:09 Set OC4J administrator's password (password text will not be displayed as it is entered)
Enter password:
Confirm password:
The password for OC4J administrator "oc4jadmin" has been set.
09/02/18 14:15:21 The OC4J administrator "oc4jadmin" account is activated.
09/02/18 14:15:27 Oracle Containers for J2EE 10g (  initialized
  • Verify HTTP 8888 and ORMI 23791 ports are running.
C:\opt\oc4j1014\bin>netstat -a
  TCP           mfobrien-PC3:0         LISTENING
  TCP          mfobrien-PC3:0         LISTENING

Oc4j em admin welcome screen.jpg

  • Verify that shutdown works fine
    • Open a separate cmd prompt and shutdown the server.
C:\opt\oc4j1014\bin>oc4j -shutdown -port 23791 -password password
Shutdown OC4J instance...
  • Observe that oc4j is shutdown in the original CMD prompt.
09/02/18 14:38:22 Shutting down...

OC4J configuration Changes

  • OC4J ships with a default JTA datasource called OracleDS that points to an Oracle DB install on the same machine.
  • Use or Edit the OC4J config in $OC4J_HOME/config/data-sources.xml and enter the following DataSource definition for JTA and non-JTA sources and refering to it in the managed-data-source. The only thing you may need to change is the IP address if your database server is on another machine, the user, password and schema name orcl.
  <managed-data-source name="OracleDS" connection-pool-name="local oracle11g" jndi-name="jdbc/OracleDS"/>
  <connection-pool name="local oracle11g">
    <connection-factory factory-class="oracle.jdbc.pool.OracleDataSource"

Oc4j em admin data sources url.jpg

Note: If you modify a JDBC datasource using the EM UI - the data-sources.xml will be completely regenerated and any commented elements will be overwritten - if you would like to keep them then edit data-sources.xml manually.

EclipseLink JAR location

There are 2 jar files required to run the EclipseLink provider on OC4J - eclipselink.jar and a version of the specification jar - currently javax.persistence_2.0_preview.jar.

eclipselink.jar on the Server or EAR?

  • It is not recommended that you distribute eclipselink.jar with your EAR application in a production environment.
  • Why? One reason is that an application deployed EclipseLink jar will be lower on the server ClassLoader tree and will not be available to other modules or applications higher up due to hierarchical visibility constraints. However, there may be occasions during development or staging that you will want to run a local copy or different version than the one loaded from the modules directory - I have not tested this scenario yet, a test of the 3 use cases will be required.

Option 1: Leave shipped module as is in

  • As of OC4J Server / 10.1.4 the EclipseLink library is shipped in the following location on the server.
  • Out of the box the EclipseLink provider will not be found on OC4J without some configuration changes - it currently defaults to TopLink Essentials.
  • You may use this version unless you would like to override the jar with a different version in options 2-3 below
    • $OC4J_ROOT/toplink/jlib/eclipselink.jar (I am running rev

oracle.persistence shared library

  • Since OC4J a shared-library element has been shipped with the server config.
  • In $OC4J_HOME/config/server.xml the following configuration for the shared library oracle.persistence is setup.
  • You may have a question about how this library relates to our EclipseLink persistence provider?
	<shared-library name="oracle.persistence" version="1.0" library-compatible="true">
		<code-source path="../../../toplink/jlib/toplink-essentials.jar"/>
		<import-shared-library name="oracle.jdbc"/>
  • Verify also that the two shared libraries oracle.persistence and oracle.toplink are referenced in $OC4J_HOME/config/system-application.xml - they should be.
    <import-shared-library name="oracle.toplink"/>
    <import-shared-library name="oracle.persistence"/>
  • There is also an empty directory for toplink that can be ignored.

Option 2: eclipselink.jar in applib

The eclipselink.jar may be placed as noted by config/server.xml in the directory $OC4J_HOME/applib or in my case C:\opt\oc4j1014\j2ee\home\applib

  <!-- Global application libraries -->
  <shared-library name="global.libraries" version="1.0" library-compatible="true">
    <code-source path="../applib"/>

Details on how this would work with the shipped eclipselink.jar in $OC4J_ROOT/toplink/jlib requires expansion. However if you go the route of using the applib directory then you will need to also put a version of javax.persistence.*.jar as well as a version of the jdbc jar your database requires - in my case orai18n.jar or ojdbc14.jar.

Otherwise you will see the following missing JDBC jar CNFE on your first entityManager interaction with the database.

09/02/26 13:23:16 javax.ejb.EJBException: java.lang.NoClassDefFoundError: org/eclipse/persistence/internal/platform/database/oracle/TIMESTAMPTypes
09/02/26 13:23:16 	at com.evermind.server.ejb.EJBUtils.getLocalUserException(EJBUtils.java:337)

You will see the following on startup...TBD

Option 3: eclipselink.jar specified at startup

TBD. If you want to reference eclipselink.jar outside of the OC4J install then you must modify the startup script that was generated for your domain.

see $OC4J_ROOT/bin/oc4j.cmd:183 appended to the following line.

"%JAVA_HOME%\bin\java" %JVMARGS% -jar "%OC4J_JAR%" %CMDARGS% 


  • EclipseLink supports JPA 1.0 and a preview of JPA 2.0, this jar is shipped in $OC4J_ROOT/toplink/jlib where $OC4J is c:/opt/oc4j1014 in my case.

JDBC JAR location

  • There is an existing Oracle jdbc driver in OC4J_HOME/../jdbc/lib/orai18n.jar
  • Or, copy your specific jdbc driver jar to $OC4J_HOME/applib

Create server in Eclipse

Open the servers view New | Server | Oracle | Oracle OC4J Standalone Server 10.1.3.n (it is ok to use this one for 10.1.4). The only default you may need to change is the admin user from oc4jadmin to fmwadmin.

Eclipse oc4j server setup 2.jpg

Update in progress 20090223 past this point...

Verify OC4J server launch from Eclipse

You will see the following after starting the server from the servers' tab - no TopLink product interaction happens yet.

09/02/26 09:55:00 Oracle Containers for J2EE 10g (  initialized

Create J2EE application

Check out the 3 example projects in the trunk '(TBD) or create your own J2EE Enterprise Application as below. File | new | project | J2EE | Enterprise Application Project Select server, use 5.0 Ear version

Create a new Web and an optional EJB project

Select generate deployment descriptor if you want to change the context-root

  • Path changes
	<classpathentry combineaccessrules="false" kind="src" path="/eclipselink.core"/>
	<classpathentry combineaccessrules="false" kind="src" path="/eclipselink.jpa"/>
  • After EAR project creation - reference eclipselink.core and eclipselink.jpa or include a reference to eclipselink.jar in your WAR project.
  • If you don't reference the eclipselink.* projects then include a classpath reference to persistence.jar and an Oracle JDBC driver jar for your DB - You will need to put this JDBC driver jar in your OC4J applib directory as well.


  • Put persistence.xml in yourProjectEJB/ejbModule/META-INF
<persistence version="1.0" xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd">
    <persistence-unit name="statJPAJ2EE" transaction-type="JTA">
… other entity classes
            <property name="eclipselink.target-server" value="OC4J"/>
            <property name="eclipselink.weaving" value="true"/>
            <property name="eclipselink.logging.level" value="FINEST"/>

J5EE: Container Managed Persistence

  • Inject the Session Bean (DAO) and the EntityManager via
public class ApplicationService implements ApplicationServiceLocal {
	private EntityManager entityManager;

public class FrontController extends HttpServlet implements Servlet {
	public ApplicationService applicationService;

J2SE: Application Managed Persistence

  • Put persistence.xml in yourProjectWeb/src/META-INF
<persistence version="1.0" xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd">
    <persistence-unit name="statJPAJ2EE" transaction-type="RESOURCE_LOCAL">
… other entity classes
            <property name="eclipselink.target-server" value="OC4J"/>
            <property name="eclipselink.logging.level" value="FINEST"/>

Start Server

  • Steps: Select the EAR and [Run on Server].
  • The first "Run on Server" may not start the server, in this case you "Start Server" and then "Run on Server".

Publish EAR

  • Eclipse WTP will take care of dynamically generating all the orion*.xml files required by OC4J when you either [re-publish] or modify any files while the server is running.
  • You may also use any combination of running the OC4J server yourself in run or debug mode and using eclipse to publish EAR changes.
  • In the predeploy EAR Ant task you should see weaving messages for your entities if logs are set to FINEST in persistence.xml
  • Depending on your application you will see the following after running [start server]
    • In your console window you will see two processes - one for the server and the second for the deploy target.
Oracle OC4J SA Server localhost [Generic Server]	
	C:\jdk1.5.0\bin\javaw.exe (Apr 9, 2008 9:06:19 AM)	
<terminated>jpaELTestEAR module publisher [Ant Build]	
	<terminated, exit value: 0>C:\jdk1.5.0\bin\javaw.exe (Apr 9, 2008 9:06:36 AM)	
  • If you click on the deploy target console you will see the deploy logs from the WTP oracle*.xml Ant target...
Buildfile: C:\eclipse34\plugins\org.eclipse.jst.server.generic.oc4j_1.5.105.v20071217\buildfiles\oracle.10.1.3.xml
      [jar] Building jar: C:\opt\oc4j11samba\j2ee\home\applications\jpaELTestEAR.ear
[oracle:deploy] Deploying application jpaELTestEAR.
[oracle:deploy] Application deployer for jpaELTestEAR COMPLETES.
  • If you click on the server console you will see the predeploy weaving logs
08/04/09 09:06:29 Oracle Containers for J2EE 11g (  initialized.
08/04/09 09:06:39 Application Deployer for jpaELTestEAR STARTS.
08/04/09 09:06:39 Started application : jpaELTestEAR
08/04/09 09:06:39 Binding jpaELTestWeb web-module for application jpaELTestEAR to site default-web-site under context root jpaELTest
[EPS Finest]: 2008.04.09 09:06:39.893--ServerSession(23543153)--Thread(Thread[DeployerRunnable Thread for jpaELTestEAR,9,SystemThreadGroup])--Begin predeploying Persistence Unit statJPAJ2EE; state Initial; factoryCount 0
[EL Finer]: 2008.04.09 09:06:39.940--ServerSession(23543153)--Thread(Thread[DeployerRunnable Thread for jpaELTestEAR,9,SystemThreadGroup])--Found a default mapping file at file:/C:/opt/oc4j11samba/j2ee/home/applications/jpaELTestEAR/jpaELTestWeb/WEB-INF/classes/META-INF/orm.xml for root URL file:/C:/opt/oc4j11samba/j2ee/home/applications/jpaELTestEAR/jpaELTestWeb/WEB-INF/classes/
[EL Finer]: 2008.04.09 09:06:40.783--ServerSession(23543153)--Thread(Thread[DeployerRunnable Thread for jpaELTestEAR,9,SystemThreadGroup])--Class [org.eclipse.persistence.example.navigation.business.StatClass] registered to be processed by weaver.
[EL Finest]: 2008.04.09 09:06:40.783--ServerSession(23543153)--Thread(Thread[DeployerRunnable Thread for jpaELTestEAR,9,SystemThreadGroup])--End predeploying Persistence Unit statJPAJ2EE; state Predeployed; factoryCount 1
[EL Finest]: 2008.04.09 09:06:41.033--ServerSession(23543153)--Thread(Thread[DeployerRunnable Thread for jpaELTestEAR,9,SystemThreadGroup])--Begin weaver class transformer processing class [org/eclipse/persistence/example/navigation/business/StatClass].
[EL Finest]: 2008.04.09 09:06:41.079--ServerSession(23543153)--Thread(Thread[DeployerRunnable Thread for jpaELTestEAR,9,SystemThreadGroup])--End weaver class transformer processing class [org/eclipse/persistence/example/navigation/business/StatClass].
08/04/09 09:06:41 Application Deployer for jpaELTestEAR COMPLETES. Operation time: 2155 msecs

Perform a JPQL query

emf = Persistence.createEntityManagerFactory(puName);
entityManager = emf.createEntityManager();

Console Output

08/04/09 09:19:29 Action: init
[EL Finest]: 2008.04.09 09:19:29.634--ServerSession(2059288)--Thread(Thread[HTTPThreadGroup-1,9,HTTPThreadGroup])--Begin deploying Persistence Unit statJPAJ2EE; state Predeployed; factoryCount 2
[EPS Warning]: 2008.04.09 09:19:29.868--ServerSession(2059288)--Thread(Thread[HTTPThreadGroup-1,9,HTTPThreadGroup])--PersistenceUnitInfo statJPAJ2EE has transactionType RESOURCE_LOCAL and therefore jtaDataSource will be ignored
[EL Info]: 2008.04.09 09:19:29.884--ServerSession(2059288)--Thread(Thread[HTTPThreadGroup-1,9,HTTPThreadGroup])--EclipseLink, version: Eclipse Persistence Services - 1.0 (Build SNAPSHOT - 20080403)
[EL Config]: 2008.04.09 09:19:30.289--ServerSession(2059288)--Connection(17254324)--Thread(Thread[HTTPThreadGroup-1,9,HTTPThreadGroup])--connecting(DatabaseLogin(
	user name=> "stat"
	connector=>JNDIConnector datasource name=>null
[EL Config]: 2008.04.09 09:19:30.289--ServerSession(2059288)--Connection(16022259)--Thread(Thread[HTTPThreadGroup-1,9,HTTPThreadGroup])--Connected: jdbc:oracle:thin:@//
	User: STAT
	Database: Oracle  Version: Oracle Database 11g Release - Production
	Driver: Oracle JDBC driver  Version:
[EL Finest]: 2008.04.09 09:19:30.289--ServerSession(2059288)--Thread(Thread[HTTPThreadGroup-1,9,HTTPThreadGroup])--sequencing connected, state is Preallocation_NoTransaction_State
[EL Finest]: 2008.04.09 09:19:30.289--ServerSession(2059288)--Thread(Thread[HTTPThreadGroup-1,9,HTTPThreadGroup])--sequence STAT_CLASS_SEQ_GENERATOR: preallocation size 25
[EL Info]: 2008.04.09 09:19:30.336--ServerSession(2059288)--Thread(Thread[HTTPThreadGroup-1,9,HTTPThreadGroup])--file:/C:/opt/oc4j11samba/j2ee/home/applications/jpaELTestEAR/jpaELTestWeb/WEB-INF/classes/-statJPAJ2EE login successful
[EL Finest]: 2008.04.09 09:19:30.336--ServerSession(2059288)--Thread(Thread[HTTPThreadGroup-1,9,HTTPThreadGroup])--End deploying Persistence Unit statJPAJ2EE; state Deployed; factoryCount 2
  • Exercise your application in a browser by requesting a JPQL query
    • Launch<100

Browser Output

Eclipselink example jpa oc4j web jpql action cap.jpg