2) Either create a new 10.1.3 server in Eclipse and deploy your EAR there, or deploy your EAR manually via the EM console.

Document History

Date

Author

Version Description & Notes

20080414

Michael O'Brien

Initial version covering Oracle OC4J 10.1.3.4 and 11.1.1.0

20090217

Michael O'Brien

Updated for version 10.1.3.5 - completed 20090226

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 will be available online at the following locations. These 3 projects must be imported along with the jpa core eclipselink project.

Prerequisites

Install Eclipse

I installed a clean version of Eclipse Ganymede EE SR1 Version: 3.4.1 Build id: M20080911-1700 with all of WTP 3.0

Install a Database

In this example I am using Oracle 11g, the table schemas have already been created either manually or using DDL generation in the SE example. All entity java classes have been generated using the Eclipse DALI tool.

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_ROOT/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

The OC4J 10.1.3 release does not ship with the EclipseLink JPA provider - you will need to modify or create a shared library to pick up the jars.

There are 2 jar files required to run the EclipseLink provider on OC4J - eclipselink.jar and a version of the JPA 1.0 specification jar - currently javax.persistence_*.jar

Downloading EclipseLink Libraries

Download EclipseLink using HTTP - recommended

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

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 2: Modify an existing shared-library - not recommended

The following step replaces the default TopLink Essentials JPA library with the EclipseLink provider - this is the fastest but not recommended configuration modification. It would be better to create a new EclipseLink shared library.

As of OC4J Server 10.1.3+ the TopLink Essentials library is shipped in the following location on the server - we will replace the jar references to this library with EclipseLink versions.

$OC4J_ROOT/toplink/jlib/toplink.jar

Copy EclipseLink jars to new shared-library folder

Create a new eclipselink directory off of $OC4J_ROOT at the same level as the existing toplink directory.

$OC4J_ROOT/eclipselink/eclipselink.jar

$OC4J_ROOT/eclipselink/javax.persistence_*.jar

Modify server.xml

Edit $OC4J_ROOT/config/server.xml and edit the following shared-library "code-source" elements in oracle.persistence.

This approach will not allow you to easily version different distributions of EclipseLink - like you are able to using a shared-library via the version tag, in option 1.

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.

Linking source to binaries and debugging EclipseLink - optional step

Developers may want to debug EclipseLink, the EclipseLink nightly build compiles a debug ready jar using the following debug parameters in build.properties.

javac.debug=true
javac.debuglevel=lines,vars,source

The following file available at the SVN trunk can be used to view EclipseLink source in an IDE - you will want to place this jar into your new 'eclipselink shared-library folder.

eclipselink-src.zip

JDBC JAR location

There is an existing Oracle jdbc driver in OC4J_ROOT/../jdbc/lib/orai18n.jar that is referenced by the existing toplink shared library and if you follow option 1 will be referenced by the new eclipselink shared library.

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.3.5).
The only default you may need to change is the admin user from oc4jadmin to fmwadmin.

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 required.

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 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 when using a stateless session bean - 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.

Persistence.xml

JTA Datasource

Note: Your <jta-data-source> or <non-jta-data-source> element in persistence.xml must match the JNDI Name: on the server admin page Home >Summary of JDBC Data Sources - either prefixed with jdbc/ or not.

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.