How to increment the parent entity version whenever a child entity gets modified with JPA and Hibernate

Introduction

StackOverflow and the Hibernate forum are gold mines. Yesterday, I bumped on the following question on our forum:

Usually, the rationale behind clustering objects together is to form a transactional boundary inside which business invariants are protected. I’ve noticed that with the OPTIMISTIC locking mode changes to a child entity will not cause a version increment on the root. This behavior makes it quite useless to cluster objects together in the first place.

Is there a way to configure Hibernate so that any changes to an object cluster will cause the root object’s version to increment? I’ve read about OPTIMISTIC_FORCE_INCREMENT but I think this does increment the version regardless of if entities were changed or not. Since reads shouldn’t be conflicting with other reads in most scenarios, this doesn’t seem so useful either.

I could always increment the version inside every mutating behavior of the root, but that is quite error-prone. I’ve also thought of perhaps using AOP to do this, but before looking into it, I wanted to know if there were any easy way to do that. If there were a way to check if an object graph is dirty, then it would make it quite easy to implement as well.

What a brilliant question! This post is going to demonstrate how easy you can implement such a requirement when using Hibernate.

Domain Model

First, let’s assume we have the following entities in our system:

PostEntities

The Post is the root entity, and it might have several PostComment entities. Every PostComment can have at most one PostCommentDetails. These entities are mapped as follows:

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

    @Id
    private Long id;

    private String title;

    @Version
    private int version;

    //Getters and setters omitted for brevity
}

@Entity(name = "PostComment")
@Table(name = "post_comment")
public class PostComment 
    implements RootAware<Post> {

    @Id
    private Long id;

    @ManyToOne(fetch = FetchType.LAZY)
    private Post post;

    private String review;

    //Getters and setters omitted for brevity

    @Override
    public Post root() {
        return post;
    }
}

@Entity(name = "PostCommentDetails")
@Table(name = "post_comment_details")
public class PostCommentDetails 
    implements RootAware<Post> {

    @Id
    private Long id;

    @OneToOne(fetch = FetchType.LAZY)
    @MapsId
    private PostComment comment;

    private int votes;

    //Getters and setters omitted for brevity

    @Override
    public Post root() {
        return comment.root();
    }
}

As you probably noticed, the @OneToOne association uses the awesome @MapsId mapping which I already explained in this post.

The PostComment and PostCommentDetails entities are implementing the RootAware interface which is very straightforward:

public interface RootAware<T> {
    T root();
}

By implementing the RootAware interface, we can resolve the root entity for any PostComment and PostCommentDetails entity.

Event Listeners

Contrary to popular belief, Hibernate is not just an ORM framework but a very customizable data access platform. For our example, we need to intercept any child entity modification and acquire an OPTIMISTIC_FORCE_INCREMENT event on the associated root entity.

To intercept the UPDATE and the DELETE SQL events, the following custom entity event listener is needed:

public static class RootAwareUpdateAndDeleteEventListener 
    implements FlushEntityEventListener {

    private static final Logger LOGGER = 
        LoggerFactory.getLogger(RootAwareUpdateAndDeleteEventListener.class);

    public static final RootAwareUpdateAndDeleteEventListener INSTANCE = 
        new RootAwareUpdateAndDeleteEventListener();

    @Override
    public void onFlushEntity(FlushEntityEvent event) throws HibernateException {
        final EntityEntry entry = event.getEntityEntry();
        final Object entity = event.getEntity();
        final boolean mightBeDirty = entry.requiresDirtyCheck( entity );

        if(mightBeDirty && entity instanceof RootAware) {
            RootAware rootAware = (RootAware) entity;
            if(updated(event)) {
                Object root = rootAware.root();
                LOGGER.info("Incrementing {} entity version because a {} child entity has been updated", 
                    root, entity);
                incrementRootVersion(event, root);
            }
            else if (deleted(event)) {
                Object root = rootAware.root();
                LOGGER.info("Incrementing {} entity version because a {} child entity has been deleted", 
                    root, entity);
                incrementRootVersion(event, root);
            }
        }
    }

    private void incrementRootVersion(FlushEntityEvent event, Object root) {
        event.getSession().lock(root, LockMode.OPTIMISTIC_FORCE_INCREMENT);
    }

    private boolean deleted(FlushEntityEvent event) {
        return event.getEntityEntry().getStatus() == Status.DELETED;
    }

    private boolean updated(FlushEntityEvent event) {
        final EntityEntry entry = event.getEntityEntry();
        final Object entity = event.getEntity();

        int[] dirtyProperties;
        EntityPersister persister = entry.getPersister();
        final Object[] values = event.getPropertyValues();
        SessionImplementor session = event.getSession();

        if ( event.hasDatabaseSnapshot() ) {
            dirtyProperties = persister.findModified( 
                event.getDatabaseSnapshot(), values, entity, session 
            );
        }
        else {
            dirtyProperties = persister.findDirty( 
                values, entry.getLoadedState(), entity, session 
            );
        }

        return dirtyProperties != null;
    }
}

