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

Using TopLink projects through JPA

I started writing a response to a comment on my blog about accessing the underlying ServerSession in TopLink Essentials and decided that the question warranted it's own blog entry.

In his comment, Bruno said:
"I'm trying to do the reverse of what you explained here. I want to be able to obtain an EntityManager from an existing ServerSession. My application configures the ServerSession directly, and all the descriptors are configured in code. I now want to be able to use the JPA interfaces for data access, but defer migrating all the mappings until some time later. Can this be done with TopLink 10.1.3.1? It looks like we need to add the toplink-essentials.jar just to get the actual JPA code, but this all depends on the package oracle.toplink.essentials, while we still have many dependencies on the original package path."

Mixing Oracle TopLink classes with TopLink Essentials JPA isn't really possible--you need to choose one or the other. If you're interested in using the spec compliant JPA programmer API then you should use Essentials. The next release of Oracle TopLink will be spec compliant and offer access to advanced TopLink features. A preview of the JPA compliant Oracle TopLink will be available around JavaOne, the second week of May.

In the meantime, if you can't wait, you can bring your hand coded TopLink Project and Descriptors to TopLink Essentials. The process involves replacing toplink.jar on your classpath with toplink-essentials.jar and changing the package imports in your Project to use the TLE classes instead of the Oracle TopLink ones. Once your code is compiling, you can create a ServerSession and wrap it in an EntityManagerFactory.

Project project = new MyProject();
final ServerSession serverSession = new ServerSession(project);
EntityManagerFactory emf = new EntityManagerFactoryImpl(serverSession);
EntityManager em = emf.createEntityManager();

Now you can use all the features of JPA including JPQL.

public void test() throws Exception {
 
 Project project = new MyProject();
 final ServerSession serverSession = new ServerSession(project);
 EntityManagerFactory emf = new EntityManagerFactoryImpl(serverSession);
 EntityManager em = emf.createEntityManager();
  
 em.getTransaction().begin();
 em.createQuery("Delete from A").executeUpdate();
 A a = new A();
 a.setId(1l);
 em.persist(a);
 em.getTransaction().commit();
  
 List <A> results = em
  .createQuery("select a from A a")
  .getResultList();
  
 for (A eachA : results) {
  System.out.println(eachA);
 }
 serverSession.logout();
}

Pretty cool!

--Shaun

EclipseLink Project Declared

The Eclipse Java Persistence Platform Project (nicknamed EclipseLink) was "declared" today--which is Eclipse-speak for posting the initial project proposal and sending out an announcement to the Eclipse membership.

Along with the declaration, the eclipse.technology.eclipselink newsgroup was created to discuss all things EclipseLink. You'll need to get a user id/password to access the newsgroups but this isn't much of a hassle and keeps out the spam. You can access the newsgroup via your news reader or through the Eclipse News Portal.

The project is now in the Proposal Phase where the proposal is discussed and refined. The end of the Proposal Phase is the Creation Review where the merits of the project, as described in the proposal, are discussed and a decision is made as to whether it should proceed. If you have any ideas or comments that would improve the proposal or any questions about it please post to the newsgroup and get involved!

--Shaun

Oracle Open Sources TopLink!

Today at EclipseCon in Santa Clara, Oracle (my employer) announced that it would open source Oracle TopLink (for which I’m a product manager) as part of the proposal of the Eclipse Persistence Platform project (nicknamed “EclipseLink”).

This is big news! All the advanced features of TopLink will be available in open source for use by Java developers building any kind of Java application. Everything will be open sourced except for Oracle Application Server specific integration code that, frankly, isn’t useful to anyone outside Oracle—it’s glue code. Along with the existing ORM/JPA, OXM/JAXB, and EIS support, a number of new features that are being developed for the next release of TopLink will now make their debut in open source including:

• Service Data Objects (SDO) implementation and SDO Data Access Service (DAS) that leverages JPA for use with SDO.
• XR (XML-Relational) that provides a completely metadata driven approach to obtaining relational data as XML.
• DBWS which exposes XR as a web service. With DBWS, you can easily build web services that access relational data without any programming.

