Object States in Hibernate’s Session

1. Introduction

Hibernate is a convenient framework for managing persistent data, but understanding how it works internally can be tricky at times.

In this tutorial, we’ll learn about object states and how to move between them. We’ll also look at the problems we can encounter with detached entities and how to solve them.

2. Hibernate’s Session

The Session interface is the main tool used to communicate with Hibernate. It provides an API enabling us to create, read, update, and delete persistent objects. The session has a simple lifecycle. We open it, perform some operations, and then close it.

When we operate on the objects during the session, they get attached to that session. The changes we make are detected and saved upon closing. After closing, Hibernate breaks the connections between the objects and the session.

3. Object States

In the context of Hibernate’s Session, objects can be in one of three possible states: transient, persistent, or detached.

3.1. Transient

An object we haven’t attached to any session is in the transient state. Since it was never persisted, it doesn’t have any representation in the database. Because no session is aware of it, it won’t be saved automatically.

Let’s create a user object with the constructor and confirm that it isn’t managed by the session:

Session session = openSession();
UserEntity userEntity = new UserEntity("John");
assertThat(session.contains(userEntity)).isFalse();

3.2. Persistent

An object that we’ve associated with a session is in the persistent state. We either saved it or read it from a persistence context, so it represents some row in the database.

Let’s create an object and then use the persist method to make it persistent:

Session session = openSession();
UserEntity userEntity = new UserEntity("John");
session.persist(userEntity);
assertThat(session.contains(userEntity)).isTrue();

Alternatively, we may use the save method. The difference is that the persist method will just save an object, and the save method will additionally generate its identifier if that’s needed.

3.3. Detached

When we close the session, all objects inside it become detached. Although they still represent rows in the database, they’re no longer managed by any session:

session.persist(userEntity);
session.close();
assertThat(session.isOpen()).isFalse();
assertThatThrownBy(() -> session.contains(userEntity));

Next, we’ll learn how to save transient and detached entities.

4. Saving and Reattaching an Entity

4.1. Saving a Transient Entity

Let’s create a new entity and save it to the database. When we first construct the object, it’ll be in the transient state.

To persist our new entity, we’ll use the persist method:

UserEntity userEntity = new UserEntity("John");
session.persist(userEntity);

Now, we’ll create another object with the same identifier as the first one. This second object is transient because it’s not yet managed by any session, but we can’t make it persistent using the persist method. It’s already represented in the database, so it’s not really new in the context of the persistence layer.

Instead, we’ll use the merge method to update the database and make the object persistent:

UserEntity onceAgainJohn = new UserEntity("John");
session.merge(onceAgainJohn);

4.2. Saving a Detached Entity

If we close the previous session, our objects will be in a detached state. Similarly to the previous example, they’re represented in the database but they aren’t currently managed by any session. We can make them persistent again using the merge method:

UserEntity userEntity = new UserEntity("John");
session.persist(userEntity);
session.close();
session.merge(userEntity);

5. Nested Entities

Things get more complicated when we consider nested entities. Let’s say our user entity will also store information about his manager:

public class UserEntity {
    @Id
    private String name;

    @ManyToOne
    private UserEntity manager;
}

When we save this entity, we need to think not only about the state of the entity itself but also about the state of the nested entity. Let’s create a persistent user entity and then set its manager:

UserEntity userEntity = new UserEntity("John");
session.persist(userEntity);
UserEntity manager = new UserEntity("Adam");
userEntity.setManager(manager);

If we try to update it now, we’ll get an exception:

assertThatThrownBy(() -> {
            session.saveOrUpdate(userEntity);
            transaction.commit();
});

java.lang.IllegalStateException: org.hibernate.TransientPropertyValueException: object references an unsaved transient instance - save the transient instance before flushing : com.baeldung.states.UserEntity.manager -> com.baeldung.states.UserEntity

That’s happening because Hibernate doesn’t know what to do with the transient nested entity.

5.1. Persisting Nested Entities

One way to solve this problem is to explicitly persist nested entities:

UserEntity manager = new UserEntity("Adam");
session.persist(manager);
userEntity.setManager(manager);

Then, after committing the transaction, we’ll be able to retrieve the correctly saved entity:

transaction.commit();
session.close();

Session otherSession = openSession();
UserEntity savedUser = otherSession.get(UserEntity.class, "John");
assertThat(savedUser.getManager().getName()).isEqualTo("Adam");

5.2. Cascading Operations

Transient nested entities can be persisted automatically if we configure the relationship’s cascade property correctly in the entity class:

@ManyToOne(cascade = CascadeType.PERSIST)
private UserEntity manager;

Now when we persist the object, that operation will be cascaded to all nested entities:

UserEntityWithCascade userEntity = new UserEntityWithCascade("John");
session.persist(userEntity);
UserEntityWithCascade manager = new UserEntityWithCascade("Adam");

userEntity.setManager(manager); // add transient manager to persistent user
session.saveOrUpdate(userEntity);
transaction.commit();
session.close();

Session otherSession = openSession();
UserEntityWithCascade savedUser = otherSession.get(UserEntityWithCascade.class, "John");
assertThat(savedUser.getManager().getName()).isEqualTo("Adam");

6. Summary

In this tutorial, we took a closer look at how the Hibernate Session works with respect to object state. We then inspected some problems it can create and how to solve them.