Companion Notes on
the Java Persistence API
and using EclipseLink
with Apache Derby

Russell Bateman
last update: 27 September 2010

Similarly to the decision I took on re-inventing a tutorial on Eclipse Data Tools Platform (DTP), i.e.: not duplicating someone else's already capable efforts, I decided to follow one on this topic that Lars Vogel has done. There are very few comments to be made. Pick up and begin Lars' tutorial at

I make notes by section number only where I have a comment to make. However, I do make some rather important contributions to the original tutorial in my comments.

What is the Java Persistence API?

First, simply put, persistence is the storage of state between application instances. If you run an application, state mostly in the form of data exists, modified by what the application may do, and sometimes by user interaction. When that application ceases to run, that state is lost unless persisted. The Java Persistence API (JPA) is a light framework for accomplishing this Java.

JPA handles data persistence without having by hand to write code to instantiate (and initialize) a (schema) bean or dredge the bean for creating SQL UPDATE statements.

(Another possible way of doing this, lighter than JPA, is to use XStream and the filesystem, but that's a topic for another day.)

The JPA solution consists primarily of four components:

  1. Solution JARs; ours are from EclipseLink (the persistence mechanism and "reference implementation" for JPA) and Apache Derby (the database to put state into). The Derby database is not the only choice, but MySQL, PostgreSQL, and still others are possible.
  3. The metadata or persistence-configuration file; here, persistence.xml.
  5. Schema beans; here, Family, Job and Person classes. These are "plain old Java objects" (POJOs).
  7. Annotations that mark up the POJOs for role information used by the framework:

    Getter/setter annotations The fields of the "entity" (the bean class that will become a table) are saved in the database. JPA can use either the instance variables (fields) themselves or their corresponding getters and setters for access the fields, but not both.

    Note: Hibernate uses the getters and setters; we're going to do that too here. It's probably a "best practice".

    To use the setter and getter methods the class must follow Java bean naming convention. By default, JPA persists all fields of an entity. If fields are not to be saved (i.e.: are transient, of unreliable or irrelevant value) they must be marked so.
    @Id Identifies the unique ID of the database entry
    @GeneratedValue Together with ID defines that this value is generated automatically
    @Transient Field will not be saved in database
    Relationship mapping JPA allows the definition of relationships between classes, e.g. a class can be defined as being part of another (containment). Classes can have one-to-one, one-to-many, many-to-one and many-to-mant relationships with other classes.

    Relationships can be bi- or uni-directional. In a bi-directional relationship both classes store a (foreign table) reference to each other. In a uni-directional relationship only one class has a such a reference (to the other class). Within a bi-directional relationship the owning side of this relationship must be specified using the "mappedBy" attribute (as seen in the code of this project).

Cautionary note: versioning POJOs

If you're paying attention, you've already figured out that elements of this solution are cast in concrete when it comes to making schema changes subsequent to releasing any version of your application. Be therefore wary! Solutions to this problem include versioning POJOs, maybe under different names. This isn't covered in this tutorial. In fact, as nearly as I can tell, this isn't provided for in JPA at all.

Finding @Version in a POJO

Now, you may stumble upon JPA 2.0 annotation, @Version.

Sadly, this will not magically obviate the need to handle modifications made to a POJO subsequent to releasing your application. It has nothing to do with that at all, but it's a locking mechanism.

The SQL (underneath in JPA) generated to deal with the field thus marked is as below. Assume that a new field, @Version private int version; has been added just after private String id; in this tutorial's This will generate:

UPDATE Person SET ..., version = version + 1 WHERE id = ? AND version = readVersion

This bumps the version field at the time of update. The code is generated based on the presences of the annotation in your code. So, what this does is allow your application to version or count instances, but not in the sense that the different instances correspond or not to substantial schema additions to your POJO code (added, subtracted or renamed fields).

What does this accomplish you ask? It is a locking mechanism by which your code can sort out problems arising from concurrent access to your application's persistence solution. It allows persistence transactions to proceed simultaneously, but detects and prevents collisions. Any thread can read and update a persisted entity (the contents of a POJO), but an exception is thrown if the version field has been updated since the entity was last read.

2. Installation

I installed EclipseLink 2.1.0 and Apache Derby The exact JARs I ended up installing were:

Oddly, I didn't seem to have to do anything to get Derby working. I did not configure it, so what's in persistence.xml magically works for username and password are null-length. Like Lars, I leave this configuration (and the instantiation of an actual file in the filesystem) as an exercise to the user. The tutorial links to a Derby tutorial to help accomplish this.

3.1. Data model

If you're actually planning on using JPA, EclipseLink and Derby in any real project, you'll want to learn to set up a User Library instead of creating the lib subdirectory the way the tutorial shows. See JARs and Eclipse Build Path: Appendix D: Setting up a third-party library: a practical example.

3.2. Persistence Unit

I added some comments to the persistence configuration file that I think are helpful. A big difference between what I did and what he did is perhaps the version of EclipseLink use. The later one I used seemed to encourage using javax.persistence; there was no persistence.jar in the distro.

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="1.0"

  <persistence-unit name="people">




        <!-- Note: The tutorial said to use "eclipselink.jdbc.driver (user, password, etc.), but EclipseLink
            now ships with javax.persistence_1.0.0.jar (instead of persistence.jar?) and you get complaints in
            Console about it. Use "javax.persistence" in place of "eclipselink".
        <property name="javax.persistence.jdbc.driver" value="org.apache.derby.jdbc.EmbeddedDriver" />
        <property name="javax.persistence.jdbc.url" value="jdbc:derby:C:/DerbyDatabases/hellojpa-database8;create=true" />

        <!-- I work in this example without user / password -->
        <property name="javax.persistence.jdbc.user" value="" />
        <property name="javax.persistence.jdbc.password" value="" />

        <!-- EclipseLink should create the database schema automatically -->
        <property name="eclipselink.ddl-generation" value="drop-and-create-tables" />
        <!-- To see the SQL generated for the the databases set eclipselink.ddl-generation.output-mode value
            from "database" to "sql-script" or "both". Two files will get generated "createDDL.jdbc" and
            "dropDDL.jdbc". These are very useful.

            <property name="eclipselink.ddl-generation.output-mode" value="database" /> -->
        <property name="eclipselink.ddl-generation.output-mode" value="both" />

    <!-- I got output saying: "[EL Warning]: 2010-09-27 10:21:52.521--ServerSession(9688764)
        --Exception [EclipseLink-4002] (Eclipse Persistence Services - 2.1.1.v20100817-r8050):
        Internal Exception: java.sql.SQLException: Table/View 'SEQUENCE' already exists in Schema 'APP'.
        Error Code: 30000"

        I noted that a) table SEQUENCE isn't dropped, probably because it's frequently used in the same database
        by others and not just this project, and b) it's a row that's inserted this table that belongs to this
        project and that's deleted--not the whole table. Hence the non-fatal error (that doesn't prohibit the
        example from working).

3.3. Entity Manager

Somewhat unstated, you'll want to add the JUnit 4 JARs (via Build Path) to your project (rather than JUnit 3 if you're only familiar with that).

6. Appendix: Using JPA with XML metadata

The utility of this discussion is to show you how to to use JPA in Java 1.4—before annotations were introduced (in Java 5). This is done using an XML file, orm.xml to specify all the information that was otherwise specified in the POJOs via annotation. Confusingly, the tutorial leaves annotations in the Java code, but you should not (indeed you cannot) have to do that if you're using Java 1.4.

XML files is how how complication configuration was done for JPA, JAX, Spring and many other framework technologies prior to the introdution of annotations in Java 5.