Defining Your Object Model with JPA

In the perfect world, your object model would map seamlessly to your database schema. Most organizations however, have database naming standards, requirements for how relationships are modeled and columns that all tables must have.

The following example will show how to use JPA in a real-world scenario. You’ve been asked to quickly mock up a simple blog application; here are your constraints:

• All database table names are uppercase, words separated by an underscore (“_”)
• All table columns must start with the table name, or its initials
• All mutable tables need to track who created and updated a row and when the insert and update occurred
• Object relationships need to be managed intelligently
• You should use as few trips as possible to the database to make sure we can handle current and future load

The application should include the following objects:

• User
• Blog entry
• Comments
• The comments need to support nesting, so a user can reply to another’s comment, there is no limit to the nesting
• You need to list all users who start comment threads, comments without responses, etc.

Here is one possible object model:

Figure 1: Blog Object Model

ModelBase is an abstract superclass of three entities: BlogPost, Comment, and User. It also defines fields for who created and modified each entity and when the changes occurred. The nested comment requirement is taken care of by Comment’s parent and child relationships.

The database schema for the object model is:

Figure 2: Blog Entity Relationship Diagram

The database tables can be seen here:

The root object of the class hierarchy is ModeBase. The @Column annotation maps each field in ModelBase to a database table column. The problem is, ModelBase does not follow the database naming conventions listed above. This will be fixed with the concrete class definitions a little later. Here is ModelBase:

 1 import javax.persistence.*;
 2
 3 @MappedSuperclass
 4 @EntityListeners({ModelListener.class})
 5 public abstract class ModelBase {
 6
 7     @Id
 8     @GeneratedValue(strategy = GenerationType.IDENTITY)
 9     @Column(name="id")
10     private Long id;
11
12     @Version
13     @Column(name="version")
14     private Integer version;
15
16     @ManyToOne(fetch=FetchType.LAZY, cascade=CascadeType.ALL)
17     @JoinColumn(name="created_by_user_id")
18     private User createdByUser;
19
20     @Temporal(value = TemporalType.TIMESTAMP)
21     @Column(name = "date_created", nullable = false)
22     private Date dateCreated;
23
24     @ManyToOne(fetch=FetchType.LAZY)
25     @JoinColumn(name="updated_by_user_id")
26     private User updatedByUser;
27
28     @Temporal(value = TemporalType.TIMESTAMP)
29     @Column(name = "date_updated", nullable = false)
30     private Date dateUpdated;
31
32     // methods removed for readability
33 }

ModelBase uses the @MappedSuperclass annotation to tell the JPA persistence provide that this object is not an entity but it’s fields will be included in each entities table (for the entities that subclass ModelBase). You can use a mapped superclass to define all common fields. In this case it defines a field for optimist locking, version, primary key, id and fields for date created and updated. The second annotation, @EntityListener defines a class to be called by the JPA persistence provider at various lifecycle events. ModelListener, sets the user who created and modified each entity and when it was created and updated. Here is ModelListener:

 1 public class ModelListener {
 2
 3     @PrePersist
 4     public void setDatesAndUser(ModelBase modelBase) {
 5
 6         // set createdBy and updatedBy User information
 7         User currentUser = UserUtil.getCurrentUser();
 8
 9         // check to see if modelBase and currentUser are 
10         // the same, if so, make currentUser modelBase.
11         if (modelBase.equals(currentUser)) {
12             currentUser = (User) modelBase;
13         }
14
15         if (currentUser != null) {
16             if (modelBase.getCreatedByUser() == null) {
17                 modelBase.setCreatedByUser(currentUser);
18             }
19             modelBase.setUpdatedByUser(currentUser);
20         }
21
22         // set dateCreated and dateUpdated fields
23         Date now = new Date();
24         if (modelBase.getDateCreated() == null) {
25             modelBase.setDateCreated(now);
26         }
27         modelBase.setDateUpdated(now);
28     }
29 }

ModelListener has only one method, setDatesAndUser(ModelBase modelBase). This method is tied to the pre-persist entity lifecycle event and will always be called just before an entity is persisted to the database. This gives us a convenient way to set when and by whom the object is created and updated.

JPA requires that entity listeners be stateless and therefore we need a way to establish who the current user of our system is so we can set the createdByUser and updatedByUser fields. The UserUtil class uses a ThreadLocal to store the current user and provides an easy way for clients to establish the “current” user of the system.

 1 public class UserUtil {
 2
 3     private static ThreadLocal<User> currentUser =
 4         new ThreadLocal<User>();
 5
 6     public static void setCurrentUser(User user) {
 7         currentUser.set(user);
 8     }
 9
10     public static User getCurrentUser() {
11         return currentUser.get();
12     }
13 }

If you want to turn off any inherited entity listeners for a particular entity, you can use @ExcludeSuperclassListeners. This annotation does not have any elements, you add it to your entity like this:

1 @ExcludeDefaultListeners
2 public class Comment extends ModelBase implements Serializable

Now, Comment will not be passed to ModelListener when it’s persisted.

There are a couple of drawbacks to using entity listeners, most notably the lack of any lifecycle methods for the listener itself, it must be stateless, and it must have a public no-arg constructor. If you can live with these restrictions entity listeners are a good way to hook into the JPA entity lifecycle.

JPA also supports callback methods, these are methods in your object model class itself and must have the following method signature: void methodName(). Use the entity lifecycle event annotations (e.g. @PrePersist or @PostPersist) to indicate which event the callback method participates in. Here is an example of a callback method (continuing with the example of Comment turning off it’s entity listeners):

 1 @ExcludeDefaultListeners
 2 public class Comment extends ModelBase implements Serializable {
 3
 4     // code removed for readability 
 5
 6     @PrePersist
 7     public void setDates() {
 8         Date now = new Date();
 9         if (getDateCreated() == null) {
10              setDateCreated(now);
11         }
12         setDateUpdated(now);
13     }
14 }

By default, an entities table name is the same as the entity itself. In the case of BlogPost, the default table name would be BlogPost. To explicitly set the table name an entity is mapped to, use the @Table annotation. To change the column mappings defined in ModelBase, use @AttributeOverride. If you need to override more than one field, use the @AttributeOverrides (plural) annotation. Here is how you change the mappings:

1 @Entity
2 @Table(name = "BLOG_POST")
3 @AttributeOverrides( { @AttributeOverride(name = "id", column = @Column(name = "BP_ID")),
4     @AttributeOverride(name="version", column=@Column(name="BP_VERSION")),
5     @AttributeOverride(name="dateCreated", column=@Column(name="BP_DATE_CREATED")),
6     @AttributeOverride(name="dateUpdated", column=@Column(name="BP_DATE_UPDATED"))
7     })
8 public class BlogPost extends ModelBase implements Serializable {

The two remaining fields to remap from ModelBase are not attributes but associations, so you need to use a different set of annotations, @AssociationOverrides (plural) and @AssociationOverride. Here is how you rename the createdByUser and updatedByUser foreign key columns in the BlogPost entity:

1 @AssociationOverrides( {
2     @AssociationOverride(name="createdByUser",
3                joinColumns=@JoinColumn(name="BP_CREATED_BY_USER_ID")),
4
5     @AssociationOverride(name="updatedByUser",
6                joinColumns=@JoinColumn(name="BP_UPDATED_BY_USER_ID"))
7 })

As you can see, the @AssociationOverride annotation is a little be more complex than @AttributeOverride because it has a nested annotation, @JoinColumn.

As you can see in Figure 1, there are three more fields to be defined in BlogPost. Here is their definition:

1     @Lob
2     @Column(name = "BP_CONTENT")
3     private String content;
4
5     @Column(name="BP_TITLE")
6     private String title;
7
8     @Column(name = "BP_EDIT_COUNT")
9     private Integer editCount;

The @Lob annotation tells the persistence provider that content is bound to a large object type column. The @Column annotation defines the column name the content field is mapped to. Use the @Column annotation to map an entities field to a specific column name.

One last thing to look at is BlogPost’s relationship to Comment. Here is how the comments field is defined:

1     @OneToMany(cascade={CascadeType.PERSIST,CascadeType.MERGE},
2             fetch=FetchType.LAZY)
3     @Cascade(org.hibernate.annotations.CascadeType.DELETE_ORPHAN)
4     private List<Comment> comments = new ArrayList<Comment>();

The OneToMany annotation tells the persistence provider this is an association and not an attribute. The cascade element tells the persistence provider to persist or merge any comments associated with this instance when blog post is persisted or merged. Unfortunately, JPA does not provide a cascade type for managing orphaned deletes. Fortunately, the Hibernate team has created a set of Hibernate extension annotations to make managing relationships (and every other aspect of an entity) easier. The delete orphan cascade annotation lets Hibernate know it can delete a row from the comment table if a comment is removed from the comments list. Without this annotation, you would have to manually delete the removed comment.

There are two ways for the persistence provider to map a one-to-many relationship in the database. One is to use a join table (a unidirectional relationship) and the other is to have a foreign key column in the many side of the relationship (a bidirectional relationship). Given the BlogPost to Comment relationship, if you just defined the blog post to comment relationship as shown above, JPA should expect the following tables in the database:

Figure 3: Blog Post to Comment join table

You eliminate the join table, BlogPost_Comment, by defining a bidirectional relationship. To tell JPA this is a bidirectional relationship, you need to add the mappedBy element to the @OneToMany annotation like this:

1     @OneToMany(cascade={CascadeType.PERSIST,CascadeType.MERGE},
2             fetch=FetchType.LAZY, mappedBy="blogPost")
3     @Cascade(org.hibernate.annotations.CascadeType.DELETE_ORPHAN)
4     private List<Comment> comments = new ArrayList<Comment>();

The mappedBy element indicates the owning-side of the relationship, or the field in Comment that will hold a reference to BlogPost. Here is the comment side of the relationship:

1     @ManyToOne
2     @JoinColumn(name="COMMENT_BLOG_POST_ID")
3     private BlogPost blogPost;

By defining the post to comments relationship this way we eliminate the need for a join table.

The Comment entity has the same attribute and association overrides as BlogPost (mapping to different column names of course), however it has an interesting relationship to itself. Comments support nested comments, so a comment can contain a list of responses to itself. To create this relationship, Comment needs two fields, one for the collection of comments and another to represent the parent comment. Here is how the fields are defined:

1     @ManyToOne
2     @JoinColumn(name="COMMENT_PARENT")
3     private Comment parent;
4
5     @OneToMany(mappedBy="parent",
6             cascade={CascadeType.MERGE, CascadeType.PERSIST})
7     @OrderBy("dateCreated DESC")
8     private List<Comment> children = new ArrayList<Comment>();

These relationships are the same as any other one-to-many bidirectional relationship between BlogPost and Comment; the only difference is both sides of the relationship are in the same class. The parent field holds the primary key of the parent comment.

Now that you have the fields defined, you need to add methods to manage the relationship. Both sides of the relationship need to be set in order for the Comment entity to behave properly. To ensure the relationship is set up correctly the java bean property methods for children need to be slightly modified. Since the JPA annotations used in the Comment entity are field based, the JPA persistence provider does not use property accessor methods to set its state. This means we do not need the public void setChildren(List<Comment> children) method for the persistence provider. In addition, by removing this method clients of our model cannot directly set the collection. Next is the public List<Comment> getChildren() method; like setChildren() this method allows clients to directly modify a comments children. To fix this, make getChildren() return an immutable list, like this:

1     public List<Comment> getChildren() {
2         return Collections.unmodifiableList(children);
3     }

The final step is to define methods to add and remove child comments. Here is the method for adding child comments:

 1     public void addChildComment(Comment comment) {
 2         if (comment == null) {
 3             throw new IllegalArgumentException("child comment is null!");
 4         }
 5
 6         // check to see if comment has a parent
 7         if (comment.getParent() != null) {
 8             // if there is a parent check to see if it's already 
 9             // associated to this comment
10             if (comment.getParent().equals(this)) {
11                 // if this instance is already the parent, we can just return
12                 return;
13             }
14             else {
15                 // disconnect post from it's current relationship
16                 comment.getParent().children.remove(this);
17             }
18         }
19
20         // make this instance the new parent
21         comment.setParent(this);
22         children.add(comment);
23     }

If you want to add a remove comment method, it might look like this:

 1     public void removeChildComment(Comment comment) {
 2         if (comment == null) {
 3             throw new IllegalArgumentException("child comment is null!");
 4         }
 5
 6         // make sure we are the parent before we break the relationship
 7         if (comment.parent != null && comment.getParent().equals(this)) {
 8             comment.setParent(null);
 9             children.remove(comment);
10         }
11         else {
12             throw new IllegalArgumentException(
13                     "child comment not associated with this instance");
14         }
15     }

Not only does this method remove a comment from its parents children collection, it makes sure the parent of comment is this instance. If comment were not associated with this instance, removing it from children would have no affect. However, setting its parent to null would leave a dangling comment in the database.

The last two methods to deal with are getParent() and setParent() . Here is their definition:

1     public Comment getParent() {
2         return parent;
3     }
4
5     private void setParent(Comment parent) {
6         this.parent = parent;
7     }

The addChildComment() method uses setParent() , however; clients of the object model should not be able to change a comments parent. The easiest way to ensure this is to make setParent() private. getParent() is fine the way it is. The pattern used for Comments parent/child relationship can be applied to any bidirectional association in your object model.

Deciding where to put the relationship management methods in a bidirectional relationship is rather arbitrary since the purpose of the methods is to ensure the relationships are established correctly. With one-to-many bidirectional relationships, I tend to put the management methods on the “one” side. In the case of Comment this isn’t obvious, but in the BlogPost to Comment relationship I placed the relationship methods in BlogPost. This seems more natural; you add comments to a blog post, not the other way around. If you have a many-to-many relationship it really doesn’t matter which side has the methods so pick one and restrict the other side.

JPA provides methods for fetching entities by their primary key but it might be a good idea to provide some queries to fetch blog posts and comments by User, count the number of comments and blog posts a user has made, determine which comments do not have child comments, and find all root comments (those without a parent).

JPA provides three different types of queries, dynamic queries, static or named queries, and native queries. Dynamic and static queries use the Java Persistence Query Language and native queries use SQL. A dynamic query is one that is processed at runtime, meaning it is parsed and SQL generated every time it’s created. Static queries are processed when the persistence provider loads your object model. This means static queries are parsed once and reused every time you run the query.

To declare a named or static query, you use the @NamedQuery annotation. If you have more than one named query, you need to use the @NamedQueries annotation. Both annotations can be placed on an entity or mapped superclass and are declared at the class or type level. Query names are global, that is, they are not bound to any entity. As a result, you should use some sort of naming convention. One approach is to prefix every query name with the entity name it’s associated with.

Here are the named queries used in Comment and BlogPost:

 1 @NamedQueries({
 2     // select comments that do not have parent comments
 3     @NamedQuery(name = "comment.rootComments",
 4             query = "SELECT c FROM Comment c WHERE c.parent IS NULL"),
 5
 6     // select comments made by a User
 7     @NamedQuery(name = "comment.userComments",
 8             query = "SELECT c FROM Comment c WHERE c.createdByUser = :user"),
 9
10     // count the number of comments made by a user
11     @NamedQuery(name = "comment.userCount",
12             query = "SELECT COUNT(c) FROM Comment c WHERE c.createdByUser = :user"),
13
14     // select the comments a user made without responses
15     @NamedQuery(name = "comment.noChildren",
16             query = "SELECT c FROM Comment c WHERE c.children IS EMPTY AND c.parent IS NULL AND c.createdByUser = ?1")
17 })
18 public class Comment extends ModelBase implements Serializable{ ... }
19
20
21 @NamedQueries( {
22     @NamedQuery(name = "blogPost.createdByUser",
23             query = "SELECT p FROM BlogPost p WHERE p.createdByUser = ?1"),
24
25     // determine the number of posts a User has made
26     @NamedQuery(name = "blogPost.postCount",
27             query = "SELECT COUNT(p) FROM BlogPost p WHERE p.createdByUser = ?1"),
28
29     // fetch a blog post and eagerly fetch its comments
30     @NamedQuery(name = "blogPost.createdByUserComments",
31             query = "SELECT p FROM BlogPost p JOIN FETCH p.comments as c WHERE p.createdByUser = ?1")
32 })
33 public class BlogPost extends ModelBase implements Serializable { ... }

Each of the above queries uses either positional or named parameters; positional parameters use the “?1” syntax and named parameters use the “:name” syntax. Here is how you would create and execute a static query which uses named parameters:

1 // assume entityManager exists
2 User user = UserUtil.getCurrentUser();
3
4 // Here is the definition of comment.userComments for reference
5 // SELECT c FROM Comment c WHERE c.createdByUser = :user 
6
7 Query q = entityManager.createNamedQuery("comment.userComments");
8 q.setParameter("user", user);
9 List results = q.getResultList();

Another query using positional parameters (note: the count function returns a Long):

1 // assume entityManager exists
2 User user = UserUtil.getCurrenstUser();
3
4 // Here is the definition of blogPost.postCount for reference
5 // SELECT COUNT(p) FROM BlogPost p WHERE p.createdByUser = ?1
6
7 Query q = entityManager.createNamedQuery("blogPost.postCount");
8 q.setParameter(1, user);
9 Long result = (Long) q.getSingleResult();

The JPQL has many built in functions and expressions to assist you in working with your object model. If you have not checked out JPQL before, you might be surprised by how powerful it is.

The last query to look at is blogPost.createdByUserComments. This query uses the fetch join operator to eagerly fetch a blog posts’ comments. The BlogPost to Comment association is defined as being LAZY (here is the relationship again):

1     @OneToMany(cascade={CascadeType.PERSIST,CascadeType.MERGE},
2             fetch=FetchType.LAZY, mappedBy="blogPost")
3     @Cascade(org.hibernate.annotations.CascadeType.DELETE_ORPHAN)
4     private List<Comment> comments = new ArrayList<Comment>();

Making the relationship LAZY (by setting the fetch element of the @OneToMany annotation to FetchType.LAZY) enables your application to fetch a blog post, say when a user wants to edit the post, without also fetching all the comments. When you want to fetch the blog post and its comments, you can use the named query, blogPost.createdByUserComments. Sometimes you will want to make a relationship eager, by setting the fetch element of the @OneToMany annotation to FetchType.EAGER, so when you fetch entity “A” the persistence provider will also fetch entity “B”. Having one fetch to get back several objects is more efficient than multiple trips to the database but you will need to decide the correct semantics for each collection in your object model.

If you haven’t looked at JPA before, I hope this short example will encourage you to give it a try. Hibernate’s latest release has excellent JPA support and provides an extensive set of JPA extension annotations.

Get the Source Code here.