The best way to map a @OneToMany relationship with JPA and Hibernate

(Last Updated On: January 4, 2018)

Introduction

In a relational database system, a one-to-many association between links two tables based on a Foreign Key column so that the child table record references the Primary Key of the parent table row.

As straightforward as it might be in a RDBMS, when it comes to JPA, the one-to-many database association can be represented either through a @ManyToOne or a @OneToMany association since the OOP association can be either unidirectional or bidirectional.

The @ManyToOne annotation allows you to map the Foreign Key column in the child entity mapping so that the child has an entity object reference to its parent entity. This is the most natural way of mapping a database one-to-many database association, and, usually, the most efficient alternative too.

For convenience, to take advantage of the entity state transitions and the dirty checking mechanism, many developers choose to map the child entities as a collection in the parent object, and, for this purpose, JPA offers the @OneToMany annotation.

As I explained in my book, many times, you are better off replacing collections with a query, which is much more flexible in terms of fetching performance. However, there are times when mapping a collection is the right thing to do, and then you have two choices:

  • a unidirectional @OneToMany association
  • a bidirectional @OneToMany association

The bidirectional association requires the child entity mapping to provide a @ManyToOne annotation, which is responsible for controlling the association.

One the other hand, the unidirectional @OneToMany association is simpler since it’s just the parent-side which defines the relationship. In this article, I’m going to explain the caveats of @OneToMany associations, and how you can overcome them.

There are many ways to map the @OneToMany association. We can use a List or a Set. We can also define the @JoinColumn annotation too. So, let’s see how all these work.

Unidirectional @OneToMany

Consider we have the following mapping:

@Entity(name = "Post")
@Table(name = "post")
public class Post {

    @Id
    @GeneratedValue
    private Long id;

    private String title;

    @OneToMany(
        cascade = CascadeType.ALL, 
        orphanRemoval = true
    )
    private List<PostComment> comments = new ArrayList<>();

    //Constructors, getters and setters removed for brevity
}

@Entity(name = "PostComment")
@Table(name = "post_comment")
public class PostComment {

    @Id
    @GeneratedValue
    private Long id;

    private String review;

    //Constructors, getters and setters removed for brevity
}

Now, if we persist one Post and three PostComment(s):

Post post = new Post("First post");

post.getComments().add(
    new PostComment("My first review")
);
post.getComments().add(
    new PostComment("My second review")
);
post.getComments().add(
    new PostComment("My third review")
);

entityManager.persist(post);

Hibernate is going to execute the following SQL statements:

insert into post (title, id) 
values ('First post', 1)

insert into post_comment (review, id) 
values ('My first review', 2) 

insert into post_comment (review, id) 
values ('My second review', 3)

insert into post_comment (review, id) 
values ('My third review', 4)

insert into post_post_comment (Post_id, comments_id) 
values (1, 2)

insert into post_post_comment (Post_id, comments_id) 
values (1, 3)

insert into post_post_comment (Post_id, comments_id) 
values (1, 4)

What is that! Why there are so many queries executed? And what’s the deal with that post_post_comment table anyway?

Well, by default, that’s how the unidirectional @OneToMany association works, and this is how it looks from a database perspective:

For a DBA, this looks more like a many-to-many database association than a one-to-many relationship, and it’s not very efficient either. Instead of two tables, we now have three tables, so we are using more storage than necessary. Instead of only one Foreign Key, we now have two of them. However, since we are most likely going to index these Foreign Keys, we are going to require twice as much memory to cache the index for this association. Not nice!

Unidirectional @OneToMany with @JoinColumn

To fix the aforementioned extra join table issue, we just need to add the @JoinColumn in the mix:

@OneToMany(cascade = CascadeType.ALL, orphanRemoval = true)
@JoinColumn(name = "post_id")
private List<PostComment> comments = new ArrayList<>();

The @JoinColumn annotation helps Hibernate (the most famous JPA provider) to figure out that there is a post_id Foreign Key column in the post_comment table that defines this association.

With this annotation in place, when persisting the three PostComment entities, we get the following SQL output:

insert into post (title, id) 
values ('First post', 1)

insert into post_comment (review, id) 
values ('My first review', 2)

insert into post_comment (review, id) 
values ('My second review', 3)

insert into post_comment (review, id) 
values ('My third review', 4)

update post_comment set post_id = 1 where id = 2

update post_comment set post_id = 1 where id =  3

update post_comment set post_id = 1 where id =  4

A little bit better, but what’s the purpose of those three update statements?

