Hibernate Bytecode Enhancement. Dirty Tracking

  Have you ever wondered how does Hibernate keep track of changes made to an entity, what exactly happens at flush time and why is Hibernate sometimes too slow?

  In this article I’m going to explain what actually happens under the hood and how to tune it up.

Background

  An entity loaded from database becomes managed by Hibernate. At load time, Hibernate creates a copy of all entity property values. The state of an entity can be altered any time during runtime, and at some point these changes are persisted back to the database.

  When the time comes to flush the entities, every managed property is matched against the loading-time snapshot value. Even if only one property of just one single entity has changed, Hibernate will anyway check all the other managed entities. The process of comparing a managed entity against its original, unmodified state is known as dirty checking mechanism.

  Hibernate executes the dirty checking mechanism during flush-time. Any change made to a managed entity is translated into an UPDATE SQL statement. The default dirty checking mechanism makes use of Java reflection and goes through each property of every managed entity.

  For a small number of entities this process might be unnoticeable, however a large number of managed entities will definitely leave a significant CPU and memory footprint. Another thing worth mentioning is that the persistence context needs twice as much memory as all managed entities would normally occupy, because of the copies which are created at load time.

  There might be use cases when an optimized dirty checking algorithm would be required. For this purpose, bytecode enhancement has been introduced.

Bytecode enhancement

  Bytecode enhancement is the process of manipulating the bytecode of a Java class for some purpose. This can be achieved at compile-time or runtime. In this article, we are going to optimize the dirty checking mechanism at compile-time.

  When the enhancement is performed offline (at compile-time), class files are enhanced during a post-compilation step, a step at which Hibernate inserts bytecode level instructions implementing the automatic dirty checking mechanism into each compiled entity. Because the classes are enhanced at build-time, this process doesn’t introduce any extra runtime penalty.

How to enable the bytecode enhancement: Dirty Tracking

  To instrument all @Entity classes, you need to add the following Maven plugin:

<plugin>
    <groupId>org.hibernate.orm.tooling</groupId>
    <artifactId>hibernate-enhance-maven-plugin</artifactId>
    <version>${hibernate.version}</version>
    <executions>
        <execution>
            <configuration>
                <enableDirtyTracking>true</enableDirtyTracking>
            </configuration>
            <goals>
                <goal>enhance</goal>
            </goals>
        </execution>
    </executions>
</plugin>
 

  As soon as the Java classes are compiled, the plugin goes through all @Entity classes and modifies their bytecode representation according to the provided configuration.

  Notice the property specified within the <configuration> tags. With this setup, Hibernate will manipulate the bytecode of the classes to add “dirty tracking” instructions, allowing the entity itself to keep track of which of its attributes have changed.

  At flush time, Hibernate will ask each entity what has changed rather than performing state-diff calculations.

Changes made to the bytecode

  As it’s stated above, once the Dirty Tracking property is enabled, the bytecode of the classes changes.

  For instance, a Java class with 7 attributes, 5 of which are object references and 2 others are collections, before enabling the bytecode enhancement, the .class file had 11.1 KB, and after enabling it, the compiled class occupies 16.42 KB.

  If we would inspect the bytecode of the class, we’ll notice that for each setter method a corresponding Hibernate method has been generated, and inside each setter a call to the appropriate method has been included.

public void setDescription(java.lang.String);
    Code:
       0: aload_0
       1: aload_1
       2: putfield    #79  // Field description:Ljava/lang/String;
       5: return
       
public void setParent(com.hibernate.bytecode.enhancement.ArticleGroup);
    Code:
       0: aload_0
       1: aload_1
       2: putfield    #73  // Field parent:Lcom/hibernate/bytecode/enhancement/ArticleGroup;
       5: return
 
public void setDescription(java.lang.String);
    Code:
       0: aload_0
       1: aload_1
       2: invokevirtual #488   // Method $$_hibernate_write_description:(Ljava/lang/String;)V
       5: return
       
public void setParent(com.hibernate.bytecode.enhancement.ArticleGroup);
    Code:
       0: aload_0
       1: aload_1
       2: invokevirtual #486   // Method $$_hibernate_write_parent:(Lcom/hibernate/bytecode/enhancement/ArticleGroup;)V
       5: return
 
