JPA implementation patterns

Sky-Tiger

The simple solution

To remedy this problem, we also have to remove the OrderLine from the Order.orderLines set. That sounds awfully familiar... In fact, when managing bidirectional associations we also had to make sure both sides of the association were in a consistent state. And that means we can reuse the pattern we used there. By adding an invocation of orderLineToRemove.setOrder(null); to the test it will succeed:

OrderLine orderLineToRemove = orderLineDao.findById(someOrderLineId);
Order parentOrder = orderLineToRemove.getOrder();
int sizeBeforeRemoval = parentOrder.getOrderLines().size();
orderLineToRemove.setOrder(null);
orderLineDao.remove(orderLineToRemove);
assertEquals(sizeBeforeRemoval - 1, parentOrder.getOrderLines().size());

Sky-Tiger

The pattern

But doing it like this makes our code brittle as it depends on the users of our domain objects to invoke the right methods. The DAO should be responsible for this. A very nice way to solve this problem is to use the @PreRemove entity lifecycle hook like this:

@Entity
public class OrderLine {
        [...]

        @PreRemove
        public void preRemove() {
                setOrder(null);
        }
}

Now we can just invoke OrderLineDao.remove() to get rid of an unwanted OrderLine object.

Originally this blog suggested introducing a HasPreRemove interface with a preRemove method that would be invoked by the DAO. But Sakuraba commented below that the @PreRemove annotation is just the thing we need here. Thanks again, Sakuraba!

Sky-Tiger

Removing orphans

But what, you ask, would happen if we were to just remove the OrderLine from the Order.orderLines set like so:

Order parentOrder = orderLineToRemove.getOrder();
parentOrder.removeOrderLine(orderLineToRemove);

?

The OrderLine would indeed be removed from the Order.orderLines set. And not just in this transaction. If we retrieve the Order object again in a new transaction, the removed OrderLine still would not show up. But if we were to look in the database, we would see that the OrderLine is still there. It just has its OrderLine.order field set to null. What we are seeing here is an "orphaned" set element. There are two ways to solve this problem:

    * Explicitly remove the OrderLine object as we discussed above.
    * If you are using Hibernate as your JPA provider, you can let Hibernate remove these orphans automatically. Add a org.hibernate.annotations.Cascade annotation with a value of a org.hibernate.annotations.CascadeType.DELETE_ORPHAN next to the @OneToMany for which you want Hibernate to do this. See the Hibernate documentation for an example.

While the second solution is vendor-specific it does have the nice feature of not requiring your code to invoke a DAO remove method every time you remove an entity from a set. But to make it obvious you are using a vendor specific extension, you should refer to those annotations using the full package name (as Java Persistence with Hibernate suggests too):

@OneToMany(mappedBy = "order", cascade = CascadeType.ALL)
@org.hibernate.annotations.Cascade(org.hibernate.annotations.CascadeType.DELETE_ORPHAN)
private Set<OrderLine> orderLines = new HashSet<OrderLine>();

Please note that CascadeType.ALL does not include the DELETE_ORPHAN cascade type. That's why the example here explicitly sets it.

So we can conclude that removing entities is simple unless you are dealing with associations. In that case you need to take extra precautions to make sure the entity is removed from any objects referring to it and from the database at the same time. See you at the next blog! In the meantime, please drop any remarks in the comment section below.

P.S. If you will be attending J-Spring next week, come and join my talk about this subject from 14:25 until 15:15 (it'll be in Dutch though). Or find me somewhere at the conference to talk about JPA. I'll probably be hovering around the Xebia booth. :-)

Sky-Tiger

In my previous blog on JPA implementation patterns, I touched upon the subject of the DTO and Service Facade patterns. In this blog I will explore why we would even need such patterns and put these patterns and the DAO pattern into the broader context of JPA application architecture.

If there is one thing that I learned when implementing JPA for the first time is that some of the "old school" enterprise application architecture patterns still apply, even though some people have proclaimed them to be no longer necessary:

    * The DAO has been declared dead because you might just as well invoke the EntityManager directly. It provides a nice enough interface and switching from JPA to a different persistence implementation is not something the DAO abstraction would make much easier.
    * DTO's have been deemed superfluous because you can also use your domain objects directly in the presentation layer. This is made possible by a combination of the open EntityManager in view pattern, tag libraries to display your domain objects in JSP's and data-binding utilities to map HTTP request parameters back to domain objects.
    * And finally Service Facades also seem to have gone out of fashion. Instead you can have the controller directly invoke the services it needs or, even simpler, directly contain the business logic.

The resulting application architecture will look something like this diagram of the Spring Web MVC application architecture:
Spring Web MVC application architecture

Sky-Tiger