If you take a look at Hibernate flush order, you’ll see that the persist action is executed before the collection elements are handled. This way, Hibernate inserts the child records first without the Foreign Key since the child entity does not store this information. During collection handling phase, the Foreign Key column is updated accordingly.

The same logic applies to collection state modifications, so when removing the firsts entry from the child collection:

post.getComments().remove(0);

Hibernate executes two statements instead of one:

update post_comment set post_id = null where post_id = 1 and id = 2

delete from post_comment where id=2

Again, the parent entity state change is executed first, which triggers the child entity update. Afterward, when the collection is processed, the orphan removal action will execute the child row delete statement.

So, is a java.util.Set any different?

No, it’s not. The same statements are executed if you use the @JoinColumn annotation on a unidirectional @OneToMany Set association.

Bidirectional @OneToMany

The best way to map a @OneToMany association is to rely on the @ManyToOne side to propagate all entity state changes:

@Entity(name = "Post")
@Table(name = "post")
public class Post {

    @Id
    @GeneratedValue
    private Long id;

    private String title;

    @OneToMany(
        mappedBy = "post", 
        cascade = CascadeType.ALL, 
        orphanRemoval = true
    )
    private List<PostComment> comments = new ArrayList<>();

    //Constructors, getters and setters removed for brevity

    public void addComment(PostComment comment) {
        comments.add(comment);
        comment.setPost(this);
    }

    public void removeComment(PostComment comment) {
        comments.remove(comment);
        comment.setPost(null);
    }
}

@Entity(name = "PostComment")
@Table(name = "post_comment")
public class PostComment {

    @Id
    @GeneratedValue
    private Long id;

    private String review;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "post_id")
    private Post post;

    //Constructors, getters and setters removed for brevity

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof PostComment )) return false;
        return id != null && id.equals(((PostComment) o).id);
    }
    @Override
    public int hashCode() {
        return 31;
    }
}

There are several things to note on the aforementioned mapping:

  • The @ManyToOne association uses FetchType.LAZY because, otherwise, we’d fall back to EAGER fetching which is bad for performance.
  • The parent entity, Post, features two utility methods (e.g. addComment and removeComment) which are used to synchronize both sides of the bidirectional association. You should always provide these methods whenever you are working with a bidirectional association as, otherwise, you risk very subtle state propagation issues.
  • The child entity, PostComment, implement the equals and hashCode methods. Since we cannot rely on a natural identifier for equality checks, we need to use the entity identifier instead. However, you need to do it properly so that equality is consistent across all entity state transitions. Because we rely on equality for the removeComment, it’s good practice to override equals and hashCode for the child entity in a bidirectional association.

If we persist three PostComment(s):

Post post = new Post("First post");

post.addComment(
    new PostComment("My first review")
);
post.addComment(
    new PostComment("My second review")
);
post.addComment(
    new PostComment("My third review")
);

entityManager.persist(post);

Hibernate generates just one SQL statement for each persisted PostComment entity:

insert into post (title, id) 
values ('First post', 1)

insert into post_comment (post_id, review, id) 
values (1, 'My first review', 2)

insert into post_comment (post_id, review, id) 
values (1, 'My second review', 3)

insert into post_comment (post_id, review, id) 
values (1, 'My third review', 4)

If we remove a PostComment:

Post post = entityManager.find( Post.class, 1L );
PostComment comment1 = post.getComments().get( 0 );

post.removeComment(comment1);

There’s only one delete SQL statement that gets executed:

delete from post_comment where id = 2

So, the bidirectional @OneToMany association is the best way to map a one-to-many database relationship when we really need the collection on the parent side of the association.

Just @ManyToOne

Just because you have the option of using the @OneToMany annotation, it does not mean this should be the default option for every one-to-many database relationship. The problem with collections is that we can only use them when the number of child records is rather limited.

Therefore, in reality, @OneToMany is practical only when many means few. Maybe @OneToFew would have been a more suggestive name for this annotation.

As I explained in this StackOverflow answer, you cannot limit the size of a @OneToMany collection like it would be the case if you used query-level pagination.

Therefore, most of the time, the @ManyToOne annotation on the child side is everything you need. But then, how do you get the child entities associated with a Post entity?

Well, all you need is just a single JPQL query:

List<PostComment> comments = entityManager.createQuery(
    "select pc " +
    "from PostComment pc " +
    "where pc.post.id = :postId", PostComment.class)
.setParameter( "postId", 1L )
.getResultList();

Which translates to a straightforward SQL query:

select pc.id AS id1_1_,
       pc.post_id AS post_id3_1_,
       pc.review AS review2_1_
from   post_comment pc
where  pc.post_id = 1

