Hibernate Bytecode Enhancement: Dirty Tracking

Have you ever wondered how Hibernate keeps track of changes made to an entity, what exactly happens at a flush time, and why is Hibernate is 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 the database is 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 a single entity has changed, Hibernate will check all of the other managed entities. The process of comparing a managed entity against its original, unmodified state is known as the 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 seven attributes, five of which are object references and two 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.

Setter methods from the Java class before enhancement:

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

public void setParent(ArticleGroup parent) {
    this.parent = parent;
}

And their bytecode:

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

Setter methods from the Java class after enhancement, these are Hibernate generated methods:

void setDescription(String description) {
    $$_hibernate_write_description(description);
}

public void setParent(ArticleGroup parent) {
    $$_hibernate_write_parent(parent);
}

public void $$_hibernate_write_description(String paramString) {
    if (!Objects.deepEquals(paramString, this.description))
        $$_hibernate_trackChange("description");
    this.description = paramString;
}

public void $$_hibernate_write_parent(ArticleGroup paramArticleGroup) {
    if (!Objects.deepEquals(paramArticleGroup, this.parent))
        $$_hibernate_trackChange("parent");
    this.parent = paramArticleGroup;
}

public void $$_hibernate_trackChange(String paramString) {
    if (this.$$_hibernate_tracker == null) {
        this;
        this.$$_hibernate_tracker = new SimpleFieldTracker();
    }
    this.$$_hibernate_tracker.add(paramString);
}

And the bytecode of these methods:

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

Header of the ArticleGroup.class file:

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 1,000 managed Order Lines, on 500 of which a String field has been changed (+13.5%):

Given 5,000 managed Order Lines, on 1,000 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 and build of the project, you will notice in the output, some log lines written by the Hibernate’s plugin:

Part of the project build log:

--- 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.