So why bother with DAO's, DTO's and Service Facades?

I've already argued why the DAO pattern is still relevant in JPA application architecture. A similar argument can be made for the DTO and Service Facade patterns. While the DTO-less and Service Facade-less architecture displayed above works quite well for straight forward web applications, it has two major drawbacks:

    * If you wish to expose your application to other non-HTML clients (think of web services using SOAP, Flex frontends using AMF or Ajax applications using JSON), you will need a more clearly defined interface. That interface specifies which services get exposed to the client and what types are used as the input and output. Service Facades and DTO's respectively help you define this interface.
    * Using domain objects directly in the presentation layer requires those domain objects to expose all their fields as public properties with getters and setters. If the fields are not exposed as such, the tag libraries won't be able to render them and the data binding code won't be able to set them. As Allen Holub has already argued before, getters and setters are evil. (BTW, some people interpret Holub's article as an excuse to make all fields public. The article is saying that public getters and setters are no better, but that does not mean your code should just have public fields. Instead the article is advocating use of the tell, don't ask approach to OO.)

In fact the reason I found out why Service Facades and DTO's are still useful, is that the application my team and I are developing has a Flex frontend and a command-line interface that communicate to the core using AMF and Hessian respectively. The only HTML code our application produces loads the SWF file for the Flex frontend! We started out without DAO's, DTO's and Service Facades as one would do, but added them all to our architecture to make this work. And we got a well defined interface between the service layer and the presentation layer as an added bonus.

Sky-Tiger

Pros and cons of DTO's

Of course it would be silly to say you should always use DTO's in your architecture. As always it depends. :-) To allow you to make up your own mind, I will list a number of pros and cons of using DTO's:

    * Con: DTO's cause code duplication. This is especially the case when your DTO's have exactly the same fields as your domain objects, and even more so when they both have getters and setters for those fields. But having DTO's in your architecture allows you to get rid of the getters and setters in your domain objects.
    * Con: DTO's require you to write boilerplate code to copy properties back and forth. Some people have suggested using a Java Bean mapper framework such as Dozer, Apache Commons BeanUtils, or the Spring Framework's BeanUtils class, but that requires you add getters and setters to your beans and we just decided we did not want to do that anymore!
    * Pro/Con: DTO's make it impossible to use EntityManger.merge to copy their state to your persistent objects. Instead you'll have to apply the DIY merge pattern as described in my blog on saving (detached) entities. Of course forcing you to do something a particular way, and one that is not 100% satisfying, is not really an advantage. But at least the DTO and the DIY merge work well together.
    * Pro: DTO's ensure you are not hit by unexpected lazy loading problems in your presentation layer. Or in the case of remote invocations they protect you from lazy loading problems when serializing for transport or, even stranger, on the client.
    * Pro: The DTO pattern forces you to think about the interface of your application. You can make your DTO's richer than your plain domain objects, e.g. by adding security information to them. Or you can group information from multiple domain objects into one DTO to make the interface easier to use.

Before we move on to discuss Service Facades, it might be worth to have a look at Anirudh Vyas's blog on common abuses of the DTO pattern.

Sky-Tiger

Pros and cons of Service Facades

Just like is the case with DTO's, there are cases when Service Facades make a lot of sense and there are cases when they just add meaningless overhead. Let's have a look at some pros and cons:

    * Con: Service Facades add an extra layer that does not do much apart from delegate to the actual service. This argument appeals especially to Java EE developers that have bad memories of the EJB 1.0 based multi-tier architectures we set up in the beginning of this century. ;-)
    * Pro: Service Facades can (should!) be made responsible for mapping from DTO's to domain objects and back. Service Facades are invoked with DTO's as arguments, map them to domain objects, invoke the actual service (or services), map the result back to DTO's and return those DTO's to the client. Actually, to make sure your Service Facades only adhere to Single Responsibility Principle, you should factor the mapping logic out to separate DTO2DOMapper and DO2DTOMapper classes.
    * Pro: Service Facades can function as the transaction boundary of your application, i.e. a transaction is started for the duration of a request to the Service Facade. Instead of having to define the transaction attributes of all your services, you can assume that all service invocation arrive through the Service Facade. Actually, setting your Service Facade to be the transaction boundary is obligatory when you want to invoke more than one service during the handling of one request or when you want the Service Facade to map lazily loaded domain objects to DTO's. In that case you end with something akin to the open EntityManager in view pattern; a transaction is started that lasts from the moment the incoming DTO's are translated to domain objects to the moment the resulting DTO's are returned to the client. (BTW, if you want to enforce that all services invocations go through the Service Facade you can set their transaction attribute to MANDATORY. If a transaction hasn't already been started when such a service is invoked, an exception is thrown)
    * Pro: The Service Facade pattern forces you to think about the interface of your application. Instead of letting the client invoke all your services, you get to decide which ones to actually expose.

