Banish Your Resistance to Persistence with the EJB 3.0 Persistence API

lthough the EJB 3.0 specification has yet to be released, it is already generating much interest in the software development community by both proponents and opponents alike. All recognize the need to find more productive methods for developing software; the debate centers on whether, and to what extent, EJB 3.0 will play a role in this new landscape. Debate notwithstanding, the release of the EJB 3.0 public draft and preliminary support in JBoss mean that now is a great time to explore this influential technology. In fact, reports of the use of EJB 3.0 in production systems are already emerging.

This article is the second in a three-part series exploring EJB 3.0 as defined in the public draft. Each article will introduce you to particular concepts from the specification and walk you through the implementation of these techniques using JBoss.

The first article introduced EJB 3.0, the philosophy behind it, and illustrated how to use it to develop Enterprise Bean Components. This second article will introduce you to developing persistent entities with EJB 3.0. The third article will explore more advanced topics such as transaction management, security, exceptions, callbacks, and interceptors.

Example Application
In the first article I built a sample music store application that allows users to browse for albums and videos, add them to their shopping cart, and eventually purchase the items stored their cart. In this article I’ll extend that application to illustrate the concepts of EJB 3.0 persistence. The storefront is shown in Figure 1.

Figure 1. Music Store: The music store allows products to be browsed, added to a shopping cart, and eventually purchased.
Figure 2. Music Store Design: In this design web, requests are handled by a Struts action that uses two EJBs (one stateless and the other stateful) to fulfill the request. At checkout the customer’s cart is passed via JMS to an order processor implemented as a MDB for fulfillment.

In the first article you saw how the storefront was designed and implemented using EJB 3.0 enterprise component beans (session and message-driven beans). This simple design is shown in Figure 2.

In this article you will enhance the application to retrieve its inventory from a database using EJB 3.0 persistence.

What You Need

Introducing EJB 3.0 Persistence
The EJB 3.0 specification defines a persistence API that is modeled after successful approaches to Object Relational Mapping (ORM) such as Hibernate, JDO, and TopLink. This approach stands in contrast to the approach taken in the introduction of entity beans in EJB 1.0 where the specification preceded industry consensus.

This third major release of the EJB specification is exciting because it attempts to standardize the successful, yet diverse, array of ORM tools. This standardization is not intended to replace existing tools or to discourage innovation in this arena, but to provide a commonly agreed upon set of standards to support vendor tooling and the stability associated with Sun and JCP acceptance. This is often important to large IT organizations concerned with the long-term viability of the technologies they adopt.

This new approach to developing persistent entities is radically different then the entity bean approach taken in prior versions of the EJB specification. This new approach is characterized by:

  • Plain java objects (POJO)?Persistent entities are simple Java objects and have no dependencies on an EJB-specific API.
  • Metadata annotations?The mapping configuration is defined by source-level metadata annotations. An XML descriptor may still be used as an alternative or to override annotations.
  • Configuration by exception?To simplify configuration the specification takes the approach of assuming reasonable defaults and requiring the programmer to only define configuration information when it is necessary to override these settings.
  • Optional container?The persistence API defined in the EJB 3.0 specification is designed to run both inside and outside of an EJB container.

Introducing Entities
The specification defines entities as lightweight persistent domain objects. This means an entity is simply a POJO from your domain that you desire to persist in a data store of some type. The requirements of an entity are very minimal. To qualify as an entity a class must:

  • Be annotated with the @Entity annotation.
  • Have a default (no argument) constructor.
  • Have a primary key.
  • Must not be final and must have no final methods.
  • Instance variables holding the state of the entity must be private, protected, or have package visibility.
  • If the entity is to be detached then the class must implement the Serializable interface.

Entities are plain Java objects and as such may contain references to other POJOs and persistent entities. An entity class may be abstract and can extend other entity or non-entity classes.

