JPA Transitive Persistence for the Play Framework

In play framework 1.x the JPA persistency model has been changed in a dramatic way. JPA as a standard is all about transitive persistence. That means, within a JPA transaction, any change to any object that is managed by the EntityManager will result in propagation of these changes into the database, that means the transitive hull of the loaded reachable object graph is traversed (considering Cascade annotation), then compared to the loaded state and then the full delta is committed to the DB. It is all happening implicitly. The easiness of this automatism is an achievement which took the Java Enterprise world quite some time.

Play now, on the other hand, tries to resemble the logic found in web frameworks like Ruby on Rails, where the save operation is an explicit operation. You will need to call save on any object whose changes you want to propagate to the database. Play has implemented a cascade when the corresponding JPA annotation is present so you don’t need to call save() on all of them but even this solution is not complete, which I wrote about in Beware of this: play framework’s cascaded save() only works on loaded collections.

To be honest, I don’t like play’s (or RoR’s) approach. The logic behind it is, that you can make changes to as many objects you want and if an error occurs somewhere down the logic, you will not need to undo the changes that you made before the error occurred. The same can be accomplished by just not committing the running JPA transaction (i.e., rolling it back). In a J2EE environment, you just don’t want to control the transactions yourself. The JPA hack in play makes it necessary to do exactly that. If you are in a non-trivial environment, where you need to manage more complex object models you don’t want to mess up with the transaction which demarcates the unit of work! Some logic might apply changes which result in changes in the reachable object graph. The programmer of that logic doesn’t necessarily need to know that perhaps the initial change will ripple through to other objects. We call that encapsulation, and that is broken by play’s approach.

Long story short, in order to circumvent that, I created a module that brings the original JPA behavior of transitive persistence back to play. The API is exactly the same as in original play with the exception that it is necessary to inherit the model classes from a different base class. Instead of calling save on every changed object it is only necessay to call persist() on newly created objects. Every other change is handled by the transitive persistence logic of JPA just as it was originally intended.

The module is not publicly available, but I’ve been using it successfully in all my play projects. I just wanted to let you know about it and of course will I make it available (in github) if people ask for it. So, if you want the real JPA back in play, drop me a note and I will publish it.

Advertisements

Play module “associations” 1.0 released

Today I have released version 1.0 of the play [associations] module. I would like to elaborate a bit more on the rationale for this module.

Imagine the following simple model:

public class Forum {
    @OneToMany(cascade=CascadeType.ALL, mappedBy="forum")
    public List<Post> posts;
} 
public class Post {
    @ManyToOne
    public Forum forum;
}

Before the Module

In model management there are 3 phases, creation, manipulation and deletion. Under normal conditions (read play without associations module) these would be implemented like this:

1. Object creation and association creation

Forum forum = new Forum();
Post post = new Post();
forum.posts.add(post);
post.forum = forum; // don't forget this
forum.save(); // using CascadeType.ALL etc. this will cascade

2. Manipulation of existing objects

Post post = ...
post.forum.posts.remove(post); // don't forget this
Forum forum2 = new Forum();
forum2.posts.add(post);
post.forum = forum2; // don't forget this
forum2.posts.add(post);
forum.save(); // cascades
forum2.save(); // cascades

3. Deletion of objects

// this can be accomplished using
public class Forum {
  @OneToMany(cascade = CascadeType.ALL, orphaneRemoval = true)
  public List&lt;Post&gt; posts;
}
Post post = ...
post.forum.posts.remove(post);
post.forum = null; // don't forget this
forum.save();

With the Module

Now fast forward to an implementation *with* the associations module, this all gets much easier and intuitive to write:

1. Object creation and association creation

Forum forum = new Forum();
Post post = new Post();
forum.posts.add(post);
forum.save(); // using CascadeType.ALL etc. this will cascade

2. Manipulation of existing objects

Post post = ...
Forum forum2 = new Forum();
forum2.posts.add(post);
forum.save(); // cascades
forum2.save(); // cascades

3. Deletion of objects