Hmm, I can't seem to think of many disadvantages to the Service Facade pattern. ;-) Apart from the "overhead" argument and that is a subjective thing. Feel free to add more cons of this pattern to the comment section!

Sky-Tiger

Impact on application architecture

If we apply the DAO, DTO and Service Facade patterns, we end up with a JPA application architecture that looks like this:
application_architecture_with_dtos_and_service_facade

When a request is made, the sequence of events goes something like this:

   1. A service client sends a request to the service facade. All objects sent are DTO's.
   2. A transaction is started.
   3. The service facade invokes the DTO2DOMapper to map the incoming DTO's to domain objects. The DTO2DOMapper may invoke one or more DAO's to load domain objects from the database.
   4. The service facade invokes one or more services to perform actual business logic.
   5. The service facade passes the return values to the DO2DTOMapper and gets DTO's back. The DO2DTOMapper may invoke one or more services or DAO's to enrich the DTO's.
   6. The transaction is committed. Or rolled back in case an exception has occurred.
   7. The service facade passes the DTO's to client.
   8. The service client receives the DTO's.

Sky-Tiger

When a request is made, the sequence of events goes something like this:

   1. A service client sends a request to the service facade. All objects sent are DTO's.
   2. A transaction is started.
   3. The service facade invokes the DTO2DOMapper to map the incoming DTO's to domain objects. The DTO2DOMapper may invoke one or more DAO's to load domain objects from the database.
   4. The service facade invokes one or more services to perform actual business logic.
   5. The service facade passes the return values to the DO2DTOMapper and gets DTO's back. The DO2DTOMapper may invoke one or more services or DAO's to enrich the DTO's.
   6. The transaction is committed. Or rolled back in case an exception has occurred.
   7. The service facade passes the DTO's to client.
   8. The service client receives the DTO's.

In fact, if you take this diagram and replace "DTO2DOMapper" with "Data binding", "DO2DTOMapper" with "View rendering", and "Service Facade" with "Front Controller", you get the original Web MVC architecture we started out with. The big difference is that the incoming "DTO's" are request parameters while the outgoing "DTO's" are HTML:
application_architecture_with_dispatcher_servlet

That makes this blog come full circle, so now is a good time to wrap up. :-) As you can see there is no clear-cut answer to whether or not to use DTO's and Service Facades. It all depends on what you are trying to achieve with your application, for example:

    * Will it be a straight HTML application or will you want to expose it over different protocols?
    * How tightly coupled do you want your clients and your services to be?
    * Do you want your domain objects to not have any getters and setters?

I am very interested to hear what you guys think about the validity of these patterns in modern Java EE architecture. When would you apply then? Or when not and why not? See you all at the next blog in which I will try and tackle the subject of how to handle inheritance in JPA.

P.S. Last week I gave a presentation on this subject to the guys at info.nl and they provided me with some interesting feedback that helped shape this blog. Thanks for that guys!

Sky-Tiger

The setup

Let's start by expanding the Order example from the previous blog with an OrderLine object. It has an id, a description, a price, and a reference to the order that contains it:

@Entity
public class OrderLine {
        @Id
        @GeneratedValue
        private int id;

        private String description;

        private int price;

        @ManyToOne
        private Order order;

        public int getId() { return id; }
        public void setId(int id) { this.id = id; }

        public String getDescription() { return description; }
        public void setDescription(String description) { this.description = description; }

        public int getPrice() { return price; }
        public void setPrice(int price) { this.price = price; }

        public Order getOrder() { return order; }
        public void setOrder(Order order) { this.order = order; }
}

Using the generic DAO pattern, we quickly get ourselves a very basic OrderLineDao interface and an implementation:

public interface OrderLineDao extends Dao<Integer, OrderLine> {
        public List<OrderLine> findOrderLinesByOrder(Order o);
}

public class JpaOrderLineDao extends JpaDao<Integer, OrderLine> implements
                OrderLineDao {

        public List<OrderLine> findOrderLinesByOrder(Order o) {
                Query q = entityManager.createQuery("SELECT e FROM "
                                + entityClass.getName() + " e WHERE order = ";
                q.setParameter("o", o);
                return (List<OrderLine> q.getResultList();
        }
}

We can use this DAO to add a orderline to an order, or to find all the order lines for an order:

        OrderLine line = new OrderLine();
        line.setDescription("Java Persistence with Hibernate";
        line.setPrice(5999);
        line.setOrder(o);
        orderLineDao.persist(line);

        Collection<OrderLine> lines = orderLineDao.findOrderLinesByOrder(o);