Basic Mapping
In order for entities to be persisted the state of each entity must be mapped to the underlying data source. This is typically done through metadata annotations that map fields in the entity to tables and columns in the data store. You have two options (access types) regarding how you define this mapping:

  • Field access?All non-transient instance variables are persisted. You annotate the instance variables directly to override default mapping settings.
  • Property access?All public and protected, non-transient properties are persisted. You annotate the getter method to override default mapping settings.

You can choose which access type you wish to be used for each entity through the access attribute of the @Entity annotation. The example below illustrates how to specify field-level access:

@Entity(access = AccessType.FIELD)public class MusicOrder implements Serializable{    ...}

By default, property-level access is assumed for persistent entities.

You can specify a variety of settings to control how the entity is persisted. For example, you can specify which table a particular entity is persisted to through the @Table annotation, which can be applied at the class level:

@Entity(access = AccessType.FIELD)@Table(name = "musicorder")public class MusicOrder implements Serializable{...}

And you can specify which column any particular field or property is persisted to through the @Column annotation:

@Entity(access = AccessType.FIELD)@Table(name = "musicorder")public class MusicOrder implements Serializable{    @Column(name = "desc")    private String description = "test";    ...}

If you would like a particular to field to not be persisted then all you have to do is annotate it with the @Transient annotation to indicate that the data in the field need not be saved:

@Entity(access = AccessType.FIELD)@Table(name = "musicorder")public class MusicOrder implements Serializable{    @Column(name = "desc")    private String description = "test";    @Transient    private List products;    ...}

However, in order to make the example above complete we must define a primary key and optionally provide information about how this identifier is to be determined and mapped. The following example shows a simple primary key where the responsibility for assigning unique identifiers is delegated to the underlying database:

@Entity(access = AccessType.FIELD)@Table(name = "musicorder")public class MusicOrder implements Serializable{    @Id(generate = GeneratorType.AUTO)    private long orderID;    @Column(name = "desc")    private String description = "test";    @Transient    private List products;    ...}

As shown above the @Id annotation allows you to configure the strategy used to determine the value of the identity field. Other options include TABLE, SEQUENCE, AUTO, and NONE. For more information on these other options consult the EJB 3.0 specification.

In order to convert this example to work with property-level access instead of field-level access all you would need to do would be to change the access attribute of the @Entity attribute to AccessType.PROPERTY and move the @Id, @Column, and @Transient annotations to their respective getter methods.

At this point you have created an EJB 3.0 entity class that contains enough information for the persistence engine to store MusicOrder objects. Next you need to use the persistence framework API to cause persistent entities to be created, updated, and deleted.

The Entity Manager API
The three key concepts behind persistence in EJB 3.0 are the persistence unit, persistence context, and the entity manager.

A persistence unit is a set of classes that are mapped to a single data store. These classes are typically packaged into a single persistence archive (PAR), which associates these classes and their mapping metadata with a named entity manager. Persistence archives will be discussed in more depth later in this article.

The EJB 3.0 specification defines a persistence context as “a set of entity instances in which?for any persistent entity identity?there is a unique entity instance.” In most cases this means that a persistence context is the set of entities associated with a particular transaction.

The entity manager is the primary interface for your programs to interact with the underlying persistence engine. An entity manager is associated with a particular persistence context and provides methods to create, update, and delete entities (among other functions).

You typically obtain an entity manager either through dependency injection or by looking up the entity manager through JNDI. In order for the container to inject an entity manager into your class you must declare a field of type EntityManager and annotate it with the @PersistenceContext annotation. This annotation specifies which persistent unit to retrieve an entity manager for and matches the unit name specified in the persistence archive. This is the simplest approach for obtaining an entity manager and is illustrated below in the OrderProcessor message-driven bean begun in the first article.

public class OrderProcessor implements MessageListener{    @PersistenceContext(unitName = "musicStoreDB")    protected EntityManager em;    ...}

