Java Persistence Lab

Page 1

Java Persistence Architecture

Java Persistence Architecture (JPA) is a specification for how to persist objects. It provides a standard API and set of services. JPA provides services for saving objects, associations, and inheritance relationships in a database, in a way that is independent of the database and the implementation of JPA. When objects are persisted to a database, or recreated from a database, JPA can save/restore associated objects, and guarantee object uniqueness. JPA version 2 can be used in two contexts: in an enterprise application (JavaEE) that runs in a container, or as part of a stand-alone application using Java SE. JPA is only one choice for object persistence. Other choices are Java Data Objects (JDO), which has a broader scope, and object-relational mapping (ORM) frameworks such as Hibernate. Hibernate provides the basis for many JPA features (such as criteria queries) and itself now implements JPA. Knowing JPA is useful because it is so widely used (Google App Engine supports JPA), and the concepts can be applied to learning JDO, Hibernate, or other frameworks. This lab covers the basics of JPA 2.0 in a stand-alone Java SE application.

Required Software
1. Java SE 1.6.0 SDK (version 1.5 should work as well). 2. MySQL or Derby database. 3. EclipseLink 2.x, an implementation of JPA 2.0. 4. Eclipse or NetBeans. Eclipse Helios and Indigo have good support for JPA, NetBeans 7 has reasonable support. These are not essential: you use JPA with any Java development tools. See end of this document for help installing this software.

The World Database

World is a sample database provided by MySQL. The data is from the 1990s, but it's still useful. There are 3 tables as shown below. It's not a great database design: the Continent attribute is an enumeration of Strings, the Region is a String, and Language is a String. COUNTRY table Code Capital Code2 Continent GNP LifeExpectancy LocalName Name Population Region SurfaceArea CITY table ID CountryCode District Name Population

COUNTRYLANGUAGE CountryCode Language isOfficial Percentage

Java Persistence Lab

Page 2

1. Object Persistence Concepts

Object persistence means saving information about objects and their associations even after execution ends, e.g. to non-volatile storage. Persistence includes saving and updating objects and associations, searching for saved object data and recreating objects from storage, and guaranteeing that objects retain their uniqueness even after being saved and recreated. Persistence is a set of related responsibilities that isn't closely related to the "domain" logic of your application, and it's a service that's needed by many applications. Hence, it makes sense to implement persistence services as reusable software that can be used by many applications (a framework).

2. How JPA Works

The Java Persistence Architecture provides an abstraction that hides the details of saving, updating, querying, and deleting objects in persistence storage. An EntityManager provides services that your application uses to query, save, update, or delete persistent objects, called entities. EntityManager is just an interface. A concrete EntityManager is provided by an implementation of JPA, called a Persistence Provider. JPA provides an Entity Manager Factory that creates a concrete instance of EntityManager based on configuration data. The architecture looks similar to the way JDBC DriverManager creates a Connection object from a url. In this lab, we'll use EclipseLink as the persistence provider. Other providers are Hibernate, OpenJPA, TopLink Essentials, and DataNucleus.

Persistent Storage

The Java code for the above sequence is:

final String PERSISTENCE_UNIT = "world"; // name as in persistence.xml factory = Persistence.createEntityManagerFactory(PERSISTENCE_UNIT); EntityManager em = factory.createEntityManager(); Query query = em.createQuery( "SELECT c FROM City c WHERE c.name='Bangkok'" ); List<City> results = query.getResultList(); System.out.printf("Found %d cities.\n", cities.size()); for( City city: results ) System.out.println( city );

Java Persistence Lab

Page 3

EntityManager provides persistence operations such as find(...), persist(Entity), and remove(Entity). The createQuery method uses a String in Java Persistence Query Language (JPQL): SELECT c FROM City c WHERE c.name = 'Bangkok' This looks like SQL but is written in terms of classes and attributes, not tables. "City c" means a City object c, like in Java. The query returns objects (entities), as shown in the query.getResultList( ).

3. JPA Basics
In JPA, a class whose objects are persisted is called an Entity. An entity class is mapped to one or more tables in a database. In some frameworks objects can also be persisted to other forms of storage, including XML files, LDAP directory, or even an Excel spreadsheet. You have to describe the Entities to JPA, such as what attribute is the primary key, what attributes to save/restore, and associations with other objects. There are two ways to describe entities: annotations added to source code XML mapping file containing the same information, but in XML Both ways have advantages and disadvantages. You will use both in this lab.

4. Structure of a Java JPA Project

For a project named "WorldJPA" the structure will look like this:
WorldJPA/ src/ META-INF/ persistence.xml orm.xml world / domain/ bin/ ... Referenced Libraries/ eclipselink.jar javax.persistence_2.xxx.jar mysql-connector-java-5.1.7.jar the project base directory source directory meta-information directory JPA configuration file O-R mapping file (optional) base package for our source code package for domain objects generated class files. The name may be "build/classes" or other. JPA 2.x provider (EclipseLink) JPA API MySQL JDBC connector

Exercise: Create a Database Connection (Optional but Helpful)

Eclipse and Netbeans let you store information about database connections. If you do this, you can explore the database from within the IDE, and apply database connection parameters (url, user, password) to a new JPA project. The IDE can also generate Java code from database tables. NetBeans 7.0: 1. On the left side of workbench, click the Services tab. 2. Right click on Database and choose "New Connection" 3. Select a driver (Java DB (Embedded) is Derby). Change driver JAR if needed. 4. Click Next. Enter database URL, user name, and password. If your database doesn't require a user or password (e.g. Derby), use empty strings for user and password.

Java Persistence Lab 5. Test the connection and fix any problems. Eclipse Helios (with Eclipse Data Tools plugin):

Page 4

Eclipse Data Tools let you connect to a database and explore it. You can perform queries, edit schema, and create Java code from schema. The tools are part of the Eclipse JavaEE bundle, and may already be installed on your machine. If your Eclipse has a perspective named "Database Development" then the tools are already installed. If not, you can install them from the Eclipse update site. To create a database connection: 1. In Window -> View, open the "Database Source Explorer" view. Right click on "Database Connections" and choose New. 2. Choose connector type (MySQL, Derby, etc). Eclipse provides only the "profile" for connectors. You must supply a JDBC connector JAR for the database, or create/use a Library for it. Click Next. 3. Enter database name or url, user, and password. Test the connection. 4. Click Next to view summary. Note the database URL. Click Finish

