Spring Data JPA Tutorial: Creating Database Queries With the JPA Criteria API

The previous part of this tutorial described how we can create database queries with named queries.

This tutorial has already taught us how we can create static database queries with Spring Data JPA. However, when we are writing real-life applications, we have to be able to create dynamic database queries as well.

This blog post describes how we can create dynamic database queries by using the JPA Criteria API. We will also implement a search function that has two requirements:

• It must return todo entries whose title or description contains the given search term.
• The search must be case-insensitive.

Let’s start by ensuring that Maven creates the JPA static metamodel classes when we compile our project.

Creating the JPA Static Metamodel Classes

A static metamodel consists of classes that describe the entity and embeddable classes found from our domain model. These metamodel classes provide static access to the metadata that describes the attributes of our domain model classes.

We want to use these classes because they give us the possibility to create type-safe criteria queries, but we don’t want to create them manually.

Luckily, we can create these classes automatically by using the Maven Processor Plugin and the JPA Static Metamodel Generator. We can configure these tools by following these steps:

1. Add the Maven Processor Plugin (version 2.2.4) declaration to the plugins section of the pom.xml file.
2. Configure the dependencies of this plugin and add the JPA static metamodel generator dependency (version 4.3.8) to the plugin's dependencies section.
3. Create an execution that invokes the plugin’s process goal in the generate-sources phase of the Maven default lifecycle.
4. Ensure that the plugin runs only the org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor. This annotation processor scans our entities and embeddable classes, and creates the static metamodel classes.

The configuration of the Maven Processor Plugin looks as follows:

<plugin>
	<groupId>org.bsc.maven</groupId>
	<artifactId>maven-processor-plugin</artifactId>
	<version>2.2.4</version>
	<executions>
		<execution>
			<id>process</id>
			<goals>
				<goal>process</goal>
			</goals>
			<phase>generate-sources</phase>
			<configuration>
				<processors>
					<processor>org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor</processor>
				</processors>
			</configuration>
		</execution>
	</executions>
	<dependencies>
		<dependency>
			<groupId>org.hibernate</groupId>
			<artifactId>hibernate-jpamodelgen</artifactId>
			<version>4.3.8.Final</version>
		</dependency>
	</dependencies>
</plugin>

When we compile our project, the invoked annotation processor creates the JPA static metamodel classes to the target/generated-sources/apt directory. Because our domain model has only one entity, the annotation processor creates only one class called Todo_. The source code of the Todo_ class looks as follows:

package net.petrikainulainen.springdata.jpa.todo;

import java.time.ZonedDateTime;
import javax.annotation.Generated;
import javax.persistence.metamodel.SingularAttribute;
import javax.persistence.metamodel.StaticMetamodel;

@Generated(value = "org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor")
@StaticMetamodel(Todo.class)
public abstract class Todo_ {

	public static volatile SingularAttribute<Todo, ZonedDateTime> creationTime;
	public static volatile SingularAttribute<Todo, String> createdByUser;
	public static volatile SingularAttribute<Todo, ZonedDateTime> modificationTime;
	public static volatile SingularAttribute<Todo, String> modifiedByUser;
	public static volatile SingularAttribute<Todo, String> description;
	public static volatile SingularAttribute<Todo, Long> id;
	public static volatile SingularAttribute<Todo, String> title;
	public static volatile SingularAttribute<Todo, Long> version;

}

Let’s move and find out how we can create database queries with the JPA criteria API.

Creating Database Queries With the JPA Criteria API

We can create database queries with the JPA Criteria API by following these steps:

1. Modify the repository interface to support queries that use the JPA Criteria API.
2. Specify the conditions of the invoked database query.
3. Invoke the database query.

Let’s get started.

Modifying the Repository Interface

The JpaSpecificationExecutor<T> interface declares the methods that can be used to invoke database queries that use the JPA Criteria API. This interface has one type parameter T that describes the type of the queried entity.

In other words, if we need to modify our repository interface to support database queries that use the JPA Criteria API, we have to follow these steps:

1. Extend the JpaSpecificationExecutor<T> interface.
2. Set the type of the managed entity.