Once you have obtained an entity manager reference you can use the entity manager interface to store and retrieve persistent entities. For example, to store a MusicOrder you can invoke the persist() method on the entity manager. Below you’ll find the OrderProcessor, which has been enhanced to receive an order via JMS and save it to the database:

public class OrderProcessor implements MessageListener{    @PersistenceContext(unitName = "musicStoreDB")    protected EntityManager em;    public void onMessage(Message message)    {        ObjectMessage objectMessage = (ObjectMessage) message;        try        {            MusicOrder order = (MusicOrder) objectMessage.getObject();                        em.persist(order);        }        catch (JMSException e)        {            e.printStackTrace();        }    }}

In addition to using the EnityManager class to persist entities, you can also use it to find particular entities by their identifying primary key. The MusicStoreDAO contains several examples of this:

public class MusicStoreDAO implements IMusicStoreDAO{    @PersistenceContext(unitName = "musicStoreDB")    protected EntityManager em;    ...    public Artist findArtistById(int id)    {        return em.find(Artist.class, id);    }    public Genre findGenreById(int id)    {        return em.find(Genre.class, id);    }    public Product findProductById(int id)    {        return em.find(Product.class, id);    }        ...}

The EntityManager retrieves a unique entity from persistent storage via a class and a primary key object. The actual definition of the find method of the EntityManager is shown below:

/*** Find by primary key.* @param entityClass* @param primaryKey* @return the found entity instance or null* if the entity does not exist* @throws IllegalArgumentException if the first argument does* not denote an entity type or the second* argument is not a valid type for that* entity’s primary key*/public  T find(Class entityClass, Object primaryKey);

There are a couple of points to take note of here. First, this method uses generics to match the return type of the method to the entityClass parameter. This avoids having to make the self-obvious cast from Object to the type of object you are retrieving. Also notice that although the second parameter expects an object I am passing a primitive integer instead. The Java 5 JRE is autoboxing the primitive into an Integer object before passing it on to the EntityManager.

In addition to allowing you to retrieve individual objects via the find method, the EntityManager also features a query language that you can use to perform more complex queries against your persisted entities. This query language is named EJB QL and more information on this can be found in the EJB 3.0 specification. An example of this from the music store application, and also from the MusicStoreDAO, is shown below:

public class MusicStoreDAO implements IMusicStoreDAO{    @PersistenceContext(unitName = "musicStoreDB")    protected EntityManager em;    ...    @SuppressWarnings("unchecked")    public List listGenres()    {        return (List) em.createQuery("SELECT g FROM Genre g").getResultList();    }        ...}

More Advanced Mapping
The previous example showed how a simple POJO could be persisted to a single table. However, in most real-life scenarios you will be dealing with much more complex domain objects. For example, Figure 3 below shows a class diagram of the domain objects from the example music store application.

Figure 3. Music Store Domain. The music store domain illustrates more complex mapping scenarios including entity references, collections, and inheritance.
Figure 4. Music Store Database. The music store domain uses metadata annotation to provide a mapping to this relational schema.

The examples in this section will illustrate how to map this domain model into the relational schema illustrated in Figure 4.

In comparing these two illustrations, you will notice several fundamental differences. For example, Java objects express multiplicity via collections and a relational database by foreign keys and link tables. These differences are often collectively referred to as the object-relational mismatch and are the problem ORM tools are meant to address.

Relationships between entities come in several flavors. These are one-to-one, one-to-many, many-to-one, and many-to-many. In Java, a one-to-one relationship is simply a reference to an entity. A one-to-many, many-to-one, or many-to-many relationship is a collection of entity references. In order to be properly mapped to its corresponding representation in the database, each relationship must be properly annotated as: @OneToOne, @OneToMany, @ManyToOne, or @ManyToMany. As an example, the many-to-many relationship between genres and artists is illustrated below:

@Entity(access = AccessType.FIELD)public class Genre implements Serializable{    @Id(generate = GeneratorType.AUTO)    private int id;    private String name;    private String description;    @ManyToMany(fetch = FetchType.EAGER)    @JoinTable(table = @Table(name = "genre_artist"), joinColumns = {        @JoinColumn(name = "genre_id")    }, inverseJoinColumns = {        @JoinColumn(name = "artist_id")    })    private Set artists = new HashSet();    ...}

Notice the @JoinTable annotation is used to specify which table and columns are used at a database level to store this many-to-many relationship. Also notice that the example above specifies a fetch type of eager. With eager fetching the elements contained by the entity are fetched immediately with the containing entity. With lazy fetching these elements are not fetched until they are needed. Although lazy fetching is often desirable, it won’t work if the entity is already detached from its persistence context the first time the elements are needed. This is the case in the music store example because the genres are retrieved from the artist in a JSP page executing after control has left the EJB where the transaction is demarcated.

Additionally, each type of relationship can be either unidirectional or bidirectional. In a unidirectional relationship one entity has a reference to another, but the second entity does not have a corresponding reference back to the first. In a bidirectional relationship both entities have references to each other.

All relationships have an owning side. The owning side is used to determine what updates need to be applied to the database. Additionally, bidirectional relationships also have an inverse side. In a one-to-one relationship the owning side is the side with the reference. In a one-to-many relationship the many side must be the owning side. And in a many-to-many relationship either side can be the owning side. Regardless, it is the developer’s responsibility to keep both sides of the relationship consistent with one another.

In a bidirectional relationship the inverse side must refer back to the owning side through the mappedBy attribute of the annotation used to define the relationship. This is illustrated below in the Artist-to-Genre relationship, which is the inverse of the previously illustrated Genre-to-Artist relationship.

@Entity(access = AccessType.FIELD)public class Artist implements Serializable{    @Id(generate = GeneratorType.AUTO)    private int id;    private String name;    private String biography;    @ManyToMany(mappedBy = "artists", fetch = FetchType.EAGER)    private Set genres = new HashSet();    ...}

Notice that the mappedBy attribute refers to the property name of the owning collection, in this case “artists.” The type of the related class is determined through the use of generics.

In order to keep both sides of the relationship consistent with each other it is common to assign the owning side the responsibility of keeping the relationship consistent. For example, you could create an addProduct method on the Artist class that would maintain both ends of the relationship.

@Entity(access = AccessType.FIELD)public class Artist implements Serializable{    ...    @OneToMany(mappedBy = "artist", fetch = FetchType.EAGER)    private Set products = new HashSet();    public void addProduct(Product product)    {        products.add(product);        product.setArtist(this);    }    ...}

Notice that in this example the addProduct method not only stores the new product in the Artist object but also sets a reference to itself in the corresponding product. This approach is preferred to calling anArtist.getProducts().add(aProduct) because it properly encapsulates management of the collection within the artist class. This is also consistent with Law of Demeter (“don’t talk to strangers”), which would discourage directly manipulating elements within a collection contained in another object.

In addition to being able to map entities related by containment to a database, EJB 3.0 also allows entities related through inheritance to be mapped and persisted. There are three strategies to accomplish this:

  • Single table per class hierarchy?Create one table and place within it all data related to the hierarchy of objects. A discriminator column is added to indicate each table row’s object type.
  • Single table per class?Each subclass is mapped to a separate table.
  • Joined subclasses?Fields common to all classes in the hierarchy are placed in one table. Each subclass has its own table with fields specific only to that subclass.

These three strategies are illustrated below in Figure 5.

Figure 5. Inheritance Mapping Strategies. There are three mapping strategies that you can choose from to map inherited entities to a database. Each strategy has its own tradeoffs in terms of duplication and complexity.

You specify the mapping strategy, and optionally the discriminator value, in the @Inheritance annotation applied to the subclasses. The default mapping strategy (and the one used in the example application) is the table per class hierarchy strategy. This is illustrated in the below code snippets from the Product, Album, and Video classes, respectively.