This event listener is going to be executed whenever an entity is flushed by the currently running Persistence Context. Every entity modification is automatically detected by the dirty checking mechanism and marked as dirty.

If the entity is dirty and implements the RootAware interface, then we can just lock the parent entity with an OPTIMISTIC_FORCE_INCREMENT lock type. This lock type is going to increment the root entity version during the flush operation.

To intercept when new child entities are being persisted, the following event listener is needed:

public static class RootAwareInsertEventListener 
    implements PersistEventListener {

    private static final Logger LOGGER = 
        LoggerFactory.getLogger(RootAwareInsertEventListener.class);

    public static final RootAwareInsertEventListener INSTANCE = 
        new RootAwareInsertEventListener();

    @Override
    public void onPersist(PersistEvent event) throws HibernateException {
        final Object entity = event.getObject();

        if(entity instanceof RootAware) {
            RootAware rootAware = (RootAware) entity;
            Object root = rootAware.root();
            event.getSession().lock(root, LockMode.OPTIMISTIC_FORCE_INCREMENT);

            LOGGER.info("Incrementing {} entity version because a {} child entity has been inserted", 
                root, entity);
        }
    }

    @Override
    public void onPersist(PersistEvent event, Map createdAlready) 
        throws HibernateException {
        onPersist(event);
    }
}

To register these two event listeners, we need to provide a org.hibernate.integrator.spi.Integrator implementation:

public class RootAwareEventListenerIntegrator
    implements org.hibernate.integrator.spi.Integrator {

    public static final RootAwareEventListenerIntegrator INSTANCE = 
        new RootAwareEventListenerIntegrator();

    @Override
    public void integrate(
            Metadata metadata,
            SessionFactoryImplementor sessionFactory,
            SessionFactoryServiceRegistry serviceRegistry) {

        final EventListenerRegistry eventListenerRegistry =
                serviceRegistry.getService( 
                    EventListenerRegistry.class 
        );

        eventListenerRegistry.appendListeners(
            EventType.PERSIST, 
            RootAwareInsertEventListener.INSTANCE
        );
        eventListenerRegistry.appendListeners(
            EventType.FLUSH_ENTITY, 
            RootAwareUpdateAndDeleteEventListener.INSTANCE
        );
    }

    @Override
    public void disintegrate(
            SessionFactoryImplementor sessionFactory,
            SessionFactoryServiceRegistry serviceRegistry) {
        //Do nothing
    }
}

When bootstrapping the JPA EntityManagerFactory, we can provide the RootAwareEventListenerIntegrator via the hibernate.integrator_provider configuration property:

configuration.put(
    "hibernate.integrator_provider", 
    (IntegratorProvider) () -> Collections.singletonList(
        RootAwareEventListenerIntegrator.INSTANCE
    )
);

Testing time

Assuming we have the following entities within our system:

doInJPA(entityManager -> {
    Post post = new Post();
    post.setId(1L);
    post.setTitle("High-Performance Java Persistence");

    PostComment comment1 = new PostComment();
    comment1.setId(1L);
    comment1.setReview("Good");
    comment1.setPost(post);

    PostCommentDetails details1 = new PostCommentDetails();
    details1.setComment(comment1);
    details1.setVotes(10);

    PostComment comment2 = new PostComment();
    comment2.setId(2L);
    comment2.setReview("Excellent");
    comment2.setPost(post);

    PostCommentDetails details2 = new PostCommentDetails();
    details2.setComment(comment2);
    details2.setVotes(10);

    entityManager.persist(post);
    entityManager.persist(comment1);
    entityManager.persist(comment2);
    entityManager.persist(details1);
    entityManager.persist(details2);
});

Updating child entities

When updating a PostCommentDetails entity:

PostCommentDetails postCommentDetails = entityManager.createQuery(
    "select pcd " +
    "from PostCommentDetails pcd " +
    "join fetch pcd.comment pc " +
    "join fetch pc.post p " +
    "where pcd.id = :id", PostCommentDetails.class)
.setParameter("id", 2L)
.getSingleResult();

postCommentDetails.setVotes(15);

Hibernate generates the following SQL statements:

SELECT  pcd.comment_id AS comment_2_2_0_ ,
        pc.id AS id1_1_1_ ,
        p.id AS id1_0_2_ ,
        pcd.votes AS votes1_2_0_ ,
        pc.post_id AS post_id3_1_1_ ,
        pc.review AS review2_1_1_ ,
        p.title AS title2_0_2_ ,
        p.version AS version3_0_2_
FROM    post_comment_details pcd
INNER JOIN post_comment pc ON pcd.comment_id = pc.id
INNER JOIN post p ON pc.post_id = p.id
WHERE   pcd.comment_id = 2

UPDATE post_comment_details 
SET votes = 15 
WHERE comment_id = 2

UPDATE post 
SET version = 1 
where id = 1 AND version = 0

As you can see, not only the post_comment_details row gets updated but the post version is also incremented.

The same goes for the PostComment entity modifications:

PostComment postComment = entityManager.createQuery(
    "select pc " +
    "from PostComment pc " +
    "join fetch pc.post p " +
    "where pc.id = :id", PostComment.class)
.setParameter("id", 2L)
.getSingleResult();

postComment.setReview("Brilliant!");

Hibernate generating the following SQL statements:

SELECT  pc.id AS id1_1_0_ ,
        p.id AS id1_0_1_ ,
        pc.post_id AS post_id3_1_0_ ,
        pc.review AS review2_1_0_ ,
        p.title AS title2_0_1_ ,
        p.version AS version3_0_1_
FROM    post_comment pc
INNER JOIN post p ON pc.post_id = p.id
WHERE   pc.id = 2

UPDATE post_comment 
SET post_id = 1, review = 'Brilliant!' 
WHERE id = 2

UPDATE post 
SET version = 2 
WHERE id = 1 AND version = 1

Adding new child entities

The parent Post entity version is incremented even when a new child entity is being persisted:

Post post = entityManager.getReference(Post.class, 1L);

PostComment postComment = new PostComment();
postComment.setId(3L);
postComment.setReview("Worth it!");
postComment.setPost(post);
entityManager.persist(postComment);

Hibernate generating the following SQL statements:

SELECT p.id AS id1_0_0_ ,
       p.title AS title2_0_0_ ,
       p.version AS version3_0_0_
FROM   post p
WHERE  p.id = 1

INSERT INTO post_comment (post_id, review, id) 
VALUES (1, 'Worth it!', 3)

UPDATE post 
SET version = 3 
WHERE id = 1 AND version = 2

Removing child entities

This solution works even when removing existing child entities:

PostComment postComment = entityManager.getReference(PostComment.class, 3l);
entityManager.remove(postComment);

Hibernate being able to increment the parent entity version accordingly:

SELECT pc.id AS id1_1_0_ ,
       pc.post_id AS post_id3_1_0_ ,
       pc.review AS review2_1_0_
FROM   post_comment pc
WHERE  pc.id = 3

SELECT p.id AS id1_0_0_ ,
       p.title AS title2_0_0_ ,
       p.version AS version3_0_0_
FROM   post p
WHERE  p.id = 1

DELETE FROM post_comment 
WHERE id = 3

UPDATE post 
SET version = 4 
WHERE id = 1 and version = 3

Cool, right?

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

Conclusion

Synchronizing a root entity version for every child entity modification is fairly easy with Hibernate. Hibernate supports many concurrency control mechanisms, as illustrated in this comprehensive tutorial.

Code available on GitHub.

Enter your email address to follow this blog and receive notifications of new posts by email.

Advertisements

