1. Introduction
Spring Data JPA provides many ways to deal with entities including query methods and custom JPQL queries. However, sometimes we need a more programmatic approach: for example Criteria API or QueryDSL.
Criteria API offers a programmatic way to create typed queries, which helps us avoid syntax errors. Even more, when we use it with Metamodel API, it makes compile-time-checks whether 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 see how can we implement our custom DAO logic using criteria queries, and how Spring helps to reduce boilerplate code.
2. Sample Application
For the sake of simplicity, in the samples, we’ll implement the same query in multiple ways: finding books by the name of the author and the title containing a String.
The Book entity for this looks like this:
@Entity
class Book {
@Id
Long id;
String title;
String author;
// getters and setters
}
Because we want to keep things simple, we don’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, for example, 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. Also, it declares the type of a row in the result
- With CriteriaQuery<Book> we declare the starting point of the query (Book entity), and we 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).
Furthermore, 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 the @Repository interface:
interface BookRepository extends JpaRepository<Book, Long>, BookRepositoryCustom {}
Also, we 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 it, for example, 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’d be a practical solution to externalize these predicates. With JPA specifications we can do exactly this; and even 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, which we can pass multiple Specification arguments to. Rather, we get utility methods in the org.springframework.data.jpa.domain.Specifications class.
For example, combining two Specification instances with logical and:
bookRepository.findAll(where(hasAuthor(author)).and(titleContains(title)));
In the example above, where() is a static method of the Specifications class.
This way we can make our queries modular. Besides, we didn’t have to write the Criteria API boilerplate: 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: selecting entities that satisfy the provided condition(s).
A query can have many structures it doesn’t support, for example, grouping, returning a different class we’re selecting from, or subqueries.
6. Conclusion
In this tutorial, we saw three ways to use criteria queries in our Spring application:
- creating a DAO class is the most straightforward and most 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
As usual, the examples are available over on GitHub.