Using StatelessSession in Hibernate

1. Overview

When building our persistence layer with Hibernate, we often use the Session API to perform CRUD operations on our domain entities. It automatically provides us with features such as caching, dirty checking, lazy loading, cascading, etc.

While these features make development easier for most common scenarios, they introduce overhead which can impact performance when processing large datasets or performing bulk operations.

For these situations, Hibernate provides the lightweight StatelessSession API as an alternative, which strips away many of the automatic, stateful features of a regular Session.

In this tutorial, we’ll explore how to use Hibernate’s StatelessSession API to perform database operations and practically look at how it differs from the standard stateful Session interface.

2. Setting up the Project

Before we explore the concept of stateless session 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>7.1.0.Final</version>
</dependency>

This dependency provides us with the core Hibernate ORM functionality, including the StatelessSession class 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.

2.2. Defining the Domain Entities

Next, let’s define our domain entities, which consist of an Author and an Article entity.

First, we’ll create an Author entity that can have multiple articles:

@Entity
@Table(name = "authors")
class Author {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false)
    private String name;

    @OneToMany(mappedBy = "author", cascade = CascadeType.ALL, fetch = FetchType.LAZY)
    private List<Article> articles;

    // standard getters and setters
}

Here, we define a standard entity for an Author.

It has a one-to-many relationship with the Article entity, which we’ll define next:

@Entity
@Table(name = "articles")
class Article {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false)
    private String title;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "author_id", nullable = false)
    private Author author;

    // standard getters and setters
}

We define a many-to-one relationship back to an author in our Article entity. This completes our setup, establishing a classic parent-child association between the two entities.

Notice that we’ve explicitly enabled cascading and set the fetch type to LAZY in our domain entities. We’ll see how these settings behave with StatelessSession in the upcoming sections.

3. Performing Write Operations

With our domain entities in place, let’s start by exploring how StatelessSession handles write operations.

As we’ve discussed, StatelessSession doesn’t support automatic cascading of operations. Let’s see what happens when we attempt to save an Article without first persisting its associated Author:

SessionFactory sessionFactory = entityManagerFactory.unwrap(SessionFactory.class);
try (StatelessSession statelessSession = sessionFactory.openStatelessSession()) {
    Author author = new Author();
    author.setName(RandomString.make());

    Article article = new Article();
    article.setTitle(RandomString.make());
    article.setAuthor(author);

    Exception exception = assertThrows(TransientObjectException.class, () -> {
        statelessSession.insert(article);
    });
    assertThat(exception.getMessage())
      .contains("object references an unsaved transient instance - save the transient instance before flushing");
}

Here, we first retrieve an instance of StatelessSession, the same way we retrieve a standard Session instance.

Then, we create our two entities and link them. However, when we call insert() only on the article object, Hibernate throws a TransientObjectException.

This occurs because the associated author object hasn’t been saved, and StatelessSession doesn’t automatically cascade the insert operation, even though we’ve explicitly enabled cascading in our entity mapping.

To resolve this, we must explicitly call insert() on the author object before inserting the article.

Furthermore, a StatelessSession does not perform automatic dirty checking. This means any changes made to an entity after it’s been persisted will be ignored unless we explicitly tell Hibernate to update it. Let’s examine this behavior:

Long authorId;
String originalName = RandomString.make();
try (StatelessSession statelessSession = sessionFactory.openStatelessSession()) {
    statelessSession.getTransaction().begin();

    Author author = new Author();
    author.setName(originalName);
    statelessSession.insert(author);

    author.setName(RandomString.make());

    statelessSession.getTransaction().commit();
    authorId = author.getId();
}

try (StatelessSession statelessSession = sessionFactory.openStatelessSession()) {
    Author author = statelessSession.get(Author.class, authorId);
    assertThat(author.getName())
        .isEqualTo(originalName);
}

Here, we insert an author with an initial name and then immediately change it. With a regular Session, Hibernate would automatically detect this change and update the database.

However, with StatelessSession, the name change is ignored. The database still contains the original name, which we verify by fetching the author again.

To persist such a change, we would need to make an explicit call to the update() method with our author object.

4. Performing Read Operations

Next, let’s explore how StatelessSession handles read operations.

A primary difference is the lack of support for lazy loading. Even though we’ve marked our associations with FetchType.LAZY, attempting to access it after the initial load will fail:

Author author = statelessSession.get(Author.class, authorId);

assertThat(author)
  .hasNoNullFieldsOrProperties();

assertThrows(LazyInitializationException.class, () -> {
    author.getArticles().size();
});

Here, we successfully fetch an Author using the get() method. However, when we try to access the associated articles, a LazyInitializationException is thrown.

This happens because the StatelessSession has no persistence context attached, and therefore cannot go back to the database to initialize the collection.

To load an entity along with its associations correctly, we must fetch them eagerly within the same query.

Let’s try to do this using the JOIN FETCH clause:

Author author = statelessSession
  .createQuery(
    "SELECT a FROM Author a LEFT JOIN FETCH a.articles WHERE a.id = :id",
    Author.class)
  .setParameter("id", authorId)
  .getSingleResult();

assertThat(author)
  .hasNoNullFieldsOrProperties();
assertThat(author.getArticles())
  .isNotNull()
  .isNotEmpty();

In the above, we use the createQuery() method to retrieve the Author and its articles in a single operation. Then, we verify that the articles collection is accessible correctly.

Alternatively, we can use Entity Graphs to achieve the same eager loading behavior:

EntityGraph<Author> authorWithArticlesGraph = statelessSession.createEntityGraph(Author.class);
authorWithArticlesGraph.addAttributeNodes("articles");

Author author = statelessSession
  .createQuery("SELECT a FROM Author a WHERE a.id = :id", Author.class)
  .setParameter("id", authorId)
  .setHint("jakarta.persistence.fetchgraph", authorWithArticlesGraph)
  .getSingleResult();

Here, we create an EntityGraph for the Author entity and configure the articles attribute to be loaded eagerly. Then, we apply it to our query using the jakarta.persistence.fetchgraph hint.

Finally, let’s examine another important aspect of StatelessSession, which is the absence of first-level caching:

Author author1 = statelessSession.get(Author.class, authorId);
Author author2 = statelessSession.get(Author.class, authorId);

assertThat(author1)
  .isNotSameAs(author2);

When we fetch the same entity twice within the same StatelessSession instance, we get two different objects.

This is different from a regular Session, which returns the same object instance from its first-level cache. However, without this cache, the database is queried twice, which results in a new object being created, even if it represents the same database record.

We should remember this behavior when using StatelessSession and carefully manage the entity instances in our code.

5. Conclusion

In this article, we’ve explored using Hibernate’s StatelessSession API to perform database operations.

We set up our domain entities and practically looked at how its behavior differs compared to the standard Session API.

While StatelessSession requires more explicit control over database operations, it’s an excellent choice when we’re dealing with large datasets and don’t need Hibernate’s automatic features.