Getting Started using Apache OpenJPA

Few weeks ago we were required to learn an Object Relational Mapping (ORM) concept in our Introduction to Database Management System course. The ORM our professor wanted us to use is Apache OpenJPA. Not really sure what was the reason he chose Apache OpenJPA over JBoss Hibernate that is more commonly used in the industry.

Although both Hibernate and OpenJPA are JPA compliant, which means that they follow the JPA standards that were set by Java, tutorials and discussion of OpenJPA is a lot fewer than of Hibernate. This means that whenever we encounter trouble with OpenJPA, the answer is not always there.

What makes it even a bit worse is that even getting started with OpenJPA is not that easy. So just in case any of you have problem with it. This is my notes and tutorial of how to kickstart using OpenJPA with Eclipse.

My Configuration

Just in case you are curious about the software versions I used in this tutorial, they are:

  • Mac OS X Snow Leopard
  • Java 6.0
  • MySQL 5.1
  • Eclipse Helios J2EE
  • Apache OpenJPA 2.01
  • MySQL Connector 5.1.13


A. Setting up the Project

1. Create new Java Project on Eclipse Workbench (ex. Getting-Started-OpenJPA)
2. Right click the Project > Properties
3. Go to Build Path > Add External JARs
4. Add the MySQL connector jar file
5. Repeat for the OpenJPA*

*There are two main jar files in the OpenJPA binary distribution zip file. The easiest one to choose is the openjpa-all-2.0.1.jar because it will include all needed jar files to run OpenJPA. If you choose the openjpa-2.0.1.jar you will need to add some other jar files in the lib directory.

B. Creating the Entity

1. Create a new package in the Project you created above. (ex. com.djitz.model)
2. Create a new class (ex. Patient)
3. Add an attribute (ex. String name)
4. Add getter and setter
5. Add empty constructor and a constructor with String name as parameter

6. Add @Entity on top of class name (public class Patient).
7. Add @Column on top of name attribute (private String name).

C. Create the Database

1. Create a new database (ex. CREATE DATABASE getstart_openjpa)

D. Create the persistence.xml

1. Right click on src directory in your project > New > Folder
2. Create a new directory labeled META-INF
3. Right click on the META-INF directory > New > Other
4. Choose XML file
5. Give the new file name persistence.xml
6. Copy the following to the file:

<persistence xmlns=""
xmlns:xsi="" version="1.0">

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

<property name="openjpa.ConnectionUserName" value="root" />
<property name="openjpa.ConnectionPassword" value="" />
<property name="openjpa.ConnectionURL" value="jdbc:mysql://"/>
<property name="openjpa.ConnectionDriverName" value="com.mysql.jdbc.Driver" />
<property name="openjpa.jdbc.SynchronizeMappings" value="buildSchema" />
<property name="openjpa.Log" value="SQL=TRACE" />
<property name="openjpa.ConnectionFactoryProperties" value="printParameters=true" />
<property name="openjpa.jdbc.MappingDefaults"
JoinForeignKeyDeleteAction=restrict" />


*I believe some of the xml contents are self-explanatory.

<class> is for the entity class we have.

<properties> are for some database connection properties and logging

These are some of the minimal configuration that it needs to run, if you need some more specific configuration to add, you can refer to OpenJPA documentation on the configuration here.

E. Create the application runner

1. Create a new package (ex.
2. Create a new Class (ex. with a public static void main function.
3. Copy and paste the following into the main function:

java.util.Map<Object,Object> map = new java.util.HashMap<Object,Object>();
EntityManagerFactory factory = Persistence.createEntityManagerFactory("getstarted", map);
EntityManager em = factory.createEntityManager();
// we'll put some codes here later

4. Run the Main class (right click the > Run As > Java Application).

If you followed everything correctly, you will see that OpenJPA creates the Patient table automatically. However, it will throw an Exception afterwards, and it goes like:

Exception in thread "main" <openjpa-2.0.1-r422266:989424 nonfatal user error> org.apache.openjpa.persistence.ArgumentException: This configuration disallows runtime optimization, but the following listed types were not enhanced at build time or at class load time with a javaagent: "com.djitz.model.Patient".

This happens because the OpenJPA fails to run enhanced the entity file ( we created. What the OpenJPA (and also Hibernate) does is putting some more code in our Patient class after it is compiled. These code lines enable the OpenJPA to do some “magic”.

Now we need to add some lines on the run configuration to apply this enhancement.

F. Add run configuration for Enhancement

1. Right click the Main class > Run As > Run configurations
2. Open the “Arguments” tab
3. Paste the following in the VM arguments box:


4. Re-run the, there should be no error by now.

Adding a record

1. Add the following lines between the em.getTransaction.begin() and em.getTransaction.commit():

Patient newpatient = new Patient("djito");

2. Run the, you will see it inserts a new record into Patient table with name = ‘djito’.

Deleting a record

1. Add the following lines between the em.getTransaction.begin() and em.getTransaction.commit():

Query q = em.createQuery(
"SELECT p " +
"FROM Patient p " +
"WHERE = 'djito'");
Patient deletepatient = (Patient)q.getSingleResult();

2. Run the, you will see it delete the record from Patient table with name = ‘djito’.


Congratulations, you have successfully setup OpenJPA using Eclipse. This is a very simple OpenJPA configuration. Depending on your need, you may want to set some more advanced annotations for the entity classes.

If you have any question, shoot me an email or put your comment down here. I’ll try to answer them the best I can. :D

Popularity: 18% [?]

Tags: , ,

Related Posts


#1 Varun on 12.12.10 at 3:47 pm

Well explained. Gr8.

#2 djitz on 12.12.10 at 6:00 pm

Thanks man! :D
I find your notes very useful also.

#3 Parvathy on 12.14.10 at 1:59 pm

Good Work Djito!..:)

#4 djitz on 12.14.10 at 8:12 pm

Thanks Parvathy! :D

#5 shiv sachan on 12.24.10 at 12:02 am

well explained serializibility and its types.

#6 djitz on 01.03.11 at 10:16 pm

thanks for the compliment shiv! :D

#7 Karthi on 03.30.11 at 12:46 am

Very very useful for OpenJPA beginners! Thanks djitz

#8 Rob on 05.16.11 at 9:32 am

thanks, just what I needed to get started! This needs to be on the OpenJPA site!

#9 djitz on 05.21.11 at 4:45 pm

@Rob, glad you found it helpful for you! :D

#10 Aristide on 12.01.11 at 1:59 pm

thank you! it very cool

Leave a Comment