The third part of my Spring Data JPA tutorialdescribed how you can create custom queries by using query methods. This blog entry will describe how you can implement more advanced queries by using the JPA criteria API.
If you have read the previous part of this tutorial, you might remember that the search function which I used as an example returned all persons whose last name matched with the given search criteria. This requirement is now replaced with a new one:
- The search function must return only such persons whose last name begins with the given search term.
I am going to walk you through the implementation of this requirement next.
Required Steps
The steps required to implement the new search function are following:
- Creating the JPA criteria query.
- Extending the repository to support JPA criteria queries.
- Using the created criteria query and repository.
Each of these steps is described with more details in following.
Building the JPA Criteria Query
Spring Data JPA uses the specification pattern for providing an API which is used to create queries with the JPA criteria API. The heart of this API is the Specification interface which contains a single method called toPredicate(). In order to build the required criteria query, you must create a new implementation of the Specification interface and build the predicate in thetoPredicate() method.
Before going in to the details, I will introduce the source code of my static meta model classwhich is used to create type safe queries with the JPA criteria API. The source code of thePerson_ class is given in following:
import javax.persistence.metamodel.StaticMetamodel;
/**
* A meta model class used to create type safe queries from person
* information.
* @author Petri Kainulainen
*/
@StaticMetamodel(Person.class)
public class Person_ {
public static volatile SingularAttribute<Person, String> lastName;
}
A clean way to create specifications is to implement a specification builder class and use static methods to build the actual specification instances. My specification builder class is calledPersonSpecifications and its source code given in following:
import javax.persistence.criteria.CriteriaBuilder;
import javax.persistence.criteria.CriteriaQuery;
import javax.persistence.criteria.Predicate;
import javax.persistence.criteria.Root;
/**
* A class which is used to create Specification objects which are used
* to create JPA criteria queries for person information.
* @author Petri Kainulainen
*/
public class PersonSpecifications {
/**
* Creates a specification used to find persons whose last name begins with
* the given search term. This search is case insensitive.
* @param searchTerm
* @return
*/
public static Specification<Person> lastNameIsLike(final String searchTerm) {
return new Specification<Person>() {
@Override
public Predicate toPredicate(Root<Person> personRoot, CriteriaQuery<?> query, CriteriaBuilder cb) {
String likePattern = getLikePattern(searchTerm);
return cb.like(cb.lower(personRoot.<String>get(Person_.lastName)), likePattern);
}
private String getLikePattern(final String searchTerm) {
StringBuilder pattern = new StringBuilder();
pattern.append(searchTerm.toLowerCase());
pattern.append("%");
return pattern.toString();
}
};
}
}
Testing my specification builder implementation is pretty straightforward. I used Mockito mocking framework to mock the JPA criteria API. The source code of my test class is given following:
import org.junit.Test;
import org.springframework.data.jpa.domain.Specification;
import javax.persistence.criteria.*;
import static junit.framework.Assert.assertEquals;
import static org.mockito.Mockito.*;
public class PersonSpecificationsTest {
private static final String SEARCH_TERM = "Foo";
private static final String SEARCH_TERM_LIKE_PATTERN = "foo%";
private CriteriaBuilder criteriaBuilderMock;
private CriteriaQuery criteriaQueryMock;
private Root<Person> personRootMock;
@Before
public void setUp() {
criteriaBuilderMock = mock(CriteriaBuilder.class);
criteriaQueryMock = mock(CriteriaQuery.class);
personRootMock = mock(Root.class);
}
@Test
public void lastNameIsLike() {
Path lastNamePathMock = mock(Path.class);
when(personRootMock.get(Person_.lastName)).thenReturn(lastNamePathMock);
Expression lastNameToLowerExpressionMock = mock(Expression.class);
when(criteriaBuilderMock.lower(lastNamePathMock)).thenReturn(lastNameToLowerExpressionMock);
Predicate lastNameIsLikePredicateMock = mock(Predicate.class);
when(criteriaBuilderMock.like(lastNameToLowerExpressionMock, SEARCH_TERM_LIKE_PATTERN)).thenReturn(lastNameIsLikePredicateMock);
Specification<Person> actual = PersonSpecifications.lastNameIsLike(SEARCH_TERM);
Predicate actualPredicate = actual.toPredicate(personRootMock, criteriaQueryMock, criteriaBuilderMock);
verify(personRootMock, times(1)).get(Person_.lastName);
verifyNoMoreInteractions(personRootMock);
verify(criteriaBuilderMock, times(1)).lower(lastNamePathMock);
verify(criteriaBuilderMock, times(1)).like(lastNameToLowerExpressionMock, SEARCH_TERM_LIKE_PATTERN);
verifyNoMoreInteractions(criteriaBuilderMock);
verifyZeroInteractions(criteriaQueryMock, lastNamePathMock, lastNameIsLikePredicateMock);
assertEquals(lastNameIsLikePredicateMock, actualPredicate);
}
}
However, if you have to build more complex queries by using this approach, testing your queries will become more troublesome because the JPA criteria API is not the easiest one to mock. In this case it is a good idea to divide the search conditions into multiple specifications and use theSpecifications class to combine your specification instances. This way your unit tests don’t become so complex but you can still harness the power of the JPA criteria API in your application.
Extending the Repository
Extending your Spring Data JPA repository to support JPA criteria queries is quite easy. All you have to do is to extend the JpaSpecificationExecutor interface. This gives you access to thefindAll(Specification spec) method which returns all entities fulfilling the search conditions specified by the specification. The source code of my PersonRepository is given in following:
import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
/**
* Specifies methods used to obtain and modify person related information
* which is stored in the database.
* @author Petri Kainulainen
*/
public interface PersonRepository extends JpaRepository<Person, Long>, JpaSpecificationExecutor<Person> {
}
Using the Specification Builder and the Repository
The last step is to implement the service class which uses the created specification builder and the repository. The search() method of the PersonService interface takes the used search term as a parameter. The relevant part of the PersonService interface is given in following:
* Declares methods used to obtain and modify person information.
* @author Petri Kainulainen
*/
public interface PersonService {
/**
* Searches persons by using the given search term as a parameter.
* @param searchTerm
* @return A list of persons whose last name begins with the given search term. If no persons is found, this method
* returns an empty list. This search is case insensitive.
*/
public List<Person> search(String searchTerm);
}
The implementation of the search() method is very simple. It simply passes the search term to the lastNameIsLike() method of the PersonSpecifications class and gives the created specification object to the PersonRepository. The source code of the implementation of the search() method is given in following:
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import javax.annotation.Resource;
/**
* This implementation of the PersonService interface communicates with
* the database by using a Spring Data JPA repository.
* @author Petri Kainulainen
*/
@Service
public class RepositoryPersonService implements PersonService {
private static final Logger LOGGER = LoggerFactory.getLogger(RepositoryPersonService.class);
@Resource
private PersonRepository personRepository;
@Transactional(readOnly = true)
@Override
public List<Person> search(String searchTerm) {
LOGGER.debug("Searching persons with search term: " + searchTerm);
//Passes the specification created by PersonSpecifications class to the repository.
return personRepository.findAll(lastNameIsLike(searchTerm));
}
}
This solution is not perfect from the architectural point of view because it introduces a dependency between the service layer and the Spring Data JPA. A general guideline is that an upper layer should not have any knowledge about the implementation details of the layers located below it.
One solution to this problem would be to create a custom search method and integrate it with the generic repository abstraction as described in the reference manual of Spring Data JPA. However, this would mean that you would have to write a lot of boilerplate code which does not really add any value to your application. Also, since the goal of the Spring Data JPA is to reduce the amount of boilerplate code, I think that my solution is an acceptable compromise between over engineering and getting things done in a clean way.
Oh, this reminds me of something. We should not forget the unit test of the search() method. The source code of this unit test is given in following:
import org.junit.Test;
import org.springframework.data.jpa.domain.Specification;
import static junit.framework.Assert.assertEquals;
import static org.mockito.Mockito.*;
public class RepositoryPersonServiceTest {
private static final String SEARCH_TERM = "foo";
private RepositoryPersonService personService;
private PersonRepository personRepositoryMock;
@Before
public void setUp() {
personService = new RepositoryPersonService();
personRepositoryMock = mock(PersonRepository.class);
personService.setPersonRepository(personRepositoryMock);
}
@Test
public void search() {
List<Person> expected = new ArrayList<Person>();
when(personRepositoryMock.findAll(any(Specification.class))).thenReturn(expected);
List<Person> actual = personService.search(SEARCH_TERM);
verify(personRepositoryMock, times(1)).findAll(any(Specification.class));
verifyNoMoreInteractions(personRepositoryMock);
assertEquals(expected, actual);
}
}
What is Next?
I have now demonstrated to you how you can use the JPA criteria API with Spring Data JPA. As always, the example application of this blog entry is available at Github. The next part of my Spring Data JPA tutorial describes how you can use Querydsl for building queries with Spring Data JPA.