Example:
The only Spring Data JPA repository of our example application (TodoRepository) manages Todo objects. After we have modified this repository to support criteria queries, its source code looks as follows:

import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
import org.springframework.data.repository.Repository;

interface TodoRepository extends Repository<Todo, Long>, JpaSpecificationExecutor<Todo> {
}

After we have extended the JpaSpeciticationExecutor interface, the classes that use our repository interface get access to the following methods:

• The long count(Specification<T> spec) method returns the number of objects that fulfil the conditions specified by the Specification<T> object given as a method parameter.
• The List<T> findAll(Specification<T> spec) method returns objects that fulfil the conditions specified by the Specification<T> object given as a method parameter.
• The T findOne(Specification<T> spec) method returns an object that fulfils the conditions specified by the Specification<T> object given as a method parameter.

Let’s find out how we can specify the conditions of the invoked database query.

Specifying the Conditions of the Invoked Database Query

We can specify the conditions of the invoked database query by following these steps:

1. Create a new Specification<T> object.
2. Set the type of the queried entity as the value of the type parameter (T).
3. Specify the conditions by implementing the toPredicate() method of the Specification<T> interface.

Example 1:

If we have to create a criteria query that returns Todo objects, we have to create the following specification:

new Specification<Todo>() {
	@Override
	public Predicate toPredicate(Root<Todo> root, 
					CriteriaQuery<?> query, 
					CriteriaBuilder cb) {
		//Create the query by using the JPA Criteria API
	}
}

The obvious next question is:

Where should we create these Specification<T> objects?

I argue that we should create our Specification<T> objects by using specification builder classes because:

• We can put our query generation logic into one place. In other words, we don’t litter the source code of our service classes (or other components) with the query generation logic.
• We can create reusable specifications and combine them in the classes that invoke our database queries.

Example 2:

If we need to create a specification builder class that constructs Specification<Todo> objects, we have to follow these steps:

1. Create a final TodoSpecifications class. The name of this class isn’t important, but I like to use the naming convention: [The name of the queried entity class]Specifications.
2. Add a private constructor the created class. This ensures that no one can instantiate our specification builder class.
3. Add static specification builder methods to this class. In our case, we will add only one specification builder method (hasTitle(String title)) to this class and implement it by returning a new Specification<Todo> object.

The source code of the TodoSpecifications class looks as follows:

import org.springframework.data.jpa.domain.Specification;

import javax.persistence.criteria.CriteriaBuilder;
import javax.persistence.criteria.CriteriaQuery;
import javax.persistence.criteria.Predicate;
import javax.persistence.criteria.Root;

final class TodoSpecifications {

    private TodoSpecifications() {}

    static Specification<Todo> hasTitle(String title) {
        return new Specification<Todo>() {
            @Override
            public Predicate toPredicate(Root<Todo> root, 								
								CriteriaQuery<?> query, 
								CriteriaBuilder cb) {
				//Create the query here.
            }
        }
    }
}

If we use Java 8, we can clean up the implementation of the hasTitle(String title) method by using lambda expressions. The source code of our new specification builder class looks as follows:

import org.springframework.data.jpa.domain.Specification;

import javax.persistence.criteria.CriteriaBuilder;
import javax.persistence.criteria.CriteriaQuery;
import javax.persistence.criteria.Predicate;
import javax.persistence.criteria.Root;

import org.springframework.data.jpa.domain.Specification;

final class TodoSpecifications {

    private TodoSpecifications() {}

    static Specification<Todo> hasTitle(String title) {
        return (root, query, cb) -> {
        	//Create query here
        };
    }
}

Let's find out how we can invoke the created database query.

Invoking the Created Database Query

After we have specified the conditions of the invoked database query by creating a new Specification<T> object, we can invoke the database query by using the methods that are provided by the JpaSpecificationExecutor<T> interface.

The following examples demonstrates how we can invoke different database queries:

Example 1:

If we want to get the number of Todo objects that have the title 'foo', we have to create and invoke our database query by using this code:

Specification<Todo> spec = TodoSpecifications.hasTitle("foo");
long count =  repository.count(spec);