public void $$_hibernate_write_description(java.lang.String);
    Code:
       0: aload_0
       1: getfield      #79    // Field description:Ljava/lang/String;
       4: aload_1
       5: invokestatic  #406   // Method org/hibernate/internal/util/compare/EqualsHelper.areEqual:(Ljava/lang/Object;Ljava/lang/Object;)Z
       8: ifne          18
      11: aload_0
      12: ldc_w         #412   // String description
      15: invokevirtual #409   // Method $$_hibernate_trackChange:(Ljava/lang/String;)V
      18: aload_0
      19: aload_1
      20: putfield      #79    // Field description:Ljava/lang/String;
      23: return
      
public void $$_hibernate_write_parent(com.hibernate.bytecode.enhancement.ArticleGroup);
    Code:
       0: aload_0
       1: getfield      #73    // Field parent:Lcom/hibernate/bytecode/enhancement/ArticleGroup;
       4: aload_1
       5: invokestatic  #406   // Method org/hibernate/internal/util/compare/EqualsHelper.areEqual:(Ljava/lang/Object;Ljava/lang/Object;)Z
       8: ifne          18
      11: aload_0
      12: ldc_w         #407   // String parent
      15: invokevirtual #409   // Method $$_hibernate_trackChange:(Ljava/lang/String;)V
      18: aload_0
      19: aload_1
      20: putfield      #73    // Field parent:Lcom/hibernate/bytecode/enhancement/ArticleGroup;
      23: return
 
Compiled from "ArticleGroup.java"
public class com.hibernate.bytecode.enhancement.ArticleGroup extends com.hibernate.bytecode.enhancement.LogicalIdEntity implements org.hibernate.engine.spi.ManagedEntity,org.hibernate.engine.spi.SelfDirtinessTracker {
  private static final long serialVersionUID;

  private com.hibernate.bytecode.enhancement.ArticleGroup parent;

  private java.lang.String description;

  private java.util.Set<com.hibernate.bytecode.enhancement.Article> articles;

  private transient org.hibernate.engine.spi.EntityEntry $$_hibernate_entityEntryHolder;

  private transient org.hibernate.engine.spi.ManagedEntity $$_hibernate_previousManagedEntity;

  private transient org.hibernate.engine.spi.ManagedEntity $$_hibernate_nextManagedEntity;

  private transient org.hibernate.bytecode.enhance.internal.tracker.DirtyTracker $$_hibernate_tracker;

  private transient org.hibernate.bytecode.enhance.spi.CollectionTracker $$_hibernate_collectionTracker;
 
  // rest of the bytecode has been omitted for brevity
 

  Besides the changes made to the setters, after the enhancement the class implements two more interfaces, ManagedEntity and SelfDirtinessTracker. In addition to this, the class has now five more private fields introduced by Hibernate which are used by the Dirty Tracking mechanism.

Benchmark test

  Laptop configs

    Intel(R) Core(TM) i7-7820HQ CPU @ 2.90GHz
    16GB RAM
    X64
    Toshiba 256GB M.2 2280 SSD
    Windows 10
    PostgreSQL 10
    Hibernate batch size = 20 (a bigger batch size gives worse results)

  The following two test scenarios have been executed to test the performance of the Dirty Tracking property:

  Given 1000 managed Order Lines, on 500 of which a String field has been changed (+13.5%):


  Given 5000 managed Order Lines, on 1000 of which a String field has been changed (+10.25%):


Project build

  Hibernate bytecode enhancement has been enabled with the help of a Maven plugin: org.hibernate.orm.tooling:hibernate-enhance-maven-plugin.

  During the usual clean&build of the project, you will notice in the output, some log lines written by the Hibernate’s plugin:

--- hibernate-enhance-maven-plugin:5.2.9.Final:enhance (default) @ core ---
Starting Hibernate enhancement for classes on D:\projects\DEMO\core\target\classes

...
 
Apr 22, 2019 11:57:03 AM org.hibernate.bytecode.enhance.internal.javassist.EnhancerImpl enhance
INFO: Enhancing [com.hibernate.bytecode.enhancement.ArticleGroup] as Entity
Successfully enhanced class [D:\projects\DEMO\core\target\classes\com\hibernate\bytecode\enhancement\ArticleGroup.class]
 
...
 

  Here’s the build time of a Maven module containing 100 @Entity classes:
    Bytecode enhancement disabled: 23.188 s
    Bytecode enhancement enabled: 29.098 s

  The overhead that is added to the compile-time is nearly 21%. However if we look at the performance boost that we could obtain having the Dirty Tracking feature enabled, we can definitely say that it’s worth it.

Share this article:

Nicolae Sîrbu
Java Developer