28 thoughts on “How to increment the parent entity version whenever a child entity gets modified with JPA and Hibernate

  1. Very nice! But “private PostComment comment;” is annotated with @ManyToOne, should be @OneToOne. And I would write “comment.getRoot();” instead of “comment.getPost();” in line 55, but that’s a matter of taste. 😉

  2. Great article, Vlad.

    Everytime I had to do this I was obligated to change any root’s attribute so that Hibernate could realize that changing. That could work for other kind attributes, like a datetime attribute (updatedAt or something like that).

    Well, that´s something so useful that Hibernate could have it built-in via configuration or annotation or just an interface (as your solution).

    Thanks for another great article!

  3. The naming of the variable “mightBeDirty” in onFlushEntity(…) suggests that “entity” might also not be dirty – is that true? Because in this case the root entity version should not be incremented but it is nevertheless…

      1. Bulk update/delete do not work with optimistic locking. Hibernate offers the VERSIONED keyword, but that’s only for incrementing the version for the entities that are updated/deleted by the query.

        Only when Hibernate manages the entity state will this logic work. So, for bulk update/delete, this concurrency control mechanism will not work.

  4. And what happens if two different entities having the same “root” are dirty? Does it work or will one lock block the other? And if it works, is the root version incremented by 1 or by 2? Ok, I could try it myself… 😉

  5. Hi, could you give me some real scenario on this example when this updating of root entity is needed. I don’t doubt there exists a good reason to do this I am just not sure if I understand when this is needed and I would like to make sure I understand 🙂 Thanks a lot

    1. If you operate on entity aggregates and you want to make sure that nothing has changed since you loaded the aggregate, then this solution is the perfect fit.

      Imagine a Version Control System, where the Repository entity has a list of Commits, each Commit with a list of Changes. If a new commit was added or amended (e.g. git), then you need to merge the Repository entity to fetch the latest status of the master branch.

  6. But in domain driven design you don’t have the root entity. You have only an id. Bidirectional associations are horrible things. I’ am struggling with all the jee stack. It was thought for anemic model. If i have an order and i’ am changing an order detail can i dirty root entity without inverse association ?

    1. Of course you have a root. That’s what DDD Aggregates are all about.

      DDD is a fine concept as long as you mind the underlying database operations. If you try to stick to OOP principles and ignore what happens in the DB, you are going to have performance issues.

      As explained in my book, unidirectional collections perform badly compared to their bidirectional counterparts.

      To answer your question, you don’t need to navigate to the root entity, you can always use OPTIMISTIC_FORCE_INCREMENT against the root entity reference that you can fetch directly.

      1. In DDD you have root entities (the root of an aggregate), but it is not necessary to put the reference inside other entities, you can create a value object for each identifier for examples ItemId, OrderId (all @Embeddable). I’am using OPTIMISTIC_FORCE_INCREMENT with spring-data-jpa with the @Lock annotation, but this is an error-prone job.

      2. Pro Tip: Unless you are using a document storage, you cannot apply all the DDD principles without affecting the data access patterns. For a RDBMS, it’s better to map the DB to the Domain Model, than the other way around.

  7. I tested this solution with envers but the root entity is not part of the revision when a child entity is modified (although its version has been increased).

    It would be nice if any change made to any entity belonging to an aggregate would increase that aggregate’s root entity version and would also create an audit record for the root.

    I could then list all revisions for the whole aggregate simply like this: auditReader.getRevisions(Root.class, rootId)

      1. Yes, if a child entity is modified, the version number of the root is increased but no envers audit record is created for the root. So, there is no way to obtain a global list of envers revisions for the whole graph.

        Let’s take the classic scenario with order/order-lines:
        – revision #1 : I create an order (version 1) + 2 order-lines
        – revision #2 : I modify an order-line, my order is now in version 2 (thanks to the listener)
        – revision #3 : I delete an order-line, my order is now in version 3 (thanks to the listener)

        If I retrieve the list of revisions for my root entity via envers, I only get revisions #1 and #3.
        I would have expected to get all 3.

        So the question is: when the root is locked with OPTIMISTIC_FORCE_INCREMENT, is there a way to force envers to create an audit record for the root too?

      2. Well, introducing debezium just for that usecase seems a bit overkill.

        I’d prefer to manually update a dumb last-modification field on my root each time a child is modified so that the root is viewed as modified by envers and is included in the revision along with the child.

      3. Just for one use case, it does not justify to switch to a new CDC framework. However, if you have multiple systems operating with the DB, and some of them are not using Hibernate, then Debezium is a much better option.

  8. Hello Vlad,
    I’ve tried this approach and it worked great when updating/deleting child entities. What bothers me is that it fails when I want to delete whole object tree (parent entity and all its children). The listener basicaly wants to increment version on already deleted parent.
    Could you help me with this?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s