Post post = ...
post.forum = null;
forum.save();

IMO this is much more intuitive. If you add a post to a forum, you’d expect that the previous forum does not reference it any more, wouldn’t you? Also, if you make a change on one side, you’d expect that the corresponding change on the other side is also made, wouldn’t you?

And this is exactly what this module provides, complete management of all JPA two-sided associations.

Transparent Bi-directional Associations in Play

Do you find writing code like this cumbersome and error prone?

forum1.posts.remove(post);
post.forum = forum2;
forum2.posts.add(post);

Wouldn’t it be much easier if you could just write

post.forum = forum2;

and the system handles all the wiring and rewiring for you? With the benefit of eliminating errors like “detached entity passed to persist” and such?

I have created a play module that does just that. Whenever you invoke one of the operations that changes a part of the association from whichever side, then the module completes this operation on all other affected parts. This includes not only the new target and its opposite reference, but it also manages to unlink a target object from its current associated object. All hassle free and safe. It works on @OneToOne, @OneToMany and @ManyToMany associations.

There are no dependencies introduced in your code. The module enhancer works on all properties of your @Entity classes having a “mappedBy” attribut on the @OneToOne, @OneToMany or @ManyToMany annotation. You do not need to declare anything else. The presence of the module is sufficient.

You can check it out at https://github.com/pareis/associations and as soon as available in the play modules repository.

Beware of this: play framework’s cascaded save() only works on loaded collections

I am currently developing a web application using the really excellent play framework. If you are a web developer with some Java background I strongly encourage you to give it a try.

However, play has taken a little different or let’s better call it an additional approach to control object synchronizations with the underlying database. Whereas JPA manages a loaded object graph and automatically persists any changes upon transaction completion, play has changed this behavior (“Explicit save”) to give the beginner more control over what is going on with the objects. This extension turns the implicit save mechanism into an explicit one where the developer is in control to call save() on the changed objects. This save() will in turn cascade (if for instance the CascadeType.ALL annotation option is present) to the reachable objects.

This might in the first place seem clever because you get control back but I have mixed feelings about it because there are cases where it does just not work as easily as expected.

As an example, imagine a 3-level parent-child object model.

@Entity
public class Item extends Model {

 @OneToMany(cascade = CascadeType.ALL, orphanRemoval=true, mappedBy="item")
       @OrderBy("createdAt")
 public List<Position> positions = new ArrayList<Position>();
}

@Entity
public class Position extends Model {

 public Date createdAt = new Date();
 public int quantity;

 @ManyToOne public Item item;

 @OneToMany(cascade = CascadeType.ALL, orphanRemoval=true, mappedBy="position")
 @OrderBy("createdAt")
 public List<Order> orders = new ArrayList<Order>();
}

@Entity @Table(name="Ordr")
public class Order extends Model { 
 public Date createdAt = new Date();
 public int quantity;

 @ManyToOne public Position position;
}

So far nothing complicated. But now imagine you are loading (for performance reasons) objects from the lowest level (Order) and manipulate the parent object (i.e., the Position).

public void dostuff(Item item) {

 // load orders according to some important criteria
 List<Order> orders = Order.find("position.item = ? order by createdAt", item).fetch();

 // manipulate the parent of the order (the Position)
 Order order = extractImportantOne(orders);
 order.position.quantity += 200;

 item.save();
}

Intuitively I would assume that the manipulated Position object is updated in the database through the Item.positions cascade settings. But this is not the case here! The reason is that the collection Item.positions has not been populated from the database. Thus, play sees an unintialized PersistentCollection and will simply ignore to cascade.

One solution to the problem would be to touch the cascading collection:

 item.positions.size();
 item.save();

This will make sure the ‘positions’ collection will be considered during the following call to save(). With pure JPA on the other hand, such a call to do the trick would never be necessary and also the call to save() could be avoided, because JPA knows all loaded and changed objects and automatically updates the database.

This is why I have very mixed feelings about play’s extended persistence API. It works well in simple cases but for more complex models it might be better to switch back to plain JPA mode.