Java Persistence Lab

Page 5

Exercise: Create a Project for World with JPA

Prerequisite: Install EclipseLink. It is convenient to create a library in the IDE. NetBeans 7.0 includes EclipseLink 2.2; NetBeans users can use that or (if you prefer) install a newer version of EclipseLink. You can use JPA in any Java Project You don't need to create a JPA project as described here, and you are not required to have the IDE's JPA plug-in. You can create the META-INF directory and the required files yourself (easier: copy them from another project). The plug-in makes it easier, but it is not required. To use JPA you need a JPA Provider such as EclipseLink. (See references for other JPA providers.) Eclipse: 1. If you have the Dali JPA extension installed, create a new "JPA Project" named WorldJPA. Eclipse will create the META-INF directory and persistence.xml. If you don't have JPA support, create a Java project. Then create a META-INF directory in your src directory. Inside META-INF, create a persistence.xml file using the example in this document. 2. Add the EclipseLink library or JARs (in directory eclipselink/jlib): to your project: eclipselink.jar javax.persistence_2.x.jar 3. Edit persistence.xml and verify that EclipseLink is the provider:
<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>

4. Add a JDBC driver to your project as a Library or external JAR. For MySQL, the JAR file is mysql-connector-java-5.x.x-bin.jar For Derby embedded server, the JAR is derby.jar

Eclipse Dali JPA Extensions Eclipse has two extensions for JPA: Dali Java Persistence Tools and Dali EclipseLink Support (optional). These extensions are not required to use JPA, but they can reduce typing. The extensions also enable you to generate Java code from database schema and to synchronize files in a JPA project. To install the Dali extensions in Eclipse Helios or Indigo: 1.Click Help Install New Software 2. In the "Work with" box select Helios (or Indigo if you use Eclipse Indigo). 3. Check the boxes for the Dali tools and click "Install".

Java Persistence Lab NetBeans 7.0 1. Create a new Java project named WorldJPA. Any name is OK, but don't use your JDBC project. 2. Create a persistence unit. Right click on the project and choose New Other Persistence and choose Persistence Unit. Click Next and enter a persistence unit name (usually the database name), Persistence Library (the persistence provider), and database connection. Choose "None" for table generation strategy. ("Create" means JPA will create the schema in a new database)

Page 6

Netbeans creates META-INF/persistence.xml (if this file exists, it adds a new persistence unit). 3. Verify that NetBeans added the EclipseLink jars (eclipselink-2.x.jar and javax.persistence-2.0.jar) to your project in the Libraries folder. If not (or if you want to use a newer version of EclipseLink) then add them to the project by right-clicking on the project's Libraries folder. 4. Add a JDBC driver for your database. Right click on the Libraries folder and choose Add JAR or Add Library (if you have a library for the driver). NetBeans includes JDBC libraries for some databases, or you can use your own. Check persistence.xml The persistence.xml that NetBeans creates may contain this line:
<property name="eclipselink.ddl-generation" value="create-tables"/>

For this lab we already have a database schema, so delete this line.

Java Persistence Lab

Page 7

4.1 The Persistence Configuration File: persistence.xml

JPA configuration information is in the file named persistence.xml. This file should be in a META-INF directory on your project source (src) folder. persistence.xml specifies persistence information specific to your project, shown in bold type:
<?xml version="1.0" encoding="UTF-8"?> <persistence version="2.0" xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"> <persistence-unit name="world" transaction-type="RESOURCE_LOCAL"> <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider> <class>world.domain.City</class> <properties> <property name="javax.persistence.jdbc.url" value="jdbc:mysql://se.cpe.ku.ac.th:3306/world"/> <property name="javax.persistence.jdbc.driver" value="com.mysql.jdbc.Driver"/> <property name="javax.persistence.jdbc.password" value="student"/> <property name="javax.persistence.jdbc.user" value="student"/> </properties> </persistence-unit> </persistence>

Note: In the xml header you can delete the long xsi:schemaLocation if you add eclipselink_orm_2_0.xsd to your IDE's Schema catalog, so the IDE can validate the XML. This avoids connecting to the Internet to get the schema. persistence version="2.0" (or newer). Make sure this is not 1.0. persistence-unit name="world" a persistence unit is a group of related entities. You can use any meaningful name; usually it is the database name. transaction-type="RESOURCE_LOCAL" for a stand-alone application. provider class is the implementation of JPA your are using. We are using EclipseLink. (zero or more times) are names of Entity classes.

properties JPA 2.0 specifies standard property names for URL, JDBC driver, user, and password. JPA providers can add optional properties, which don't begin with "javax.persistence". persistence.xml can specify more than one persistence-unit, each in its own section. It may also specify:
<mapping-file> (zero or more times) the name of a file containing object mapping info as XML.

This file is usually named orm.xml in the META-INF directory, but you can use any name and location. Some developers prefer to put it in the same source package as classes being mapped. <mapping-file>META-INF/orm.xml</mapping-file>

Java Persistence Lab

Page 8

5. Entity Classes
An entity class is a class whose objects are persisted. To be an Entity using JPA, a class must satisfy: 1. POJO rules: class has a non-private no-argument constructor (default constructor) get/set methods for persistent attributes, using Java standard naming convention 2. Class must not be final. Persisted variables and their get/set methods are not final, either. 3. Class must define an ID attribute that uniquely identifies each instance. This usually is the primary key of the table in a database. The ID can be a compound attribute. Both abstract and concrete classes can be entities. An entity class can extend another class. If an entity class will be used in a collection, then you should also specify: 4. Meaningful equals() and hashCode() methods. For persisted objects, the id attribute is a good choice. For transient (non-persisted) objects, the choice depends on your application.

5.1 Entities for the World Project

There are three tables in the World database, each of which will map to a Java class. For now, we'll define two entity classes: City id: Integer country: Country district: String name: String population: int country capital country table Code <<PK>> Capital <<FK>> Continent GNP LifeExpectancy Name Population Region SurfaceArea city table ID <<PK>> CountryCode District Name Population

Country code: String capital: City continent: String gnp: double lifeExpectancy:float name: String population: int region: String surfaceArea: float

Notice that City contains a reference to a Country object, whereas the city table contains a foreign key reference to a row in the country table. Similarly, a Country object contains a capital City reference, whereas the country table has a foreign key reference to a row in the city table.

Java Persistence Lab

Page 9

Exercise: Create the City class (without a Country)

Create a package named world.domain for our domain objects. Implement the City class. Don't include a country or countrycode attribute. Follow the rules for entity classes given above (a default constructor, get/set methods, equals using id). Write a toString().
package world.domain; public class City { private Integer id; private String name; private String district; private int population; /** required default constructor */ public City( ) { } //TODO write get/set methods and equals. //TODO write a toString

5.2 Define Entity Mapping for City using XML

Entity mapping tells JPA how to map object attributes to table columns. It be specified in XML or using Annotations in Java source code. XML mapping was used long before annotations and is still used by many frameworks. So, it is educational to learn XML mapping first. Edit persistence.xml to specify that world.domain.City is an entity class and specify the name of an XML mapping file. Add two lines to persistence.xml as shown in bold type:
<?xml version="1.0" encoding="UTF-8"?> <persistence version="2.0" xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"> <persistence-unit name="world" transaction-type="RESOURCE_LOCAL"> <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider> <mapping-file>META-INF/orm.xml</mapping-file> <class>world.domain.City</class> remainder of file as before

Next create an orm.xml file in the META-INF directory. orm.xml is where we define how to persist City objects. The xsi:schemaLocation string should be on one line.
<?xml version="1.0" encoding="UTF-8"?> <entity-mappings version="2.0" xmlns="http://java.sun.com/xml/ns/persistence/orm" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm http://java.sun.com/xml/ns/persistence/orm_2_0.xsd"> <entity class="world.domain.City" metadata-complete="true"> <attributes> <id name="id"> <column name="ID" nullable="false"/> <generated-value/> </id> <basic name="name"/>

Java Persistence Lab

<basic name="district"/> <basic name="population"/> </attributes> </entity> </entity-mapping>

Page 10

Each <entity> section specifies how to persist one entity class. The meta-data='true" is optional; it means that this file contains all the persistence info for City, so annotations in the City class (if any) are ignored. <attributes> define how to map attributes of City to columns in a database table. <id name="id"> declares the attribute id is a unique identifier for persisted objects. <column name="ID"> says that the id attribute maps to a column named ID in the database. This isn't required: JPA can automatically map attributes to columns when the names are the same ignoring case. <generated-value/> means that the database will generate the value of the id. <basic name="..."/> define an attribute that can be saved as a field in the database, using standard mapping between Java types and SQL types. <table name="CITY"/> we can specify the table name, but the default is a table with the same name as the class (JPA ignores case of letters to determine a matching table name). Since the column names are the same as the attribute names (except for case of letters), we don't have to specify them. We can, however, specify column names if we want.

5.3 Demo Program using JPA

We will write a program to find cities by name in the database, and print matches on the console. Here is an example run: Name of city to find: Bangkok Bangkok, Bangkok pop. 6,320,174 Name of city to find: Los Angeles Los Angeles, Bobo pop. 158,215 Los Angeles, California pop. 3,694,820 The code follows the sequence diagram in the section "How JPA Works". Create a JPADemo class in the world package. Our JPA code needs an EntityManagerFactory, so we will create a singleton accessor method for this:
package world; public class JPADemo { public static final String PERSISTENCE_UNIT = "world"; private static EntityManagerFactory factory = null;

public static EntityManagerFactory getFactory() { if (factory == null) factory = Persistence.createEntityManagerFactory(PERSISTENCE_UNIT); return factory; }

Persistence unit name must match the name in persistence.xml

Java Persistence Lab

Page 11

Next, write a findCity( ) method that finds cities by name. There may be more than one match, so this method should return a collection. We will use a List since the JPA Query methods returns a List.
/** Find cities with a given name. Returns all matching cities. */ public static List<City> findCity(String name) { EntityManager em = getFactory().createEntityManager(); Query query = em.createQuery("SELECT c FROM City c WHERE c.name= :name"); query.setParameter("name", name); List<City> cities = query.getResultList(); em.close(); return cities; }

This query string uses Java Persistence Query Language (JPQL). The :name is a named parameter . The query.setParameter(name, value) method inserts an actual value for the named parameter. This is similar to using ? in an SQL PreparedStatement, but safer since values are substituted by name. Write a citySearch() method to prompt user for city name, call findCity, and display the results. Invoke citySearch from the class's main method.
/** User interface for finding cities by name. */ public static void citySearch( ) { Scanner console = new Scanner(System.in); while(true) { System.out.print("Name of city to find: "); String name = console.nextLine().trim(); if (name.length() == 0) break; List<City> cities = findCity(name); for(City city: cities) showCity( city ); } } //TODO write a showCity( City ) method to print city information //TODO invoke citySearch from the class's main method.

Exercise: Run the program and correct any problems

Typically you will get exceptions the first few times you run a JPA program. Most exceptions are caused by configuration or typing errors, such as:

JDBC driver for your database not loaded. This could be due to forgetting to add the JAR file to the project, specifying the wrong driver class name in persistence.xml, or a mistake in the URL. For example: "jdbc.mysql://localhost/world" (should be jdbc:mysql). Can't connect to database because user or password is incorrect. If using Derby, a common problem is that a Derby database can have only one active connection. If you connected to Derby using some other tool (including the IDE's database browser), you must close that connection. Attribute name not consistent between Java source, orm.xml, and database field names. get/set method name doesn't match attribute name.

Note: the Exception output is usually very long. Start from the first exception and read down the list. Focus on (a) the Description of the exception, (b) the location. The first location inside your code is usually the cause.

Java Persistence Lab

Page 12

6. Entity Relationships
Objects usually contain references to other objects. A persistence framework needs to preserve these relationships. For example, a City refers to the Country it is part of. A Country has a reference to its capital City. There are 4 types of associations: One-to-one One-to-many Many-to-one Many-to-many In addition, relationships can be one-sided (unidirectional) or two-sided (bidirectional). One-sided: a Country has a reference to its capital City. Two-sided: a City refers to its Country, and the Country maintains a collection of its Cities.

6.1 One-to-One Associations

A Country object has a reference to its capital City. This is determined by the capital field in the country table. No other Country object will refer to the same City, so it is a one-to-one association. To implement this association in Java we need: 1. a Country class containing a City reference named capital 2. mapping info for persisting Country objects to the country table. 3. a one-to-one (or many-to-one) mapping of the capital attribute of Country to a City object. You will do each of these in the following exercises.

Exercise: Create a Country class

Create a Country class in world.domain with the attributes shown in the UML diagram (above). The Country class omits some of the fields in the country table, for simplicity. Later you'll see how to automatically generate a complete Country class from the database schema. The Country class must obey the rules for entity classes: default constructor, get/set methods, and an equals method that compares countries using the code. A toString method is also useful.
package world.domain; public class Country { private String code; private City capital; private String name; ... //TODO default constructor //TODO get/set methods for attributes //TODO equals() and toString() }

Java Persistence Lab

Page 13

Exercise: Add entity mapping for Country to orm.xml

In orm.xml we need to specify how to persist attributes of Country. We can omit the "basic" attributes that map to table columns when the attribute and column have the same name (ignoring case of letters)! JPA can determine the mapping itself. For example, the name attribute (String) will be automatically mapped to the Name field (CHAR(n) or VARCHAR(n)) of the country table. We do need to specify:

primary key and how it is generated. For Country, the application supplies the country code. one-to-one association of capital to a City object using the city ID. declare that Country is an entity in persistence.xml

1. Add these lines to orm.xml: <entity class="world.domain.Country"> <attributes> <id name="code"> <column name="Code" length="3"/> </id> <!-- use default mapping of basic attributes --> <one-to-one name="capital" fetch="EAGER"> <join-column name="Capital" referenced-column-name="ID"/> </many-to-one> </attributes> </entity> The <id> element specifies the column name and width for the country code. This is not required. <one-to-one name="capital"> refers to the capital attribute of Country. The <joincolumn...> specifies that the column named "Capital" should be joined to the ID of the city table. This is like the SQL: SELECT * FROM Country JOIN City ON Country.Capital = City.ID It is unfortunate (and confusing) that the capital attribute of Country has the same name as the field. A more standard field name for this would by Capital_ID. If the field name was Capital_ID we could have omitted the <join-column> and use the JPA defaults. 2. In persistence.xml add world.domain.Country as an entity class
<persistence version="2.0" ... <mapping-file>META-INF/orm.xml</mapping-file> <class>world.domain.City</class> <class>world.domain.Country</class>

Exercise: Write a countrySearch() method in JPADemo to display Country info

Be sure to display the capital city name!

Java Persistence Lab This code is nearly identical to the code you wrote for citySearch.
Name of country to find: Thailand Thailand is in Southeast Asia region Population 61,399,000 GNP per capita: USD 1,896.06 Capital city: Bangkok Name of country to find:

Page 14

Write a findCountry(name) method that returns a Country object. Since there should be only one country with a given name, we can use query.getSingleResult() to get a single Country object.
/** Find a Country with a given name. Result is null if no match. */ public static Country findCountry(String name) { EntityManager em = getFactory().createEntityManager(); Query query = em.createQuery("SELECT c FROM Country c WHERE c.name= :name"); query.setParameter("name", name); // this throws an Exception if there is more than one match Country co = (Country)query.getSingleResult(); em.close(); return co; }

Run your code. Does it retrieve both a Country object and a City object?

Fetching of Associations
When you use Query to retrieve a Country object, JPA automatically creates the City object for the Country capital. Moreover, if the capital City object refers to another entity, JPA will fetch that, too. JPA keeps track of which entities have been instantiated, so there is only one object for each entity data that is managed by JPA, no matter what queries we perform. For example, if execute a query to find a city named "Tokyo" (returns a City reference) and then perform another query for the country "Japan", Japan will contain a reference to Tokyo (as capital city). But both references to Tokyo refer to the same object.

Exercise: Add a country reference in the City class

A City object should have a reference to the Country where it resides. This is a many-to-one relationship. In the mapping file, many-to-one uses the same syntax as one-to-one. Do this: 1. Modify the City class to include a country attribute and add getCountry, setCountry methods. 2. Add a many-to-one mapping for the country attribute to orm.xml, for the City entity. The XML syntax for many-to-one is the same as one-to-one. The referenced-column-name property defaults to the primary key ("Code") of the referenced table (Country), so you can omit it. <one-to-one name="country" fetch="EAGER"> <join-column name="CountryCode"/> </many-to-one> 3. Modify showCity() in JPADemo so it prints the name of the country where a city is.

Java Persistence Lab

Page 15

6.2 One-to-Many Associations

A one-to-many association is a collection. A one-to-many association is often the inverse end of a many-to-one association. In the World application, a Country has a collection of its cities. ORM software usually designates one end of a bidirectional association as the primary or controlling end, and the other end as secondary or mapped. Typically, the many-to-one end is primary (since the reference is contained in the table on the "many" end). We will add a cities collection to the Country class and its mapping in orm.xml. In Country, you must declare cities as an interface type: Set, List, or Collection. 1. In the Country class, add a cities collection (Collection, List, or Set) and get/set methods. private Set<City> cities; // can be Collection, List, or Set

2. In orm.xml add a one-to-many mapping to the Country entity:

<entity class="world.domain.Country"> <attributes> ... <!-- inverse end of City-to-Country map --> <one-to-many name="cities" mapped-by="country" fetch="EAGER"> </one-to-many>

This mapping states that elements of the cities collection are controlled by the country attribute in City. We didn't specify the class of objects that cities maps to (called the target entity). The City class is inferred from the declaration of cities (e.g., Set<City> cities). You can specify the target entity explicitly using target-entity="world.domain.City", but don't do it -redundancy invites errors. 3. Modify showCountry() in JPADemo to display all the cities in a country. For example:
Name of country to find: Denmark Denmark is in Nordic Countries region Population 5,330,000 GNP per capita: USD 32,663.98 Capital city: Kbenhavn Other major cities: Frederiksberg, Frederiksberg pop. 90,327 Aalborg, Nordjylland pop. 161,161 Odense, Fyn pop. 183,912 rhus, rhus pop. 284,846

Don't display the capital city twice. JPA creates a unique object for each distinct row in the database table, so you can compare objects using ==, e.g. if (city != capital) showCity( city ).

6.3 Bidirection Association

A bidirectional association is one where there is a reference on both ends. In the previous section we say that a one-to-many association can be one end of a bidirectional association. One-to-one and manyto-many associations can also be bidirectional.

Java Persistence Lab

Page 16

Bidirectional relationships present a problem: how to keep the two ends of the association consistent? Here is a simple example in Java, using the code for City and Country:
City sangkhla = citySearch.findCity("Sangklaburi"); // in Kanchanaburi // moved to Burma!!! Country burma = countrySearch.findCountry("Myanmar"); sangkhla.setCountry( burma ); // the cities collection for Thailand and Burma must be updated, too!

Persistence frameworks, including JPA, address this problem by designating one end of the association as primary or controlling and the other end is designated as inverse or slave. The framework guarantees to maintain consistency if you make a change on the primary end. But if you make a change on the inverse end the association is not guaranteed to remain consistent.

Any Association can be Bidirectional

One-to-one and many-to-many associations can also be bidirectional.

7. Fetching Strategy: Eager and Lazy Fetching

The world database contains 343 cities in China. When we create a Country object for China using JPA, it must create the cities collection and the capital city reference. Should JPA create City objects for capital and all members of the cities collection? Country code = "CHN" name = "China" cities is Set of 343 cities City

country For example: Country china = em.find( Country.class, "CHN"); // how many objects are created from database??? Should JPA instantiate all 343 City objects in the china.cities collection?

city

Our application might never reference those objects, resulting in a lot of wasted I/O and memory. It would be more efficient if JPA could wait until the first time our application accessed the City objects. JPA provides two fetching strategies for when associated objects are instantiated: fetch="EAGER" fetch="LAZY" when instantiating an entity, load all referenced entities immediately. when instantiating an entity, don't create referenced entities until they are accessed. The referenced objects will be created the first time they are accessed by the application (which may be never).

You can see the difference in our JPADemo program. In the showCountry() method, add code to display the class name of the cities collection:

Java Persistence Lab

Collection<City> cities = country.getCities();

Page 17

System.out.println("cities is of type " + cities.getClass().getName() );

In orm.xml, the one-to-many mapping for cities has fetch="EAGER". Run JPADemo and search for a country. It should print: cities has type java.util.HashSet No surprise -- an ordinary Set. Now change orm.xml to use LAZY fetching of cities:
<one-to-many name="cities" mapped-by="country" fetch="LAZY"> </one-to-many>

When you run JPADemo again and search for a country it will print: cities has type org.eclipse.persistence.indirection.IndirectSet IndirectSet is a set that lazily Instantiates City objects as needed. Lazy fetching is usually more efficient than eager fetching, but has a potential problem. If you detach the entity before the associated objects are loaded, it will throw an exception when you try to access the unfetched objects.

8. Cascading Operations
When we save (persist) a Country, should the capital City be saved, too? If we tell JPA to delete a Country, should it also delete the referenced Cities and capital City? This behavior is called cascading. You can specify how JPA should cascade each entity association. For example, if we want all persistence operations for a Country to be applied to its capital City, we'd write: <many-to-one name="capital" fetch="EAGER"> <join-column name="Capital" referenced-column-name="ID"/> <cascade> <cascade-all/> <cascade> </many-to-one> Cascading is more complicated than fetching. The books in the references describe cascading in detail.

Java Persistence Lab

Page 18

9. Annotations
You can specify mapping information as annotations in Java source code, instead of using XML in mapping files. For existing source code, you can add the annotations yourself. In cases where you want to create classes to match a database schema, you can generate Entity classes with annotations automatically using the IDE. Both Eclipse and NetBeans can generate entity classes from database schema, and OpenJPA has a utility program for this. Java 1.5 supports annotations, but for full annotation processing you should use Java 1.6, aka Java 6.

Annotations for Class and Table

An entity class has the annotation @Entity before the class declaration. package world.domain; @Entity public class City { By default, JPA assumes the name of the database table is the same as the entity class name. City (class) objects are persisted to a City table. JPA does a case-insensitive match of table name, so table CITY or city will also work. If the table name is different from the class name, specify it using a @Table annotation as shown here: @Entity @Table(name="CITIES") public class City implements Serializable {

Where to Put Annotations for Attributes and Associations?

Attribute annotations tell JPA how to persist the class's attributes. The annotations can be written in either of two places: field: annotations appear before attribute (field) names @Id private Integer id; accessor: annotations appear before get methods. @Id public Integer getId( ) Most developers seem to prefer field annotation, since the annotations are closer together. You can use either type of annotation but you may not combine them in one class.

9.1 A City Entity using Annotations

To learn how to use JPA annotations, we'll modify the City and Country classes to use annotations. The mapping of City and Country entities in orm.xml overrides annotations in source code. Therefore, we must "deactivate" orm.xml first. Edit persistence.xml and remove the <mapping-file> entry: <persistence version="2.0" ... <mapping-file>META-INF/orm.xml</mapping-file>

DELETE

Java Persistence Lab 1. Edit the City class and add annotations.

Page 19

The JPA annotations are in the package javax.persistence; in this example we import all classes to minimize space in the code listing
package world.domain; import javax.persistence.*; // for annotation classes

@Entity public class City { @Id @GeneratedValue private Integer id; @Basic @Column(name="Name",nullable=false) private String name; private String district; private int population; @ManyToOne @JoinColumn(name="CountryCode") private Country country; /** required default constructor */ public City( ) { } //TODO get/set methods for all attributes //TODO equals method. Use the id attribute for comparison. //TODO write a toString() method }

JPA maps attributes to table columns having the same name, using a case insensitive match. It is very lenient about conversion of SQL data types to/from Java data types. An SQL INTEGER type can be mapped to a Java int, long, Integer, or Long (with possible loss of data). Similarly, a Java String can be persisted to SQL CHAR(n) or VARCHAR(n), with possible truncation of the string. We explicitly specified the @Basic and @Column mapping for the name attribute, as an example of how to use attribute mapping annotations. 2. Modify the Country class to use annotations. The "basic" attributes don't require any annotation and aren't shown here.
package world.domain; import javax.persistence.*; // for annotations @Entity public class Country implements Serializable { @Id private String code; private String name; ... //other attributes not shown here @ManyToOne @JoinColumn(name="Capital", referencedColumnName="ID") private City capital; @OneToMany(mappedBy="country") private Set<City> cities; //constructor and methods as before

Java Persistence Lab

Page 20

Exercise: Run JPADemo using annotations.

It should work the same as before.

9.2 Mapping of Attributes using Annotations

JPA assumes object attribute names map to table columns with the same name, for supported data types. That means any Java type that can reasonably be mapped to an SQL type. JPA uses intuitive and flexible rules. For example, both int and Integer map to INTEGER. In this case (attribute name same as table column name and attribute type is a "basic" type), you don't have to write any annotation for attributes -- except the identifier (@Id) attribute. If the table column name is not the same as object attribute name, specify the name in an annotation. For example, if the County attribute yearOfIndependence is saved in column IndepYear, use: @Column(name="IndepYear") private int yearOfIndependence; There is ambiguity in mapping of some data types, esp. date, time, and strings. The code field is CHAR(3) in the Country table, but String in Java. You can specify mapping details in annotations: @Column(name="code",length=3,nullable=false) private String code;

9.3 Mapping of Associations using Annotations

There are annotations for different kinds of associations. For bidirectional associations, the controlling end specifies a join-column for the association and the other end refers to the controlling end.

1-to-1 Mapping of Country.capital to City. The @JoinColumn name identifies the joining column in the Country table, and referencedColumnName is the column in the City table. @OneToOne @JoinColumn(name="Capital",referencedColumnName="ID") private City capital;

many-to-1 Mapping of City.country to a Country. @JoinColumn identifies the join column name in the City table. It will be joined to the primary key (code) in the Country table, since we didn't specify a referencedColumnName. @ManyToOne(optional=false) @JoinColumn(name="CountryCode", fetch=FetchType.LAZY) private Country country;

1-to-many Mapping of Country to its City(s), as inverse end of city-to-country mapping: @OneToMany(mappedBy="country") private Collection<City> cities; // inverse of City.country map

many-to-many Mapping A many-to-many mapping requires a join table. Not used in this example. embedded objects and enumerations JPA has special syntax for enumerations and for embedding the data for one object inside the row of data for the referencing object. (Described later.)

Java Persistence Lab

Page 21

10. Persistence Operations for find, save, update, and delete

The standard persistence services are create (save), retrieve, update, and delete. EntityManager provides methods for all of these. It also provides an extensive query syntax, which we have seen above.

Entity States
An entity can have several states: new - an object not yet persisted managed - object has been persisted and is currently attached or managed detached - object has been persisted, but is not currently being managed. Detached objects can be reattached (put back in managed state). TODO: Explain the entity life cycle.

10.1 Save (Persist) an Object

To persist object as a new entity use the persist method. Database updates must be part of a Transaction. To save the city of Bangsaen, Chonburi (Thailand) to the database, assuming it hasn't been added yet, use:
EntityManager em = factory.createEntityManager( ); EntityTransaction tx = em.getTransaction( ); tx.begin( ); // get the country entity for Thailand Query q = em.createQuery( "SELECT c FROM Country c WHERE c.name='Thailand'"); Country thailand = q.getSingleResult( ); // now create Bangsaen. Assume City has a parameterized constructor. City city = new City( "Bangsaen", "Chonburi", 30000 ); city.setCountry( thailand ); em.persist( city ); tx.commit( );

The persist method may throw a DatabaseException if the user does not have INSERT permission for the tables or if any database constraint is violated (e.g. a null attribute for a required field).

10.2 Find Entity by Identifier (key)

EntityManager can return an object for a given value of the primary key. This isn't used very often, since key lookup isn't usually part of a domain model. To find the country with code "CHE" use:
Country c = em.find( Country.class, "CHE" ); // the answer is probably not what you expect

There is something amazing here. We saved the return value from em.find() as a Country reference without using a cast. This only seems to work on Entity classes using annotations.

Java Persistence Lab

Page 22

10.3 Update an Entity

There are two ways to update an object (entity) in the database. 1. For an entity currently being managed by JPA, just set the attributes. The database values are updated automatically when you commit the current transaction. Let's change the population of Thailand. As of 2011, it is 67 million.
EntityTransaction tx = em.getTransaction( ); tx.begin( ); Country thailand = em.find( Country.class, "THA" ); // set the attribute thailand.setPopulation( 67000000 ); tx.commit();

2. Enter an "update" command using JPQL syntax, like an SQL UPDATE. Use a Query object to execute the update:
Query query = em.createQuery( "UPDATE Country c SET c.population=:pop WHERE c.name='Thailand'"); query.setParameter("pop", 67000000); tx = em.getTransaction( ); tx.begin(); query.executeUpdate( ); tx.commit();

10.4 Delete an Entity

Use remove. This removes the city from the database but does not change contents of the object. This is not the same as the detach method, that simple changes the entity state from managed to detached.
// DELETE Bangsaen. Bangsaen sucks. I know - I live there. Query q = em.createQuery("SELECT c FROM City c WHERE c.name=:name"); q.setParameter("name", "Bangsaen"); City bangsaen = q.getSingleResult(); // exception if more than one match tx = em.getTransaction( ); tx.begin(); em.remove(bangsaen); tx.commit();

10.5 JPA Query Language

JPA queries are in terms of classes and objects, not database tables. The syntax is Java Persistence Query Language (JPQL), which borrows from Hibernate Query Language. To query a city named Bangkok, use:
Query q = em.createQuery( "SELECT c FROM City c WHERE c.name = 'Bangkok'"); // throws exception if no match or more than 1 match City city = q.getSingleResult( );

Java Persistence Lab Names of classes and attributes are case-sensitive in JPQL (just like Java). Correct: Wrong: Correct: Correct: Wrong: select c from City c select c from city c SELECT c FROM City c // name of class is "City"

Page 23

// query language words are case-insensitive

select c from City c where c.name='Bangkok' select c from City c where name='Bangkok' // no object

Queries with Parameters

You can use named parameters or positional parameters in queries, similar to the ? in an SQL PreparedStatement. A named parameter begins with a colon (:) followed by a name (any valid variable name): Query q = em.createQuery( "SELECT c FROM City c WHERE c.name = :name"); q.setParameter("name", "Bangkok"); List<City> cities = q.getResultList( );

Using a Collection as Parameter

JPQL has an "x IN set" condition that is used in WHERE expressions. You can use a Java Collection for the values used by "IN". To find all cities in Thailand or Malaysia, use: Set<String> names = new HashSet<String>(); names.add("Thailand"); names.add("Malaysia"); Query q = em.createQuery( "SELECT c FROM City c WHERE c.country.name IN :set"); q.setParameter("set", names); List<City> cities = q.getResultList( );

Type-safe Queries
In the previous examples, we assigned q.getResultList( ) to List of City objects using unchecked type conversion. It's up to the programmer to make sure this will work; otherwise the code will throw a ClassCastException at runtime. JPA 2.0 has a typed query which is more type-safe that the Query interface in JPA 1.0. TypedQuery has a type parameter for the class of object(s) the query returns. TypedQuery<City> q = em.createQuery( "SELECT c FROM City c WHERE c.name = :name", City.class); q.setParameter("name", "New York"); List<City> cities = q.getResultList( ); Notice the 2nd parameter in createQuery. This creates a query that can only return City objects.

Java Persistence Lab

Page 24

Walking the Object Graph in JPQL

In JPQL you can access attributes of objects using "." notation. This feature is similar to C# properties and EL expressions. For example, to use the name of the country associated with City c, use: SELECT c FROM City c WHERE c.country.name = 'China' To find all the cities in China::
Query q = em.createQuery( "select c from City c where c.country.name = 'China'" ); List<City> cities = q.getResultList( );

10.6 Criterion Queries

What if you want to make a query like: Find cities with population between 100,000 and 500,000

and in a country in Asia and not in "China" or "Japan"

This would be difficult in JPQL. JPA has Criterion queries for this purpose. The query is built up as a sequence of criteria that must be true or false. Criterion queries are useful for creating a query programmatically from input choices, such an "Advanced Search" on many e-commerce sites.

Java Persistence Lab

Page 25

11. Implementing Data Access Objects using JPA

Software design principles recommend that we design for separation of concerns, low coupling, single responsibility, and protected variations via a layer of abstraction. So, we should consider persistence as a separate responsibility, implemented in separate classes. A common design is to use data access objects (DAO) to provide the required persistence services (the CRUD operations). So that our application is easy to change, we would like to (1) database and schema information separate from our Java code so it can be changed without modifying code, (2) provide an interface for DAOs so we can provide alternative DAOs for different persistence frameworks. A typical DAO has methods such as:

Exercise: Write a CityDao

1. Provide a static getFactory method to get the EntityManagerFactory. 2. Implement the methods in the UML diagram above. When you write CityDao and CountyDao, you will notice that there is a lot of identical code, including identical getFactory method. Duplicate code is a sign of poor design. We can refactor the design to eliminate duplicate code. A common pattern for this is an abstract superclass with type parameter.
K, T

Type parameters: K = key type T = Entity type

We can allow for alternate Dao implementations by writing an Interface for DAO and a DaoFactory to create instances of DAO. The DaoFactory would decide to create JPA-based DAO, JDBC DAO, or any other implementation we write. (See the reference article Core J2EE Patterns - Data Access Object.)

Java Persistence Lab

Page 26

12. Generate a Country Class (Automatically!) with Association to City

Eclipse and NetBeans can generate Java classes from database table schema. They can also add JPA annotations to the classes they generate. To do this in Eclipse, you need to install the Dali Java Persistence Tools. In Netbeans 7.0, this feature is available in the standard configuration. We will create a Country entity with a capital attribute that refers to a City. If you have defined a database connection for World in Eclipse or NetBeans, the IDE can generate the code for you. Eclipse 1. Connect to the database, so Eclipse JPA Tools can see the schema. 2. Right-click on project and choose New Other... JPA Entities from Tables. 3. Select the connection, schema (for Derby, this is APP), and select Country table. Check "Update class list in persistence.xml". Click Next. 4. In "Table Associations", click on green "+". In the New Association dialog, choose COUNTRY and CITY tables, and JOIN using capital and id fields.

Next>

Next>

5. Click Finish. Eclipse may create the association, but in my attempts using Helios SR2 it did not. 6. Complete the dialogs to create the Country class. For "annotation type", select "field". The mapping of capital to a City is a one-sided, many-to-one association. You may need to write this code yourself (delete the "int capital" and edit the get/setCapital methods).
package world.domain; @Entity public class Country implements Serializable { @Id private String code; @ManyToOne @JoinColumn(name="Capital", referencedColumnName="ID") private City capital; //TODO create get/set methods for Capital public City getCapital( ) { return capital; } public void setCaptial(City city) {

Java Persistence Lab

this.capital = city; }

Page 27

13. Summary of Common JPA Annotations

Persistence metadata is the information JPA needs to persist objects. It can be specified as annotations in Java source code or in XML files. Here is a summary of common annotations. Examples of each of them are given below. @Entity public class City @Table(name="CITIES") public class City { } @Id private String code; @Id @GeneratedValue private String ID; @Transient public double gnpPerCapita;; @Column(name="name") @Column(name="name", length=30, unique=true) String name; @OneToOne // in city class @ManyToOne private Country country; @ManyToOne @JoinColumn(name="capital" referencedColumnName="ID") City capital; @OneToMany(mappedBy="country", cascade=CascadeType.PERSIST) private Collection<City> cities; Identifies a persistent class. By default, the table name is the same as the class name. The second form lets you specify the table name. Optional annotation for table name, if not same as class name. Indicate attribute that is the primary key in database table. Indicates an attribute value is generated automatically by database. An attribute that should not be persisted in database. Specify name of column and width (for Strings). For numeric types, use precision instead.

Annotation for attributes that are associations to other persisted objects. Association to another object using a foreign key reference. Default field is country_code and target table determined by the class of attribute (Country). Default column name is the attribute name + "_" + name of key in target table. So the default for captal would be capital_ID. A Country has a collection of cities. It is an inverse map that is mapped by the country field in the City class.

13.1 Summary of XML mappings

The basic structure of orm.xml:
<?xml version="1.0" encoding="UTF-8"> <entity-mappings version="2.0" xmlns="http://java.sun.com/xml/ns/persistence/orm" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm http://java.sun.com/xml/ns/persistence/orm_2_0.xsd">

Java Persistence Lab

Page 28

</entity-mapping>

Optional <package>. You can specify a default package name so you don't need to include the package on each class name. The package name applies to all <entity> entries until the next <package>.
<package>world.domain</package>

The mapping of a class is done in an entity tag. The attribute metadata-complete="true" means that this OR mapping specifies all mapping info, and annotations in the class should be ignored.
<entity class="world.domain.city"> </entity> <entity class="world.domain.country" metadata-complete="true"> </entiry>

Java Persistence Lab

Page 29

13.2 Using JPA with Netbeans

NetBeans 7.0 has good support for JPA 1.0 and JPA 2.0. Some things Netbeans can do are: create a Persistence Unit from an existing database connection create Java code from a database table generate a database schema from Java code (JPA does this, but Netbeans configures it). To create persistence unit: 1. First create a database connection in Netbeans for the database. Do this in the "Services" tab.

Creating An Entity Class From Schema

Netbeans can create an entity class from a table in the database. The generated Java code includes annotations for persisting the class. 1. Right-click on the project and choose New Other Persistence and "Entity Classes from Database". If you've already added a Persistence Unit, then "Entity Classes from Database" will be on the new menu. 2. Select the Database Connection and the Table to create class from:

3. Click Next and enter package (world.domain) and select options. If you aren't using Named Queries or JAXB, then uncheck them.

4. The next dialog lets you select how associations should be fetched and whether collections should be declared as Collection, Set, or List.

Java Persistence Lab

Page 30

13.3 Using JPA with Existing Eclipse Projects

You can use JPA in any Eclipse Java project. It isn't necessary to create a JPA project. The benefit of a JPA project is that Eclipse can help generate annotations and synchronize persistence.xml with other parts of your application. But you can do that yourself in any project. To use JPA in a non-JPA project, do this: (a) add EclipseLink JAR files (better: EclipseLink library) to your project, (b) add the JDBC driver JAR for your database, (c) create a META-INF directory in the top-level project src directory and then create MANIFECT.MF and persistence.xml files there. Edit the files in Eclipse, using examples from this tutorial. You can also add new JPA artifacts in non-JPA projects using New JPA (choose file type). If you want to convert a Java project to a JPA project, right-click on the project (or use Project menu) and choose Configure. In the Configure menu is a "Convert to JPA Project" item that will open the same dialog as for creating a new JPA project.

Java Persistence Lab

Page 31

13.4 Installing Software for this Lab

1. EclipseLink. Download "EclipseLink Installer Zip" from http://www.eclipse.org/eclipselink/. Also download eclipselink-javadocs.zip. EclipseLink is an implementation of JPA 2.0. unzip Eclipselink-2.x.yyy.zip to your software directory (e.g. C:/lib). This will create an eclipselink subdirectory, such as C:/lib/eclipselink. move the eclipselink-javadocs.zip to this directory. In your IDE, create an EclipseLink library. Add two JAR files to this library: eclipselink/jlib/eclipselink.jar eclipselink/jlib/jpa/javax.persistence_2.0.3vXXXX.jar In your IDE, add the eclipselink-javadocs.zip as javadoc to both of the JARS, for context sensitive help.

2. Derby (Optional) You can use Derby or MySQL. Derby is simple to use, but sometimes annoying since it only allows only one connection to a database. More information on using Derby is in a separate lab sheet. download db-derby-10.1.2.zip (or any recent version) from derby.apache.org. unzip to your library directory, e.g. C:/lib. The zip file will create a subdirectory named "dbderby", such as C:/lib/db-derby. The Derby drivers are JAR files in directory dbderby/lib. So that you can use Derby tools like ij, set the DERBY_HOME environment variable and add DERBY_HOME/bin to your shell path. In Windows, right click MyComputer, choose Properties, Advanced, and add these. On Linux, edit your .profile or .bashrc (Tcsh users, edit .login). This is Windows syntax: set DERBY_HOME = C:/lib/db-derby set PATH = %DERBY_HOME%\bin;%PATH%

Java Persistence Lab

Page 32

(Optional) Create a Derby library in your IDE. There are 2 ways of using Derby: embedded server mode and client-server mode. In this lab we use embedded server mode (simpler) that is contained in the file db-derby/lib/derby.jar.

Java Persistence Lab

Page 33

Resources
These articles are given in the order that is instructive. 1. Accessing Data through Persistence Frameworks. http://www.developer.com/lang/article.php/3355151/Accessing-Data-Through-PersistenceFrameworks.htm 2. JPA 2.0 with EclipseLink Tutorial. http://www.vogella.de/articles/JavaPersistenceAPI/article.html. 3. Using the Java Persistence API in Desktop Applications, article from Sun (June 2007). http://java.sun.com/developer/technicalArticles/J2SE/Desktop/persistenceapi/. Older and biased toward Sun implementations (NetBeans, Toplink Essentials). 4. MyEclipse JPA Tutorial, http://www.myeclipseide.com/documentation/quickstarts/jpa/. Books and User Guides Bauer & King, Java Persistence with Hibernate, Manning, 2007. Excellent book about Hibernate and data persistence in Java, including JPA. Gavin King is founder of the Hibernate project, Bauer is member of the development team. OpenJPA User's Guide. This manual (in PDF form) has an ongoing example that shows every relationship you'd want to persist, and how to do it using either annotations or XML. Useful even if you don't use OpenJPA. Download from openjpa.apache.org. EclipseLink User's Guide at http://wiki.eclipse.org/EclipseLink. User guide in Wiki form. Examples mostly use annotations. Page /EclipseLink/Examples/JPA/EclipseLink-ORM.XML has XML.

Practical JPA Advice

1. JPA Implementation Patterns, article at http://java.dzone.com/articles/jpa-implementation-patterns. 2. Core J2EE Patterns - Data Access Object. http://java.sun.com/blueprints/corej2eepatterns/Patterns/DataAccessObject.html 3. Has JPA Killed the DAO? http://www.infoq.com/news/2007/09/jpa-dao. JPA makes data access so simple, programmers wonder why bother to write DAO? This article explains why.

JPA Implementations
JPA is a specification. To use it you need an implementation. JPA implementations are: EclipseLink, http://www.eclipse.org/eclipselink/. This is the JPA 2.0 reference implementation. TopLink Essentials, http://glassfish.dev.java.net/downloads/persistence/JavaPersistence.html a part of the Glassfish project. Hibernate, see JBoss Community Documentation for how to use Hibernate as JPA provider. DataNucleus Access Platform provides both JPA and JDO. Has good documentation and support for IDEs. http://www.datanucleus.org/products/accessplatform.html OpenJPA, an Apache project. http://openjpa.apache.org.

Resource for Other Frameworks

Apache JDO http://db.apache.org/jdo/. The site has an interesting (but biased) comparison of JDO and JPA at http://db.apache.org/jdo/jdo_v_jpa.html.

Java Persistence Lab

Page 34

Developer.com series on Java frameworks: http://www.developer.com/java/ent/article.php/3325741