Example 2:

If we want to the get a list of Todo objects that have the title 'foo', we have to create and invoke our database query by using this code:

Specification<Todo> spec = TodoSpecifications.hasTitle("foo");
List<Todo> todoEntries =  repository.findAll(spec);

Example 3:

If we want to get the Todo object whose title is 'foo', we have to create and invoke our database query by using this code:

Specification<Todo> spec = TodoSpecifications.hasTitle("foo");
List<Todo> todoEntries =  repository.findOne(spec);

If we need to create a new specification that combines our existing specifications, we don’t have to add a new method to our specification builder class. We can simply combine our existing specifications by using the Specifications<T> class. The following examples demonstrates how we can use that class:

Example 4:

If we have specifications A and B, and we want to create a database query that returns Todo objects which fulfil the specification A and the specification B, we can combine these specifications by using the following code:

Specification<Todo> specA = ...
Specification<Todo> specB = ...
List<Todo> todoEntries =  repository.findAll(
	Specifications.where(specA).and(specB)
);

Example 5:

If we have specifications A and B, and we want to create a database query that returns Todo objects which fulfil the specification A or the specification B, we can combine these specifications by using the following code:

Specification<Todo> specA = ...
Specification<Todo> specB = ...
Lis<Todo> todoEntries =  repository.findAll(
	Specifications.where(specA).or(specB)
);

Example 6:

If we have specifications A and B, and we want to create a database query that returns Todo objects which fulfil the specification A but not the specification B, we can combine these specifications by using the following code:

Specification<Todo> specA = ...
Specification<Todo> specB = ...
List<Todo> searchResults = repository.findAll(
	Specifications.where(specA).and(
		Specifications.not(specB)
	)
);

Let’s move on and find out how we can implement the search function.

Implementing the Search Function

We can implement our search function by following these steps:

1. Modify our repository interface to support criteria queries.
2. Create the specification builder class that creates Specification<Todo> objects.
3. Implement the service method that uses our specification builder class and invokes the created database queries by using our repository interface.

Let’s start by modifying our repository interface.

Modifying Our Repository Interface

We can make the necessary modifications to our repository interface by following these steps:

1. Extend the JpaSpecificationExecutor<T> interface.
2. The type of the queried entity to Todo.

The source code of our repository interface looks as follows:

import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
import org.springframework.data.repository.Repository;

import java.util.List;
import java.util.Optional;

interface TodoRepository extends Repository<Todo, Long>, JpaSpecificationExecutor<Todo> {

    void delete(Todo deleted);

    List<Todo> findAll();

    Optional<Todo> findOne(Long id);

    void flush();

    Todo save(Todo persisted);
}

Let’s move on and create the specification builder class.

Creating the Specification Builder Class

We can create a specification builder class that fulfils the requirements of our search function by following these steps:

1. Create the specification builder class and ensure that it cannot be instantiated.
2. Create a private static getContainsLikePattern(String searchTerm) method and implement it by following these rules:
   • If the searchTerm is null or empty, return the String "%". This ensures that if the search term is not given, our specification builder class will create a specification that returns all todo entries.
   • If the search isn’t null or empty, transform the search term into lowercase and return the like pattern that fulfils the requirements of our search function.
3. Add a static titleOrDescriptionContainsIgnoreCase(String searchTerm) method to the specification builder class and set its return type to Specification<Todo>.
4. Implement this method by following these steps:
   1. Create a Specification<Todo> object that selects todo entries whose title or description contains the given search term.
   2. Return the created Specification<Todo> object.

The source code or our specification builder class looks as follows:

import org.springframework.data.jpa.domain.Specification;

final class TodoSpecifications {

    private TodoSpecifications() {}

    static Specification<Todo> titleOrDescriptionContainsIgnoreCase(String searchTerm) {
        return (root, query, cb) -> {
            String containsLikePattern = getContainsLikePattern(searchTerm);
            return cb.or(
                    cb.like(cb.lower(root.<String>get(Todo_.title)), containsLikePattern),
                    cb.like(cb.lower(root.<String>get(Todo_.description)), containsLikePattern)
            );
        };
    }

