Use Criteria Queries in a Spring Data Application

1. Introduction

Spring Data JPA provides many ways to deal with entities, including query methods and custom JPQL queries. But sometimes, we need a more programmatic approach, such as Criteria API or QueryDSL.

Criteria API offers a programmatic way to create typed queries, which helps us avoid syntax errors. Furthermore, when we use it with Metamodel API, it makes compile-time-checks to confirm if we used the correct field names and types.

However, it has its downsides; we have to write verbose logic bloated with boilerplate code.

In this tutorial, we’ll learn how to implement our custom DAO logic using criteria queries. We’ll also illustrate how Spring helps to reduce boilerplate code. 

2. Sample Application

For the sake of simplicity in the examples, we’ll implement the same query in multiple ways: finding books by the name of the author and the title containing a String.

Here’s the Book entity:

@Entity
class Book {

    @Id
    Long id;
    String title;
    String author;

    // getters and setters

}

Because we want to keep things simple, we won’t use Metamodel API in this tutorial.

3. @Repository Class

As we know, in the Spring component model, we should place our data access logic in @Repository beans. Of course, this logic can use any implementation, like Criteria API.

To do this, we only need an EntityManager instance, which we can autowire:

@Repository
class BookDao {

    EntityManager em;

    // constructor

    List<Book> findBooksByAuthorNameAndTitle(String authorName, String title) {
        CriteriaBuilder cb = em.getCriteriaBuilder();
        CriteriaQuery<Book> cq = cb.createQuery(Book.class);

        Root<Book> book = cq.from(Book.class);
        Predicate authorNamePredicate = cb.equal(book.get("author"), authorName);
        Predicate titlePredicate = cb.like(book.get("title"), "%" + title + "%");
        cq.where(authorNamePredicate, titlePredicate);

        TypedQuery<Book> query = em.createQuery(cq);
        return query.getResultList();
    }

}

The code above follows a standard Criteria API workflow:

• First, we get a CriteriaBuilder reference, which we can use to create different parts of the query.
• Using the CriteriaBuilder, we create a CriteriaQuery<Book>, which describes what we want to do in the query. It also declares the type of a row in the result.
• With CriteriaQuery<Book>, we declare the starting point of the query (Book entity), and store it in the book variable for later use.
• Next, with CriteriaBuilder, we create predicates against our Book entity. Note that these predicates don’t have any effect yet.
• We apply both predicates to our CriteriaQuery. CriteriaQuery.where(Predicate…) combines its arguments in a logical and. This is the point when we tie these predicates to the query.
• After that, we create a TypedQuery<Book> instance from our CriteriaQuery.
• Finally, we return all matching Book entities.

Note that since we marked the DAO class with @Repository, Spring enables exception translation for this class.

4. Extending Repository With Custom Methods

Having automatic custom queries is a powerful Spring Data feature. However, sometimes we need more sophisticated logic, which we can’t create with automatic query methods.

We can implement these queries in separate DAO classes (like in the previous section).

Or, if we want a @Repository interface to have a method with a custom implementation, we can use composable repositories.

The custom interface looks like this:

interface BookRepositoryCustom {
    List<Book> findBooksByAuthorNameAndTitle(String authorName, String title);
}

And here’s the @Repository interface:

interface BookRepository extends JpaRepository<Book, Long>, BookRepositoryCustom {}

We also have to modify our previous DAO class to implement BookRepositoryCustom, and rename it to BookRepositoryImpl:

@Repository
class BookRepositoryImpl implements BookRepositoryCustom {

    EntityManager em;

    // constructor

    @Override
    List<Book> findBooksByAuthorNameAndTitle(String authorName, String title) {
        // implementation
    }

}

When we declare BookRepository as a dependency, Spring finds BookRepositoryImpl and uses it when we invoke the custom methods.

Let’s say we want to select which predicates to use in our query. For example, when we don’t want to find the books by author and title, we only need the author to match.

There are multiple ways to do this, like applying a predicate only if the passed argument isn’t null:

@Override
List<Book> findBooksByAuthorNameAndTitle(String authorName, String title) {
    CriteriaBuilder cb = em.getCriteriaBuilder();
    CriteriaQuery<Book> cq = cb.createQuery(Book.class);

    Root<Book> book = cq.from(Book.class);
    List<Predicate> predicates = new ArrayList<>();
    
    if (authorName != null) {
        predicates.add(cb.equal(book.get("author"), authorName));
    }
    if (title != null) {
        predicates.add(cb.like(book.get("title"), "%" + title + "%"));
    }
    cq.where(predicates.toArray(new Predicate[0]));

    return em.createQuery(cq).getResultList();
}

However, this approach makes the code hard to maintain, especially if we have many predicates and want to make them optional.

It would be a practical solution to externalize these predicates. With JPA specifications, we can do exactly that, and much more.

5. Using JPA Specifications

Spring Data introduced the org.springframework.data.jpa.domain.Specification interface to encapsulate a single predicate:

interface Specification<T> {
    Predicate toPredicate(Root<T> root, CriteriaQuery query, CriteriaBuilder cb);
}

We can provide methods to create Specification instances:

static Specification<Book> hasAuthor(String author) {
    return (book, cq, cb) -> cb.equal(book.get("author"), author);
}

static Specification<Book> titleContains(String title) {
    return (book, cq, cb) -> cb.like(book.get("title"), "%" + title + "%");
}

To use them, we need our repository to extend org.springframework.data.jpa.repository.JpaSpecificationExecutor<T>:

interface BookRepository extends JpaRepository<Book, Long>, JpaSpecificationExecutor<Book> {}

This interface declares handy methods to work with specifications. For example, now we can find all Book instances with the specified author with this one-liner:

bookRepository.findAll(hasAuthor(author));

Unfortunately, we don’t get any methods that we can pass multiple Specification arguments to. Rather, we get utility methods in the org.springframework.data.jpa.domain.Specification interface.

For example, we can combine two Specification instances with a logical and:

bookRepository.findAll(where(hasAuthor(author)).and(titleContains(title)));

In the example above, where() is a static method of the Specification class.

This way we can make our queries modular. Besides, we didn’t have to write the Criteria API boilerplate because Spring provided it for us.

Note that it doesn’t mean we won’t have to write criteria boilerplate anymore; this approach is only capable of handling the workflow we saw, namely selecting entities that satisfy the provided condition(s).

A query can have many structures it doesn’t support, including grouping, returning a different class than we’re selecting from, or subqueries.

6. Conclusion

In this article, we discusssed three ways to use criteria queries in our Spring application:

• creating a DAO class is the most straightforward and flexible way.
• extending a @Repository interface to seamless integration with automatic queries
• using predicates in Specification instances to make the simple cases cleaner and less verbose