A Guide to @ConcreteProxy in Hibernate

1. Overview

When working with Hibernate, we often use lazy loading to optimize performance by fetching related entities only when they’re accessed. To achieve this, Hibernate generates proxy objects that stand in for the real entities until they are initialized.

However, when working with inheritance hierarchies, these proxies are typed to the declared association type rather than the actual entity subclass. This leads to failures during type checking and casting operations.

In this tutorial, we’ll explore how to use Hibernate’s @ConcreteProxy annotation to correctly lazy load polymorphic associations in inheritance hierarchies.

2. Project Setup

Before we explore the @ConcreteProxy annotation in Hibernate, let’s set up a simple application that we’ll use throughout this tutorial.

2.1. Dependencies

Let’s start by adding the Hibernate dependency to our project’s pom.xml file:

<dependency>
    <groupId>org.hibernate.orm</groupId>
    <artifactId>hibernate-core</artifactId>
    <version>6.6.0.Final</version>
</dependency>

This dependency provides us with the core Hibernate ORM functionality, including the @ConcreteProxy annotation we’re discussing in this tutorial.

Alternatively, if we’re building a Spring Boot application, we can use the Spring Data JPA starter, which already includes this dependency.

Also, note that @ConcreteProxy was introduced in version 6.6.0.Final, so we need to ensure we’re using at least this version when following along with this tutorial.

2.2. Defining a Simple Inheritance Hierarchy

Next, to demonstrate the proxy type resolution problem and its solution, we’ll define a simple inheritance hierarchy and model a rudimentary wizard management schema.

First, let’s create an abstract HogwartsHouse entity using the single table inheritance strategy:

@Entity
@Inheritance(strategy = InheritanceType.SINGLE_TABLE)
abstract class HogwartsHouse {

    @Id
    @GeneratedValue
    private Long id;

    private String founder;

    private String houseColors;

    // standard constructors, getters, and setters
}

Here, we define an abstract base class with common properties shared by all Hogwarts houses.

Next, let’s create two concrete subclasses:

@Entity
class Gryffindor extends HogwartsHouse {

    private boolean hasSummonedSword;

    // standard constructors, getters, and setters
}

@Entity
class Slytherin extends HogwartsHouse {

    private boolean heirOfSlytherin;

    // standard constructors, getters, and setters
}

Here, we define Gryffindor and Slytherin classes, each extending HogwartsHouse and having their own unique attribute.

Finally, let’s create a Wizard entity that has a many-to-one relationship with a HogwartsHouse:

@Entity
class Wizard {

    @Id
    @GeneratedValue
    private Long id;

    private String name;

    @ManyToOne(fetch = FetchType.LAZY)
    private HogwartsHouse hogwartsHouse;

    // standard constructors, getters, and setters
}

Notice that to reproduce the proxy behavior we intend to study, we’ve explicitly set the fetch type to LAZY.

3. Understanding the Problem With Proxy Type Resolution

Now that we have our inheritance hierarchy in place, let’s explore the problem that occurs when we try to determine the concrete type of a lazily loaded entity:

Long wizardId;
SessionFactory sessionFactory = entityManagerFactory.unwrap(SessionFactory.class);
try (Session session = sessionFactory.openSession()) {
    session.getTransaction().begin();

    Gryffindor gryffindor = new Gryffindor("Godric Gryffindor", "Scarlet and Gold", true);
    session.persist(gryffindor);

    Wizard wizard = new Wizard("Neville Longbottom", gryffindor);
    session.persist(wizard);

    wizardId = wizard.getId();
    session.getTransaction().commit();
}

try (Session session = sessionFactory.openSession()) {
    Wizard wizard = session.find(Wizard.class, wizardId);
    HogwartsHouse hogwartsHouse = wizard.getHogwartsHouse();

    assertThat(hogwartsHouse)
        .isInstanceOf(HogwartsHouse.class);
    assertThat(hogwartsHouse.getId())
        .isNotNull()
        .isPositive();
}

Here, we first persist a Gryffindor instance and associate it with a wizard.

Then, in a separate session, we retrieve the wizard and access their hogwartsHouse. We’re able to type check the object against the base class and access base class specific fields.

However, let’s see what happens when we try to check if the hogwartsHouse is specifically a Gryffindor instance:

assertThat(hogwartsHouse)
  .isInstanceOf(Gryffindor.class);

When we run our above assertion, we’ll encounter an error message similar to:

Expecting actual:
  com.baeldung.concreteproxy.Gryffindor@156b31d
to be an instance of:
  com.baeldung.concreteproxy.Gryffindor
but was instance of:
  com.baeldung.concreteproxy.HogwartsHouse$HibernateProxy$8pxrMoK7

The error tells us that Hibernate has created a proxy typed to HogwartsHouse rather than the actual Gryffindor subclass. This occurs because when Hibernate lazily loads the association, it only knows the declared type of the relationship, not the actual concrete type stored in the database.

As a result, the instanceof check fails, and we cannot safely cast the proxy to access subclass-specific properties.

One workaround for this problem is to use Hibernate’s unproxy() method, which returns the underlying entity object from a proxy. However, this approach forces initialization of the proxy, defeating the entire purpose of lazy loading.

4. Using @ConcreteProxy

To resolve the problem we’ve discussed, Hibernate introduced the @ConcreteProxy annotation, which determines the actual concrete class of the entity before creating the proxy.

Let’s apply this annotation to our abstract base class:

@Entity
@ConcreteProxy
@Inheritance(strategy = InheritanceType.SINGLE_TABLE)
abstract class HogwartsHouse {
    // ...
}

With this simple addition, Hibernate will now inspect the discriminator column in the database to identify the correct subclass when fetching the lazy association. We should note that this results in a slightly slower query compared to the previous approach.

Consequently, it generates a proxy that is an instance of the specific subclass, allowing us to safely cast it and access subclass-specific attributes:

assertThat(((Gryffindor) hogwartsHouse).getHasSummonedSword())
  .isTrue();

Now, we’re able to cast our lazy association to the concrete subclass and access its specific property without any issues.

5. Conclusion

In this article, we’ve explored the benefit of Hibernate’s @ConcreteProxy annotation.

We set up a simple inheritance hierarchy and looked at how lazy loading creates proxies typed to the declared association type rather than the actual subclass, which prevents us from performing type checking and casting operations.

Then, we solved this problem by annotating the base class with the @ConcreteProxy annotation.

As always, all the code examples used in this article are available over on GitHub.