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.

Tutorial Source

The EAR, EJB and WEB Eclipse project source for this EclipseLink OC4J tutorial are available online at the following locations. These 3 projects must be imported along with the jpa core eclipselink project.

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 127.0.0.1 if your database server is on another machine, the user, password and schema name orcl.

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.3.5 / 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

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.

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%

javax.persistence.jar

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.

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.

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.

UML Data Model

The following single entity Cell has a @ManyToMany bidirectional relationship to itself.

Tutorial Design

The goal of the tutorial is to demonstrate a quick start end-to-end deployment on a specific application server of an EclipseLink JPA application.
To accomplish this...

The web framework is a simple servlet so we avoid container specific issues around JSF implementation.

The data model is very simple (@ManyToMany) - as the other tutorials get into more advanced JPA entity concepts and annoations

The entitymanager is container managed where possible by injection

The schema is generated by DDL generation in a separate common application

managed SE app.

The application context name is standard across servers

The datasource is globally defined (by the user) on the server - with the only configuration setting being the jta-data-source element in persistence.xml

DDL/Schema Generation

The database schema for this example can be automatically generated using the DDL generation capability of EclipseLink (normally only used by development or for demos). The following project in SVN can be run as an application managed stand-alone JPA project that has ddl-generation turned on in the persistence.xml.

Note: DDL Generation is not possible on a container managed entity manager connected to a JTA datasource - hence the use of a separate project that is server agnostic and sharable by all the JPA Web application tutorials in this section of the Wiki.

Browser Output

The following screen capture of this quickstart JEE OC4J JPA application shows a visual representation of the entities persisted to the Oracle database using the EclipseLink JPA implementation on Oracle OC4J Server 10.1.3.5.