Even if the collection is not managed anymore, it’s rather trivial to just add/remove child entities whenever necessary. As for updating child objects, the dirty checking mechanism works just fine even if you don’t use a managed collection. What’s nice about using a query is that you can paginate it any way you like so that, if the number of child entities grows with time, the application performance is not going to be affected.

If you enjoyed this article, I bet you are going to love my book as well.

Conclusion

As you will see in a future article, bidirectional collections are way better than unidirectional ones because they rely on the @ManyToOne association, which is always efficient in terms of generated SQL statements.

But then, even if they are very convenient, you don’t always have to use collections. The @ManyToOne association is the most natural and also efficient way of mapping a one-to-many database relationship.

Subscribe to our Newsletter

* indicates required
10 000 readers have found this blog worth following!

If you subscribe to my newsletter, you'll get:
  • A free sample of my Video Course about running Integration tests at warp-speed using Docker and tmpfs
  • 3 chapters from my book, High-Performance Java Persistence, 
  • a 10% discount coupon for my book. 
Get the most out of your persistence layer!

Advertisements

48 thoughts on “The best way to map a @OneToMany relationship with JPA and Hibernate

  1. Hi and thank you for another great article!

    One question still remains; let’s say we have Aggregate root which should be persisted using dedicated repository (like in Spring JPA) and we would like to have unidirectional OneToMany association under the Aggregate root (so One-Aggregate-root-to-Many-children). Is it possible? Or must we resort to bidirectional association?

    1. It’s possible to have that, but not very efficient. There is no reason why you shouldn’t use a bidirectional association. You can make the getter/setter for the @ManyToOne side package-private so to avoid exposing them if that’s your concern.

      1. Thanks for reply, actually I was bit concerned from the OO modelling perspective; every assocation isn’t necessarily bidirectional, but after reading this article it is more clear that is all about DB / impedance michmatch

        If you can still answer follow-up question that would be nice. In DDD (and with Spring JPA) we have Aggregate roots, which should be the “top” object to persist to dedicated repository. Now with unidirectional ManyToOne this isn’t the case, but it is vice-versa (so one ends up with child-repository). Or have I misunderstood? Is there anything that can be done with it?

      2. If you want to use the parent entity aggregate, just map the bidirectional association. You can hide the @ManyToOne side with Java access modifiers. It will work efficiently and resemble a unidirectional association which is what you wanted in the first place.

  2. Hi, that is a great article! I would like to ask you what would be the behavior of jpa if both manytoone and onetomany were used, but without using the property mappedBy of oneToMany side.

    How hibernate would work on removals and insertions of entity post?

    1. That’s not a valid mapping. Either you use a unidirectional @OneToMany or @ManyToOne, or a bidirectional @OneToMany with mappedBy.

      1. Thank you for the response. I am still in doubt considering the second case you presented, that is the bidirectional @OneToMany with mappedBy. In this case, is it mandatory the use of @ManyToOne annotation on the other side?

      2. If you don’t map the @ManyToOne side, then you don’t have a bidirectional association.

  3. Hi! What do you think of defining @PreRemove methods for both parties to clean up the other side in case the relationship is optional?

      1. I’m sorry, but it seems your statement collides with documentation.
        This is the quote from the Hibernate 5.0 docs:

        Executed before the entity manager remove operation is actually executed or cascaded. This call is synchronous with the remove operation.
        So, if this method executes before entity manager’s remove and flush will be executed after remove then it’s not possible what you said.

      2. Even if it works, it’s better to define the add/remove methods than relying on event listeners to do the job. This way, you make all actions explicit rather than implicit. On the long run, you are going to benefit more from that instead of relying on magic.

      3. But we can also put it another way. If a User cannot exist without a Group, then when a Group is deleted, all its Users must also be deleted — this is handled by cascades and is considered the best practice. But if a User gets deleted then it must be deleted from the Group — at the database level we do not need to do anything but at the persistence context level we should remove that user from the group.users collection, so wouldn’t that be more convenient to automate that in one place at the User entity’s @PreRemove method rather than relying on the caller to not forget about this? This may also introduce a little bit of code duplication .

      4. It depends. If the Persistence Context does not contain any Group, then you can just remove the User. Only if it contains the associated Group, you have to synchronize the association.

        If you do it in @PreRemove, it means you are going to fetch the Group all the time during the User remove, making it behave like an EAGER association.

        Therefore, it’s not a problem of duplicating logic here. That’s why you have a Service layer in front, to make sure that you don’t duplicate business logic.

Leave a Reply

Your email address will not be published. Required fields are marked *