@Entity(access = AccessType.FIELD)public abstract class Product implements Serializable{    @Id(generate = GeneratorType.AUTO)    private int id;    private String title;    private String description;    @ManyToOne    private Artist artist;    ...}@Entity(access = AccessType.FIELD)@Inheritance(discriminatorValue = "A")public class Album extends Product{    private int tracks;    ...}@Entity(access = AccessType.FIELD)@Inheritance(discriminatorValue = "V")public class Video extends Product{    private int length;    ...}

Notice how both classes specify a unique discriminator value. This value is used by the persistence framework to determine the underlying Java type of the object from the relational data. With this strategy, the class hierarchy is flattened when it is persisted to the database. Figure 6 shows some sample objects from the Product class hierarchy, which have been persisted.

Figure 6. Relational Representation of Product Hierarchy. The hierarchical representation of products has been flattened into a single relational table. Each row of the table contains all of the fields represented in the hierarchy. The type (or discriminator) is used to determine the underlying type of each row in the table.

In Figure 6, note that rows having a type of “A” represent Album objects while rows having a type of “V” represent Video objects. The length column is unnecessary and wasted on Album objects while the tracks column is unnecessary and waster on Video objects. This design trades off wasted space for the simplicity of only having one table to deal with.

Packaging and Deployment
As mentioned earlier in this article, each persistence unit is packaged into a single archive named a persistence archive. This archive includes the set of managed entity classes, their supporting metadata, and a named entity manger. All of these artifacts are included in the persistence archive, which is given the extension .par.

The classes and their accompanying metadata are stored in the PAR just as normal Java classes are stored in a JAR. The entity manager is specified and configured in a descriptor named persistence.xml. This descriptor is stored in the META-INF directory of the PAR just as an ejb-jar.xml file is stored in the META-INF directory of an EJB-JAR. The persistence.xml file for the music store example is shown below:

	musicStoreDB	java:/DefaultDS						

The name element specifies the name of the entity manager. This name corresponds to the unitName attribute of the @PersistenceContext annotation used to inject EntityManager instances. The jta-data-source element (and its twin the non-jta-data-source element) specifies the JNDI name of the JTA (or non-JTA) datasource to be used. In the case of JBoss the DefaultDS data source is provided by default. And you can optionally specify a non-default persistence provider through the provider element. For more information on configuring a persistence.xml file refer to the EJB 3.0 specification.

Additionally you can specify provider-specific properties in the properties section of this descriptor. Since by default JBoss uses Hibernate as its underlying persistence provider I have defined some Hibernate specific properties in this section. For more information on the specific properties that are allowable in this section consult the documentation for your persistence provider.

The .par file should be included in your application Enterprise Archive (EAR) file just as other J2EE modules are. Additionally you need to specify the .par in the application.xml file of your EAR. An sample from the music store example is shown below:

  music-store-deploy      music-store-domain-1.0-SNAPSHOT.ejb3        music-store-entity.par        music-store.aop              music-store-web.war      /music-store-web      

The music store example application uses Maven 2.0 as its build tool. The maven-ear-plugin builds this application.xml file automatically from the project metadata specified in the pom.xml file of the music-store-deploy project. For more information on this please download and consult the example source code accompanying this article.

In this article you have seen how to use the EJB 3.0 persistence API to persist Java objects to a relational data store. Specifically, you have seen how to use metadata annotations to map objects to relational entities, how to use the EntityManager to make objects persistent, and to retrieve persisted objects from the database.

Stayed tuned for my next article looking at how transaction management, security, and exception handling are addressed in EJB 3.0. I will also return to Enterprise Bean Components and show how callbacks and interceptors can be used to add additional functional to these components.

Share the Post:
Share on facebook
Share on twitter
Share on linkedin


Recent Articles: