Java Persistence Architecture 2.0 - Using The New ElementCollection Mapping

Introduction

I've been studying Java Persistence Architecture (JPA) 2.0 since we may adopt it on my programming team. One of the new features provided by JPA 2.0 is ElementCollection. An ElementCollection can be used to define a one-to-many relationship between an entity and a collection of basic values (for example, a collection of Strings).

Example Application

You can download the example application, which is a zipped Maven project. The example was created using Eclipse 3.6 and the m2eclipse Maven plugin. It is a standard Maven project, so if you're not using Eclipse you should be able to import (after unzipping the download) the project into any Maven aware Java IDE. If you don't have a Maven aware Java IDE you can view the source code in any text editor.

The example application uses HyperSQL to create an in-memory database for storing the project's entities.

After importing the project into your Java IDE, the domain class--Applicant--is in package name.brucephillips.elementcollectionexample.domain (under src/main/java). There is a JUnit 4 test of this class in src/test/java. The persistence.xml file is found in src/main/resources META-INF folder. For this example application I used Hibernate as the JPA provider.

To run the example application's test you must have Maven installed. Open a terminal (command) window and navigate to the unzipped project's root folder (ElementCollectionExample) where the pom.xml file is located. Enter this Maven command to run the test.

ElementCollection Annotation

If you examine the Applicant class you'll find this code:

The Applicant class has a collection of Strings used to store the applicant's phone numbers. The @ElementCollection is an annotation provided by JPA 2.0. Since the applicant's phone numbers are stored using a collection of Strings, I can use the @ElementCollection annotation to instruct the JPA provider to create a one-to-many relationship between the Applicant table and a table that stores the phone numbers.

By default the table used to store the phone numbers will be named Applicant_phoneNumbers. It will have two columns: Applicant_id and phoneNumbers. If you examine the output from running the example application's test you‚'ll see where the Applicant_phoneNumbers table is created.

CollectionTable Annotation

If you want to specify the table used to store the collection then you can use the CollectionTable annotation. If you just want to override the column name and its features used in the collection table you can use the Column annotation. The CollectionTable Java documentation provides a good example of using CollectionTable or Column annotations with ElementCollection.

Additional Use Of ElementCollection

You can also use ElementCollection to define a collection of Embeddable types. Embeddable types are designated using the Embeddable annotation. Embeddable is used to define how to persist an object that does not exist on its own but is always embedded into another Entity object.

An example is an applicant's address. In my example application I don't want Address objects stored without an associated Applicant object so I annotated the Address class with Embeddable and then used the ElementCollection annotation in class Applicant to define the persistence of a collection of Address objects.

Each Address object associated with an Applicant object will be stored in a separate table but linked to its Applicant. If you examine the output from running the example application's test you'll see an Applicant_address table is created.

Collection persistence defined using the ElementCollection annotation are completely managed by the entity manager. If I delete an Applicant object from the database all associated phone numbers and addresses will be deleted from their tables.

Drawback Of Using ElementCollection

A drawback of using ElementCollection instead of the OneToMany annotation is that the objects in the collection cannot be queried or managed independently of the owning object. So in my example application I could not query for which applicants live in a specific zip code or have a specific phone number. If you examine the output from running the example application's test you'll see that the tables created to store the ElementCollection annotated objects do not have a primary key.

Summary

One of the new features provided by JPA 2.0 is ElementCollection. ElementCollection enables you to define how the JPA provider should persist a collection of basic or embeddable types. It's a simpler way to define a one-to-many relationship then using the OneToMany annotation. ElementCollection is especially useful for persisting a collection of basic types such as a collection of Strings.

References

Java Persistence, Wiki Book, http://en.wikibooks.org/wiki/Java_Persistence/ElementCollection, Accessed November 2010

Package javax.persistence Java Documentation, http://download.oracle.com/javaee/6/api/javax/persistence/ElementCollection.html, Accessed November 2010

Java Persistence with JPA, Daoqi Yang, Outskirts Press, 2010, Section 4.1.3