For details check out the press release and the FAQ.

More on this later! I’m at EclipseCon this week and it’ll be interesting to see how this news and the EclipseLink proposal are received!

--Shaun

TopLink and Dali at EclipseCon 2007

EclipseCon runs from March 5th to 8th this year and I'm involved with a number of sessions relating to Dali and TopLink. If you'll be there I hope you'll consider checking them out.

The first is a short tutorial on Dali on Monday at 10:30. Neil Hauge, my co-lead on Dali will be co-presenting. It'll involve some hands on so bring a laptop. The tutorial number and title is (3633) Building applications with WTP - Java Persistence API (JPA).

If you can't make the tutorial but want to find out more about Dali, Neil and I will be giving the demo session the Dali Java Persistence API Tools Project on Wednesday at 14:30.

On a non-Dali topic, I'll be co-presenting with Stephan Eberle of Bosch a demo session entitled Integrating EMF with JPA--Enabling Enterprise Data Access for RCP Applications where we'll describe and demo the results of our collaboration. That's scheduled for Wednesday at 16:30.

Hope to see you there!

--Shaun

Read-Only JPA Entities

This came up on the TopLink Forum last week but for those who don't read all the postings I thought I'd repeat the information here.

The question was whether it's possible to have read-only Entities in JPA. This isn't in the spec but is possible in TopLink Essentials. You do it by calling the setReadOnly() method on an Entity's TopLink descriptor. One way to do this is through a descriptor customizer.

For example, in persistence.xml:

<property
  name="toplink.descriptor.customizer.Title"
  value="comics.toplink.TitleCustomizer"/>


And a definition of TitleCustomizer implementing oracle.toplink.essentials.tools.sessionconfiguration.DescriptorCustomizer.

public class TitleCustomizer implements DescriptorCustomizer {
 
 public void customize(ClassDescriptor desc) throws Exception {
  desc.setReadOnly();
 }
}

The semantics of read-only are that any changes you make to an object will not be written to the database, but you are not prevented from making changes.

--Shaun

Accessing the Session in TopLink Essentials

Although TopLink Essentials is the reference implementation for JPA, it was derived from Oracle TopLink and therefore shares the same core concepts and classes. Recently I was writing some (admittedly bizarre) JPA code and wanted to verify what was in the shared cache. Of course there's no way to look in the TopLink shared cache using JPA so I needed to use the TopLink API. Fortuately, it's still there if you need it.

To obtain a reference to a session in TopLink Essentials(as in Oracle TopLink) you use the SessionManager. Once you have the session you need, you can use it as you would in Oracle TopLink:


Session session = SessionManager.getManager().getSession("library");
List books = session.readAllObjects(BookImpl.class);
assertEquals("num books", 1, books.size());


The "library" session is the TopLink object underlying the JPA "library" persistence unit as defined in my persistence.xml. But, to make the library session available through the SessionManager you have to add a property to your persistence unit:


<?xml version="1.0" encoding="UTF-8"?>
<persistence>
  <persistence-unit name="library">
    <properties>
      <property name="toplink.session-name" value="library">
...


By adding this declaration you're effectively publishing your "library" persistence unit under a session name of "library". You could publish your persistence unit under a different session name but why confuse matters.

You have to start sometime...

Like many before me here I am posting my first blog entry. This day had to come eventually ;-).

I'm going to be blogging on TopLink related topics--both Oracle TopLink and the open source TopLink Essentials--as well as on the Java Persistence API (JPA) in general. I'll also share news about the Eclipse Dali JPA Tools project which I'm involved with. Dali's heading for 1.0 in June as part of the Eclipse Europa release so there's lots of work going on there.

I'd created this account a few days ago and was looking for a topic for my first blog but before I found it I read an interesting blog by Mike Milinkovich on the recent announcement of people named ACM Distinguished Engineers and thought I'd add a comment. And when I did, it linked my comments to my blog--and it was as yet blank. So here I am. Hopefully subsequent entries will be more substantial.

--Shaun