Tuesday, May 1, 2007

Using JPA with TopLink 11g Metadata

I've previously blogged about using JPA with TopLink 10.1.3.1 but things are much easier in the upcoming TopLink 11 release--which you can check out now in the TopLink 11 Preview.

Here's the scenario a lot of current TopLink users are faced with:
  • used the TopLink Workbench to define their mapping metadata,

  • would like to get started with JPA,

  • don't want to remap everything.

So what do you do? Well, in TopLink 11 you can use the full JPA including JPQL with projects mapped using TopLink meta-data--and it's easy. You can easily get an EntityManager for a session defined in a sessions.xml. Let's look at an example.

Example


The example has a deployment xml file called "comics.xml" (produced by the Workbench), a sessions.xml with a session named "comics" associated with comics.xml, and a persistence.xml--all in my META-INF folder. The sessions.xml and deployment xml are standard TopLink and I can use the SessionFactory to obtain a "comics" session and work with my classes through the TopLink API. The JUnit testcase comics.test.TestTopLinkORM demonstrates this.

Using JPA


To get an EntityManager for the comics session you just need couple of things in your persistence.xml. Here's what's in the example:

<persistence-unit name="comics" transaction-type="RESOURCE_LOCAL">


<properties>
<property name="toplink.sessions-xml" value="META-INF/sessions.xml"/>
<property name="toplink.session-name" value="comics"/>


You simply identify the session ("comics") you want associated with the persistence unit ("comics") and the sessions.xml file with that session. Note that the name of the persistence unit and the session do not have to be the same. But to make it easier to keep things straight, I've kept them the same. The JUnit testcase comics.test.TestTopLinkJPA demonstrates how to use the session through JPA. You'll note that the test contains no TopLink API calls--just spec compliant JPA and JPQL.

You create an EntityManagerFactory for the persistence unit as you normally would:

Persistence.createEntityManagerFactory("comics");

and go from there.

Consequences


There are some interesting consequences of using JPA with TopLink metadata.

JPA semantics apply when you use JPA. Makes sense, but you might be surprised by a few things. For example, in TopLink, there's persistence by reachability. That is, if you register an object then associated mapped objects will also be persisted. This is not true in JPA unless you've setup cascade=PERSIST on the relationship.

Getting the Example


You can get the example here. Download it, try it out, change it. Experiment! The example is an Eclipse 3.2 project. If you want to import the project into your Eclipse workspace you'll need to define a couple of Libraries: TOPLINK_11 and ORACLE_JDBC. The contents of those libraries are illustrated by the screen shot libraries.jpg in the setup folder.

The database folder contains SQL scripts for dropping and creating the schema for Oracle DB but if you want to work with another database just change your login info in the session.xml and define the toplink.ddl-generation property in the persistence.xml. It's there but commented out for your convenience ;-).

--Shaun