    private static String getContainsLikePattern(String searchTerm) {
        if (searchTerm == null || searchTerm.isEmpty()) {
            return "%";
        }
        else {
            return "%" + searchTerm.toLowerCase() + "%";
        }
    }
}

Let’s find out how we can implement the service method that creates and invokes our database query.

Implementing the Service Method

The first thing that we have to do is to create an interface called TodoSearchService. This interface declares one method called findBySearchTerm(). This method takes the search term as a method parameter and returns a list of TodoDTO objects. The source code of the TodoSearchService interface looks as follows:

import java.util.List;

public interface TodoSearchService {

    List<TodoDTO> findBySearchTerm(String searchTerm);
}

We can implement this interface by following these steps:

1. Create a RepositoryTodoSearchService class, implement the TodoSearchService interface, and annotate the class with the @Service annotation.
2. Add a private final TodoRepository field to the created class.
3. Create a constructor that injects a TodoRepository object to the created field by using constructor injection.
4. Override the findBySearchTerm() method. Annotate the method with the @Transactional annotation and ensure that the transaction is read-only.
5. Implement the findBySearchTerm() method by following these steps:
   1. Get the Specification<Todo> object by invoking the static titleOrDescriptionContainsIgnoreCase() method of the TodoSpecifications class.
   2. Get the todo entries whose title or description contains the given search term by invoking the findAll() method of the JpaSpecificationExecutor interface. Pass the created Specification<Todo> object as a method parameter.
   3. Transform the list of Todo objects into a list of TodoDTO objects and return the created list.

The source of our service class looks as follows:

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.jpa.domain.Specification;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import java.util.List;

import static net.petrikainulainen.springdata.jpa.todo.TodoSpecifications.titleOrDescriptionContainsIgnoreCase;

@Service
final class RepositoryTodoSearchService implements TodoSearchService {

    private final TodoRepository repository;

    @Autowired
    public RepositoryTodoSearchService(TodoRepository repository) {
        this.repository = repository;
    }

    @Transactional(readOnly = true)
    @Override
    public List<TodoDTO> findBySearchTerm(String searchTerm) {
		Specification<Todo> searchSpec = titleOrDescriptionContainsIgnoreCase(searchTerm);
        List<Todo> searchResults = repository.findAll(searchSpec);
        return TodoMapper.mapEntitiesIntoDTOs(searchResults);
    }
}

Let’s move on and find out when we should create our database queries by using the JPA Criteria API.

Why Should We Use the JPA Criteria API?

This tutorial has already taught us how we can create database queries by using the method names of our query methods, the @Query annotation, and named queries. The problem of these query generation methods is that we cannot use them if we have to create dynamic queries (i.e queries that don’t have a constant number of conditions).

If we need to create dynamic queries, we have to create these queries programmatically, and using the JPA Criteria API is one way to do it. The pros of using the JPA Criteria API are:

• It supports dynamic queries.
• If we have an existing application that uses the JPA Criteria API, it is easy to refactor it to use Spring Data JPA (if we want to).
• It is the standard way to create dynamic queries with the Java Persistence API (this doesn’t necessarily matter, but sometimes it does matter).

That sounds impressive. Unfortunately, the JPA Criteria API has one big problem:

It is very hard to implement complex queries and even harder to read them.

That is why I think that we should use criteria queries only when it is absolutely necessary (and we cannot use Querydsl).

Let's move on and summarize what we have learned from this blog post.

Summary

This blog post has taught us six things:

• We can create the JPA static metamodel classes by using the Maven Processor Plugin.
• If we want to invoke queries that use the JPA Criteria API, our repository interface must extend the JpaSpecificationExecutor<T> interface.
• We can specify the conditions of our database queries by creating new Specification<T> objects.
• We should create our Specification<T> objects by using specification builder classes.
• We can combine Specification<T> objects by using the methods provided by the Speficications<T> class.
• We should use criteria queries only when we don’t have a choice.

The next part of this tutorial describes how we can create database queries with Querydsl.

P.S. You can get the example application of this blog post from Github.