Petri Kainulainen » Programming

Spring Data JPA Tutorial Part Nine: Conclusions

Petri Kainulainen — Wed, 09 May 2012 17:00:02 +0000

This is the ninth and the last part of my Spring Data JPA tutorial. Now it is time to take a look of what we have learned, and how we should use it to build better software.

The contents of my Spring Data JPA tutorial is given in following:

The next step is to take a look of the advantages provided by Spring Data JPA and learn how we can use it in effective manner.

Promises Kept

The goal of the Spring Data JPA project is stated:

Implementing a data access layer of an application has been cumbersome for quite a while. Too much boilerplate code has to be written to execute simple queries as well as perform pagination, and auditing. Spring JPA aims to significantly improve the implementation of data access layers by reducing the effort to the amount that’s actually needed. As a developer you write your repository interfaces, including custom finder methods, and Spring will provide the implementation automatically.

This is a lot to promise. The question is, has Spring Data JPA achieved its goal. As you have learned from my tutorial, Spring Data JPA has following advantages over the “old school” method of building JPA repositories:

It provides CRUD capabilities to any domain object without the need of any boilerplate code.
It minimizes the amount of source code needed to write custom queries.
It offers simple abstractions for performing common tasks like sorting an pagination.

The thing is that implementing these functions have forced the developers to write a lot of boilerplate code in the past. Spring Data JPA changes all this. It minimizes the amount of code needed for implementing repositories.

Making It Work for You

I hate the term best practices because it has a negative effect on continuous improvement. However, I still feel that it is my responsibility to give you some guidance concerning the usage of Spring Data JPA. Here are my five cents about this matter:

Creating Queries

Your goal should be to use the Spring Data JPA to reduce the amount of code you have to write. With this goal in mind, I will you give some guidelines for creating queries with Spring Data JPA:

If the query can be build by using the query generation from method name strategy, I think you should use it. However, if the method name will become long and messy, I would consider using the @Query annotation in order to make the source code more readable.
Your second option for creating queries should be the @Query annotation and JPQL. This approach ensures that the you will not have to write more code than it is necessary.
Use JPA Criteria API or Querydsl only when you have no other options. Remember to extract the query generation logic into separate classes which creates Specification or Predicate objects (Depending on your technology selection).

JPA Criteria API Versus Querydsl

This is a question which should be asked by each developer. The usage of JPA Criteria API has been argued by claiming that you can use it to build type safe queries. Even though this is true, you can achieve the same goal by using the Querydsl. The first round ends in a draw, and we need to look for the answer from a bit deeper.

I will compare these two options in following categories: readability and testability.

Readability

Programs must be written for people to read, and only incidentally for machines to execute

– Abelson and Sussman on Programming.

With this guideline in mind, lets take a look of the implementations, which I created for my previous blog entries. The requirements of the search function are following:

It must be possible to search persons by using their last name as a search criteria.
The search function must return only such persons whose last name begins with the given search term.
The search must be case insensitive.

First, lets take a look of the implementation which is using the JPA Criteria API. The source code of my static meta model is given in following:

@StaticMetamodel(Person.class)
public class Person_ {
public static volatile SingularAttribute<Person, String> lastName;
}

The source code of my specification builder class is given in following:

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();
}
};
}
}

Second, the source code of the implementations which uses Querydsl is given in following:

public class PersonPredicates {

public static Predicate lastNameIsLike(final String searchTerm) {
QPerson person = QPerson.person;
return person.lastName.startsWithIgnoreCase(searchTerm);
}
}

This use case is pretty simple but it can still be used for demonstrating the differences of the JPA Criteria API and the Querydsl. The source code written by using Querydsl is clearly more readable than the one using the JPA Criteria API. Also, when the queries become more complex, the difference will be much bigger.

I would say that this round goes to Querydsl.

Testability

Software testability is the degree to which a software artifact (i.e. a software system, software module, requirements or design document) supports testing in a given context.

– Wikipedia.

In other words, the testability of your code defines the amount and quality of tests you can write at the same cost. If the testability of your code is high, you can write more tests with better quality than in a situation where the testability of your code is low.

Lets keep this measurement in mind when we will compare the unit tests written for implementations which were presented earlier.

First, lets check out the unit test for the implementation which uses the JPA Criteria API:

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);
}
}

Second, the unit test for the implementation using Querydsl is given in following:

public class PersonPredicatesTest {

private static final String SEARCH_TERM = "Foo";
private static final String EXPECTED_PREDICATE_STRING = "startsWithIgnoreCase(person.lastName,Foo)";

@Test
public void lastNameLike() {
Predicate predicate = PersonPredicates.lastNameIsLike(SEARCH_TERM);
String predicateAsString = predicate.toString();
assertEquals(EXPECTED_PREDICATE_STRING, predicateAsString);
}
}

After seeing the unit tests for both implementations, it should be obvious that writing unit tests for Querydsl is much easier than writing unit tests for the JPA Criteria API. Also, the unit test written to test the Querydsl predicate builder is much easier to understand. This is valuable because unit tests should also be used to document the behavior of the system.

At this point it should be clear that the winner of this round is Querydsl

PS. I am aware that unit tests do no ensure that the results returned by the created query are correct. However, I believe that they are still valuable because running unit tests is typically dramatically faster than running integration tests. It is still good to understand that in the context of integration testing, the testability of both implementations is equal.

Conclusions

The question is:

Should I use the JPA Criteria API or Querydsl?

It depends. If you are starting from scratch and you have a total control over your technology selections, you should at least consider using Querydsl. It makes your code easier to write and read. It also means that writing unit tests for your code is simpler and faster.

On the other hand, if you are modifying an existing system to use Spring Data JPA, and the existing code is using the JPA Criteria API, you might want to continue using it for the sake of consistency.

The fact is that there is no right answer for this question. The answer depends always from external requirements. The only thing you can do, is to ensure that you are aware of the different options, which are available to you. Only then you can choose the right tool for the task in hand.

There is Still More to Learn

The truth is that I have only scratched the surface of implementing JPA based repositories. I hope that the recommendations given in this blog entry will help you to take the first step, but I have to admit that there is a lot more to learn. I hope that the following resources will help you in your journey:

Reference Documentation

JPA Criteria API 2.0

Dynamic, Typesafe Query in JPA 2.0
JPA Criteria API by Samples Part I and Part II
Using the Criteria API to Create Queries – The Java EE 6 Tutorial

Querydsl

Spring Data JPA Tutorial Part Eight: Adding Functionality to a Repository

Petri Kainulainen — Sat, 28 Apr 2012 16:37:45 +0000

The previous part of my tutorial described how you can paginate query results with Spring Data JPA. The example application of this blog entry has the same functional requirements, but it will use Querydsl instead of JPA criteria API. This blog entry assumes that you have got experience from both Querydsl And Spring Data JPA. If this is not the case, please read my Spring Data JPA and Querydsl tutorial.

If you have read the previous parts of my Spring Data JPA tutorial, you might have noticed that the described solutions introduced a dependency between the service layer and the Spring Data JPA. This blog entry describes how you can eliminate that dependency (or at least most of it) by adding custom functionality to a Spring Data repository.

Adding Functionality to a Spring Data Repository

You can add custom functionality to a Spring Data repository by following these steps:

Create an interface for the custom functionality.
Implement the created interface.
Create the Spring Data JPA repository.

Enough with the theory. It is time to take a look, how I added custom functionality to the person repository of my example application.

Implementing The Example Application

This Section describes how I added the custom functionality to the person repository of my example application. The steps described previously are discussed with more details in following Subsections.

Creating an interface for the custom functionality.

In order to eliminate the dependency between the service layer and the Spring Data JPA, I created an interface called PaginatingPersonRepository. My goal was to move all pagination and sorting logic behind this interface. The source code of my custom interface is given in following:

public interface PaginatingPersonRepository {

/**
* Finds all persons stored in the database.
* @return
*/
public List<Person> findAllPersons();

/**
* Finds the count of persons stored in the database.
* @param searchTerm
* @return
*/
public long findPersonCount(String searchTerm);

/**
* Finds persons for the requested page whose last name starts with the given search term.
* @param searchTerm The used search term.
* @param page The number of the requested page.
* @return A list of persons belonging to the requested page.
*/
public List<Person> findPersonsForPage(String searchTerm, int page);
}

Implementing the Declared Interface

The next step is to create an implementation for the PaginatingPersonRepository interface. This implementation has following responsibilities:

Creating a new QueryDslJPARepository instance and delegating the method calls to it.
Obtaining the required Querydsl predicate when a search is performed.
Creating the Sort object which is used to specify the sort order of query results.
Creating the PageRequest object which id used the specify the wanted page and sort order of the search results.

The implementation of the PaginatingPersonRepository interface is using the PersonPredicates class for creating the required Querydsl predicates. The source code of this class is given in following:

public class PersonPredicates {

public static Predicate lastNameIsLike(final String searchTerm) {
QPerson person = QPerson.person;
return person.lastName.startsWithIgnoreCase(searchTerm);
}
}

The repository architecture of Spring Data JPA is looking for the custom implementation from the package where the repository was found. The name of the class implementing the custom interface must be constructed by adding a special postfix to the name of the custom interface. The default value of this postfix is Impl, but you can change the postfix by adding a repository-impl-postfix attribute to the namespace configuration element of Spring Data JPA. An example of this is given in following:

base-package="net.petrikainulainen.spring.datajpa.repository" repository-impl-postfix="FooBar"/>

However, I am going to use the default configuration. Thus, the name of my custom repository class must be PaginatingPersonRepositoryImpl. Its source code is given in following:

@Repository
public class PaginatingPersonRepositoryImpl implements PaginatingPersonRepository {

private static final Logger LOGGER = LoggerFactory.getLogger(PaginatingPersonRepositoryImpl.class);

protected static final int NUMBER_OF_PERSONS_PER_PAGE = 5;

@PersistenceContext
private EntityManager entityManager;

private QueryDslJpaRepository<Person, Long> personRepository;

public PaginatingPersonRepositoryImpl() {

}

@Override
public List<Person> findAllPersons() {
LOGGER.debug("Finding all persons");

//Passes the Sort object to the repository
return personRepository.findAll(sortByLastNameAsc());
}

@Override
public long findPersonCount(String searchTerm) {
LOGGER.debug("Finding person count with search term: " + searchTerm);

//Passes the predicate to the repository
return personRepository.count(lastNameIsLike(searchTerm));
}

@Override
public List<Person> findPersonsForPage(String searchTerm, int page) {
LOGGER.debug("Finding persons for page " + page + " with search term: " + searchTerm);

//Passes the predicate and the page specification to the repository
Page requestedPage = personRepository.findAll(lastNameIsLike(searchTerm), constructPageSpecification(page));

return requestedPage.getContent();
}

/**
* Returns a new object which specifies the the wanted result page.
* @param pageIndex The index of the wanted result page
* @return
*/
private Pageable constructPageSpecification(int pageIndex) {
Pageable pageSpecification = new PageRequest(pageIndex, NUMBER_OF_PERSONS_PER_PAGE, sortByLastNameAsc());
return pageSpecification;
}

/**
* Returns a Sort object which sorts persons in ascending order by using the last name.
* @return
*/
private Sort sortByLastNameAsc() {
return new Sort(Sort.Direction.ASC, "lastName");
}

/**
* An initialization method which is run after the bean has been constructed.
* This ensures that the entity manager is injected before we try to use it.
*/
@PostConstruct
public void init() {
JpaEntityInformation<Person, Long> personEntityInfo = new JpaMetamodelEntityInformation<Person, Long>(Person.class, entityManager.getMetamodel());
personRepository = new QueryDslJpaRepository<Person, Long>(personEntityInfo, entityManager);
}

/**
* This setter method should be used only by unit tests
* @param personRepository
*/
protected void setPersonRepository(QueryDslJpaRepository<Person, Long> personRepository) {
this.personRepository = personRepository;
}
}

We also have to verify that the created repository implementation is working as expected. This means that unit tests must be written. The source code of the unit tests is given in following:

public class PaginatingPersonRepositoryImplTest {

private static final int PAGE_INDEX = 2;
private static final long PERSON_COUNT = 5;
private static final String PROPERTY_LASTNAME = "lastName";
private static final String SEARCH_TERM = "searchTerm";

private PaginatingPersonRepositoryImpl repository;

private QueryDslJpaRepository personRepositoryMock;

@Before
public void setUp() {
repository = new PaginatingPersonRepositoryImpl();

personRepositoryMock = mock(QueryDslJpaRepository.class);
repository.setPersonRepository(personRepositoryMock);
}

@Test
public void findAllPersons() {
repository.findAllPersons();

ArgumentCaptor<Sort> sortArgument = ArgumentCaptor.forClass(Sort.class);
verify(personRepositoryMock, times(1)).findAll(sortArgument.capture());

Sort sort = sortArgument.getValue();
assertEquals(Sort.Direction.ASC, sort.getOrderFor(PROPERTY_LASTNAME).getDirection());
}

@Test
public void findPersonCount() {
when(personRepositoryMock.count(any(Predicate.class))).thenReturn(PERSON_COUNT);

long actual = repository.findPersonCount(SEARCH_TERM);

verify(personRepositoryMock, times(1)).count(any(Predicate.class));
verifyNoMoreInteractions(personRepositoryMock);

assertEquals(PERSON_COUNT, actual);
}

@Test
public void findPersonsForPage() {
List<Person> expected = new ArrayList<Person>();
Page foundPage = new PageImpl<Person>(expected);

when(personRepositoryMock.findAll(any(Predicate.class), any(Pageable.class))).thenReturn(foundPage);

List<Person> actual = repository.findPersonsForPage(SEARCH_TERM, PAGE_INDEX);

ArgumentCaptor<Pageable> pageSpecificationArgument = ArgumentCaptor.forClass(Pageable.class);
verify(personRepositoryMock, times(1)).findAll(any(Predicate.class), pageSpecificationArgument.capture());
verifyNoMoreInteractions(personRepositoryMock);

Pageable pageSpecification = pageSpecificationArgument.getValue();

assertEquals(PAGE_INDEX, pageSpecification.getPageNumber());
assertEquals(PaginatingPersonRepositoryImpl.NUMBER_OF_PERSONS_PER_PAGE, pageSpecification.getPageSize());
assertEquals(Sort.Direction.ASC, pageSpecification.getSort().getOrderFor(PROPERTY_LASTNAME).getDirection());

assertEquals(expected, actual);
}
}

Creating the Spring Data JPA repository

Now it is time to make the custom functionality available to the users of the repository. This is done by making the repository interface extend the created custom interface. As you might remember, the repository interface of my example application is called PersonRepository. Its source code is given in following:

public interface PersonRepository extends JpaRepository<Person, Long>, PaginatingPersonRepository, QueryDslPredicateExecutor<Person> {

}

Using the Custom Functionality

Now when the logic related to pagination and sorting has been moved to the custom repository implementation, the service layer will basically just delegate the method calls forward to the repository and act as a transaction boundary. The PersonService interface has stayed intact, but there has been some changes to the following methods of the RepositoryPersonService class:

public long count(String searchTerm)
public List findAll()
public List search(String searchTerm, int pageIndex)

All these methods are simply delegating the method call forward to the repository. The source code of the relevant parts of the RepositoryPersonService class is given in following:

Changes made to the RepositoryPersonService class means that its unit tests must be changed as well. The source code of the changed unit tests is given in following:

public class RepositoryPersonServiceTest {

private static final int PAGE_INDEX = 1;
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 count() {
personService.count(SEARCH_TERM);

verify(personRepositoryMock, times(1)).findPersonCount(SEARCH_TERM);
verifyNoMoreInteractions(personRepositoryMock);
}

@Test
public void findAll() {
List<Person> persons = new ArrayList<Person>();
when(personRepositoryMock.findAllPersons()).thenReturn(persons);

List<Person> returned = personService.findAll();

verify(personRepositoryMock, times(1)).findAllPersons();
verifyNoMoreInteractions(personRepositoryMock);

assertEquals(persons, returned);
}

@Test
public void search() {
personService.search(SEARCH_TERM, PAGE_INDEX);

verify(personRepositoryMock, times(1)).findPersonsForPage(SEARCH_TERM, PAGE_INDEX);
verifyNoMoreInteractions(personRepositoryMock);
}
}

What is Next?

I have now described to you how you can add custom functionality to a Spring Data repository. Even though this can be a handy in some situations, I think that the situation described in this blog entry is not one of them. To be honest, the benefits obtained from the proposed solution are purely theoretical, and I cannot recommend using this approach for eliminating the dependency between the service layer and Spring Data JPA. You simply don’t get enough bang for your buck.

Sometimes adding functionality to a single repository is not enough. You can also add custom functionality to all repositories. The implementation of this is left as an exercise for the reader.

The last part of my Spring Data JPA tutorial will summarize what we have learned and give some suggestions about the usage of Spring Data JPA.

PS. If you want to a take a closer look of my example application, you can get it from Github.

Spring Data JPA Tutorial Part Seven: Pagination

Petri Kainulainen — Mon, 23 Apr 2012 15:45:54 +0000

The previous part of my Spring Data JPA tutorial described how you can sort query results with Spring Data JPA. This blog entry will describe how you can paginate the query results by using Spring Data JPA. In order to demonstrate the pagination support of Spring Data JPA, I will add two new requirements for my example application:

The person search results should be paginated.
The maximum number of persons shown on a single search result page is five.

I will explain the pagination support of Spring Data JPA and my example implementation in following Sections.

Pagination with Spring Data JPA

The key of component of the Spring Data JPA pagination support is the Pageable interface which is implemented by PageRequest class. You can get a specific page of your query results by following these steps:

Create an instance of the PageRequest class.
Pass the created object as a parameter to the correct repository method.

The available repository methods are described in following:

If you want to simply paginate all objects found from the database, you should use the public Page findAll(Pageable pageable) method of the JpaRepository interface.
If you are building your queries by using the query generation from method name strategy, you can paginate the query results by passing the Pageable instance as a parameter of your method. Check the Spring Data JPA reference manual for more details (1.3.2.3 Special Parameter Handling).
If you are using the JPA criteria API for building your query, you should use the public Page findAll(Specification specification, Pageable pageable) method of the JpaSpecificationExecutor interface.
If you are building your queries with Querydsl, you should use the public Page findAll(Predicate predicate, Pageable pageable) method of the QueryDslPredicateExercutor interface.

After you have obtained the requested page, you can get a list of entities by calling the getContent() method of the Page interface.

Enough with the theory, lets take a look how the given requirements can be implemented with JPA criteria API.

Adding Pagination to Person Search Results

The given requirements can be implemented with JPA criteria API by following these steps:

Obtain the wanted page number.
Create the needed Specification instance.
Create the instance of a PageRequest class.
Pass the created Specification and PageRequest objects to the person repository.

First, I modified the search() method of the PersonService interface. In order to obtain the wanted page from the database, the repository needs to know what page it should be looking for. Thus, I had to add a new parameter to the search() method. The name of this parameter is pageIndex and it specifies the index of the wanted page. The declaration of the new search() methods is given in following:

public interface PersonService {

/**
* Searches persons for a given page by using the given search term.
* @param searchTerm
* @param pageIndex
* @return A list of persons whose last name begins with the given search term and who are belonging to the given page.
* If no persons is found, this method returns an empty list. This search is case insensitive.
*/
public List<Person> search(String searchTerm, int pageIndex);
}

Second, since I am using the JPA criteria API for building the actual query, the RepositoryPersonService will obtain the needed specification by calling the static lastNameIsLike() method of PersonSpecifications class. The source code of the PersonSpecifications class is given in following:

public class PersonSpecifications {

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();
}
};
}
}

Third, I need to create an instance of a PageRequest class and pass this instance to the PersonRepository. I created a private method called constructPageSpecification() to the RepositoryPersonService. This method simply creates a new instance of the PageRequest object and returns the created instance. The search method obtains the PageRequest instance by calling the constructPageSpecification() method.

The last step is to pass the created objects forward to the PersonRepository. The source code of the relevant parts of the RepositoryPersonService is given in following:

@Service
public class RepositoryPersonService implements PersonService {

private static final Logger LOGGER = LoggerFactory.getLogger(RepositoryPersonService.class);

protected static final int NUMBER_OF_PERSONS_PER_PAGE = 5;

@Resource
private PersonRepository personRepository;

@Transactional(readOnly = true)
@Override
public List<Person> search(String searchTerm, int pageIndex) {
LOGGER.debug("Searching persons with search term: " + searchTerm);

//Passes the specification created by PersonSpecifications class and the page specification to the repository.
Page requestedPage = personRepository.findAll(lastNameIsLike(searchTerm), constructPageSpecification(pageIndex));

return requestedPage.getContent();
}

/**
* Returns a new object which specifies the the wanted result page.
* @param pageIndex The index of the wanted result page
* @return
*/
private Pageable constructPageSpecification(int pageIndex) {
Pageable pageSpecification = new PageRequest(pageIndex, NUMBER_OF_PERSONS_PER_PAGE, sortByLastNameAsc());
return pageSpecification;
}

/**
* Returns a Sort object which sorts persons in ascending order by using the last name.
* @return
*/
private Sort sortByLastNameAsc() {
return new Sort(Sort.Direction.ASC, "lastName");
}
}

I also had to modify the unit tests of the RepositoryPersonService class. The source code of the modified unit test is given in following:

public class RepositoryPersonServiceTest {

private static final long PERSON_COUNT = 4;
private static final int PAGE_INDEX = 1;
private static final Long PERSON_ID = Long.valueOf(5);
private static final String FIRST_NAME = "Foo";
private static final String FIRST_NAME_UPDATED = "FooUpdated";
private static final String LAST_NAME = "Bar";
private static final String LAST_NAME_UPDATED = "BarUpdated";
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>();
Page expectedPage = new PageImpl(expected);
when(personRepositoryMock.findAll(any(Specification.class), any(Pageable.class))).thenReturn(expectedPage);

List<Person> actual = personService.search(SEARCH_TERM, PAGE_INDEX);

ArgumentCaptor<Pageable> pageArgument = ArgumentCaptor.forClass(Pageable.class);
verify(personRepositoryMock, times(1)).findAll(any(Specification.class), pageArgument.capture());
verifyNoMoreInteractions(personRepositoryMock);

Pageable pageSpecification = pageArgument.getValue();

assertEquals(PAGE_INDEX, pageSpecification.getPageNumber());
assertEquals(RepositoryPersonService.NUMBER_OF_PERSONS_PER_PAGE, pageSpecification.getPageSize());
assertEquals(Sort.Direction.ASC, pageSpecification.getSort().getOrderFor("lastName").getDirection());

assertEquals(expected, actual);
}
}

I have now described the parts of the source code which are using Spring Data JPA for implementing the new requirements. However, my example application has a lot of web application specific “plumbing” code in it. I recommend that you take a look of the source code because it can help you to get a better view of the big picture.

What is Next?

I have now demonstrated to you how you can paginate your query results with Spring Data JPA. If you are interested of seeing my example application in action, you can get it from Github. The next part of my Spring Data JPA tutorial will describe how you can add custom functionality to your repository.

Spring Data JPA Tutorial Part Six: Sorting

Petri Kainulainen — Sun, 08 Apr 2012 11:00:19 +0000

The fifth part of my Spring Data JPA tutorial described how you can create advanced queries with Spring Data JPA and Querydsl. This blog entry will describe how you can use Spring Data JPA for sorting the query results. As an example I will be adding two new requirements for my example application:

The list of persons shown in the front page should be sorted in ascending order by using the last name of a person.
The search results should be sorted in ascending order by using the last name of a person.

Spring Data JPA offers four different ways to sort the query results. Each of these approaches is described with more details in the following Sections.

Sorting with Method Name

If you are building your queries by using the query generation from method name strategy, you can sort the query results by using the OrderBy keyword in the name of your query method. If you want to search for persons whose last name matches with the given parameter and sort the query results, you can use the following query methods:

//Results are sorted in ascending order
public List<Person> findByLastNameOrderByLastNameAsc(String lastName);

//Results are sorted in descending order
public List<Person> findByLastNameOrderByLastNameDesc(String lastName)

Sorting with JPQL

If you are creating query method by using either @NamedQuery or @Query annotation as explained in the third part of this tutorial, you can sort the query results by using the ORDER BY keyword of the JPQL. For example, if you want to get all persons and sort the query results in ascending order by using the last name of a person, you can use the following query:

SELECT p FROM Person p ORDER BY p.lastName ASC

You can now consult the third part of this tutorial for finding out how you can use the @NamedQuery or @Query annotation to implement the actual query method.

Sorting with Sort Class

The second way to sort query results with Spring Data JPA is to use the org.springframework.data.domain.Sort class. You can use this approach for sorting the query results by following these steps:

Create an instance of the Sort class.
Pass the created instance as a parameter to the correct method.

I am going to describe to you three different ways for sorting the query results by using the Sort class. After that I will choose one of those methods and implement my first requirement with the selected method.

Query Generation by Method Name

You can pass the Sort object as a parameter to a query method, which uses the query generation by method name strategy. For instance, if you want search persons by last name and sort the results of the created query, you should add following method to your repository interface:

public List<Person> findByLastName(String lastName, Sort sort);

If you are interested of finding out more information about this query generation strategy, you should read the third part of this tutorial.

JpaRepository

As you might remember from the previous parts of this tutorial, Spring Data JPA repositories are just interfaces which extend other interfaces. One of those special interfaces is the JpaRepository interface. This interface declares the public List findAll(Sort sort) method, which returns a list of all entities and sorts the entities in the order specified by the Sort object given as a parameter. If you are interested of obtaining a sorted list of all entities, using this method is the best way to do it.

The second part of my Spring Data JPA tutorial provides more information about the usage of the JpaRepository interface.

JPA Criteria API

If you are creating your queries with the JPA criteria API, your repository interface must extend the JpaSpecificationExecutor interface. This interface declares the public List findAll(Specification spec, Sort sort) method, which returns a list of entities matching with the Specification given as a parameter. The returned entities are sorted in the order specified by the Sort object given as a parameter.

So, if you are interested of sorting the results of a query constructed by using the JPA criteria API, you can do it by using the described method. If you need more information about Spring Data JPA and the JPA criteria API, you can read the fourth part of this tutorial.

Example

I am going to describe next how you can implement the first requirement by using the findAll(Sort sort) method provided by the JpaRepository interface.

First, my repository interface must extend the JpaRepository interface. The source code of the PersonRepository is given in following:

public interface PersonRepository extends JpaRepository<Person, Long> {

}

Second, I created a private method called sortByLastNameAsc() to RepositoryPersonService class. This method is used in the findAll() method to obtain an instance of the Sort class. Third, I passed the obtained Sort object to the findAll() method of the JpaRepository interface. The source code of the relevant parts of the RepositoryPersonService is given in following:

@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> findAll() {
LOGGER.debug("Finding all persons");
//Passes the Sort object to the repository.
return personRepository.findAll(sortByLastNameAsc());
}

/**
* Returns a Sort object which sorts persons in ascending order by using the last name.
* @return
*/
private Sort sortByLastNameAsc() {
return new Sort(Sort.Direction.ASC, "lastName");
}
}

The last step was to fix the unit test of the findAll() method. The source code of the fixed unit test is given in following:

public class RepositoryPersonServiceTest {

private RepositoryPersonService personService;

private PersonRepository personRepositoryMock;

@Before
public void setUp() {
personService = new RepositoryPersonService();

personRepositoryMock = mock(PersonRepository.class);
personService.setPersonRepository(personRepositoryMock);
}

@Test
public void findAll() {
List<Person> persons = new ArrayList<Person>();
when(personRepositoryMock.findAll(any(Sort.class))).thenReturn(persons);

List<Person> returned = personService.findAll();

ArgumentCaptor<Sort> sortArgument = ArgumentCaptor.forClass(Sort.class);
verify(personRepositoryMock, times(1)).findAll(sortArgument.capture());

verifyNoMoreInteractions(personRepositoryMock);

Sort actualSort = sortArgument.getValue();
assertEquals(Sort.Direction.ASC, actualSort.getOrderFor("lastName").getDirection());

assertEquals(persons, returned);
}
}

I have now demonstrated to you, how you can sort the persons presented in the front page of my example application in ascending order by using the last name of a person.

Sorting with Querydsl

If you are using Querydsl for building your queries, you can sort the query results by following these steps:

Create an instance of the com.mysema.query.types.OrderSpecifier class.
Pass the created instance as a parameter to the findAll(Predicate predicate, OrderSpecifier order) method of the QueryDslPredicateExecutor interface.

I will now describe to you how you can implement my second requirement with Querydsl.

First, I am ensuring that my repository extends the QueryDslPredicateExecutor interface. The source code of the PersonRepository is given in following:

public interface PersonRepository extends JpaRepository<Person, Long>, QueryDslPredicateExecutor<Person> {

}

Second, I created a class called PersonPredicates which has one method: lastNameIsLike(). This method is used to build the required query predicate. The source code of this class is given in following:

public class PersonPredicates {

public static Predicate lastNameIsLike(final String searchTerm) {
QPerson person = QPerson.person;
return person.lastName.startsWithIgnoreCase(searchTerm);
}
}

The next step was to made some changes to the search() method of the RepositoryPersonService class. This method is explained with more details in following:

The predicate is still obtained by calling the lastNameIsLike() method of the PersonPredicates class.
The OrderSpecifier instance is obtained by calling a private orderByLastNameAsc() method of RepositoryPersonService class.
The predicate and the OrderSpecifier instance are passed as a parameter to the findAll(Predicate predicate, OrderSpecifier order) method of my repository implementation.

The source code of the relevant parts of the RepositoryPersonService class is given in following:

@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 PersonPredicates class and the OrderSpecifier object to the repository.
Iterable<Person> persons = personRepository.findAll(lastNameIsLike(searchTerm), orderByLastNameAsc());

return constructList(persons);
}

/**
* Returns an OrderSpecifier object which sorts person in ascending order by using the last name.
* @return
*/
private OrderSpecifier<String> orderByLastNameAsc() {
return QPerson.person.lastName.asc();
}

private List<Person> constructList(Iterable<Person> persons) {
List<Person> list = new ArrayList<Person>();
for (Person person: persons) {
list.add(person);
}
return list;
}
}

The last step was to the fix the unit test of the search() method. The source code of the fixed unit test is given in following:

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(BooleanExpression.class), any(OrderSpecifier.class))).thenReturn(expected);

List<Person> actual = personService.search(SEARCH_TERM);

ArgumentCaptor<OrderSpecifier> orderArgument = ArgumentCaptor.forClass(OrderSpecifier.class);
verify(personRepositoryMock, times(1)).findAll(any(BooleanExpression.class), orderArgument.capture());

verifyNoMoreInteractions(personRepositoryMock);

OrderSpecifier actualOrder = orderArgument.getValue();
assertEquals(Order.ASC, actualOrder.getOrder());
assertEquals(QPerson.person.lastName, actualOrder.getTarget());

assertEquals(expected, actual);
}
}

I have now demonstrated to you how you can you use Querydsl to sort the person search results in ascending order by using the last name of a person.

What is Next?

I have now described to you three different ways to sort the query results with Spring Data JPA. I have also implemented a fully functional example application, which is available at Github. The next part of my tutorial describes how you can implement pagination with Spring Data JPA.

Spring Data JPA Tutorial Part Five: Querydsl

Petri Kainulainen — Tue, 28 Feb 2012 20:20:56 +0000

The fourth part of my Spring Data JPA tutorial described how you can implement more advanced queries with the JPA criteria API. As you might remember, the goal of the previous part of this tutorial was to implement a search function which returns only such persons whose last name begins with the given search term. This blog entry will describe how you use Querydsl and Spring Data JPA for the same purpose.

Lets get to work and see how you can fulfill this requirement.

Required Steps

The steps needed to implement the given requirement are following:

Configuring the Maven integration of QueryDSL
Generating the Querydsl query type
Implementing the predicate builder class
Extending the repository to support Querydsl predicates
Using the created repository

Each of these steps is described with more details in following Sections.

Configuring the Maven Integration of Querydsl

The configuration of the maven integration of Querydsl consists two smaller phases:

First, you need to add the Querydsl dependencies to your pom.xml file. The needed dependencies are:

Querydsl core which provides the core functions of Querydsl.
Querydsl APT integration which provides support for the APT based code generation.
Querydsl JPA which provides support for the JPA annotations.

The relevant part of the pom.xml is given in following:

>
>com.mysema.querydsl>
>querydsl-core>
>2.3.2>
>

>
>com.mysema.querydsl>
>querydsl-apt>
>2.3.2>
>

>
>com.mysema.querydsl>
>querydsl-jpa>
>2.3.2>
>

Querydsl uses the Annotation Processing Tool of Java 6 for code generation. Thus, the next phase is to add the the configuration of the Maven APT plugin to the plugins section of your pom.xml file. The relevant part of the pom.xml looks following:

>
>com.mysema.maven>
>maven-apt-plugin>
>1.0.2>
>
>
>generate-sources>
>
>process>
>
>

>target/generated-sources>

>com.mysema.query.apt.jpa.JPAAnnotationProcessor>
>
>
>
>

Generating the Querydsl Query Type

The next step is to generate the Querydsl query type which is used to construct queries with Querydsl. All you have to do is to build your project and the query type is generated under the target/generated-sources directory. If you open this directory, you should notice that the query type class is created in the same package than the Person class. Since the name of the model class is called Person, the name of the Querydsl query type is QPerson.

NOTE: Remember to add the target/generated-sources directory as a source directory for your project before moving forward (Check the documentation of your IDE for more details about this).

Implementing the Predicate Builder Class

In my previous part of this tutorial, I used a builder class with static methods to build the actual Specification instances. I am following the same principle when building the Querydsl predicates by using the generated QPerson query type. The source code of my predicate builder class is given in following:

/**
* A class which is used to create Querydsl predicates.
* @author Petri Kainulainen
*/
public class PersonPredicates {

public static Predicate lastNameIsLike(final String searchTerm) {
QPerson person = QPerson.person;
return person.lastName.startsWithIgnoreCase(searchTerm);
}
}

At first I had no idea how my builder class could be tested, because the information about unit testing Querydsl is kind of hard to find. Luckily I was able to find a google groups thread, which discusses about this matter. After reading that thread I decided that testing the return value of toString() method of the created predicate is enough because this scenario is quite simple. The source code of my unit test is given in following:

If you have read my blog entry about using the JPA criteria API with Spring Data JPA, you might remember that the unit test of my lastNameLike() method was rather long and looked a bit messy. The problem is that mocking the JPA criteria API becomes a lot more complex when you are building more complex queries. This means that writing pure unit tests for your code takes longer and longer.

My unit test for the Querydsl implementation of the same method is the exact opposite. It is short and looks quite clean. And more importantly, it is much faster to write. This means that you can concentrate on adding value to your application instead of verifying its behavior.

Extending the Repository to Support Querydsl Predicates

Extending the repository to support Querydsl predicates is quite straightforward process. All you have to do is to extend the QueryDslPredicateExecutor interface. This gives you access to findAll(Predicate predicate) method. This returns all entities fulfilling the search conditions which are specified by the predicate. The source code of my PersonRepository interface is given in following:

Using the Created Repository

The last step is to implement the service class which uses the created predicate builder and the repository. The PersonService interface contains a method search(String searchTerm) which returns a list of persons matching with the given search term. 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);
}

Implementing the search method is pretty straightforward. My implementation uses the PersonPredicates class to obtain the Querydsl predicate and passes the received predicate forward to the PersonRepository. Since the findAll() method returns Iterable instead of List, I had to add an extra method which converts the returned Iterable into a List. The source code of the search(String searchTerm) method is given in following:

The same architectural remarks which I made in my last blog entry are also valid in this case. However, the end result looks pretty clean and simple. The only thing which is left, is to write a unit test for the search method. The source code of the unit test is given in following:

What is Next?

I have now demonstrated to you how you can build advanced queries with Spring Data JPA and Querydsl. As always, the example application described in this blog entry is available at Github. The next part of my tutorial describes the sorting capabilities of Spring Data JPA.

Installing PostgreSQL 9.1 to Windows 7 from the Binary Zip Distribution

Petri Kainulainen — Thu, 23 Feb 2012 17:41:10 +0000

Today I was helping a colleague of mine to install and configure PostgreSQL 9.1 to his laptop which was running on Windows 7. We had several problems with the one click installer and after the installation process was finished, we could not start the PostgreSQL database.

Since we could not solve this problem in a reasonable amount of time, we had to use the binary zip distribution. The installation process was quite straightforward but it took some time because I could not find a decent tutorial about it. This blog entry is written to fill that void. Also, even though this blog entry describes the installation process of PostgreSQL 9.1, these instructions should be valid for older versions of PostgreSQL as well.

The required steps are described with more details in later Sections of this blog entry.

Preparing the PostgreSQL 9.1 Installation

The first step is to download the binary zip distribution.

After you have downloaded the binary zip distribution, you can unzip the binary distribution to the preferred directory. When this is done, the target directory should contain a directory called ‘pgsql’. This directory contains the binaries of PostgreSQL 9.1. I will refer this directory simply as POSTGRESQL_ROOT (Remember to replace the string POSTGRESQL_ROOT with the actual directory path of you installation when following these instructions).

The next step is to create the data and log directories for your PostgreSQL installation. This is done by creating the following directories to the POSTGRESQL_ROOT directory:

The ‘data’ directory contains the data files of your PostgreSQL installation.
The ‘log’ directory contains the logs of your PostgreSQL installation.

You have now finished the needed preparations and can move on to the next phase of the installation process.

Configuring the PostgreSQL 9.1 Installation

The next step is to create a new PostgreSQL database cluster. You can do this by using the initdb command which is found from the POSTGRESQL_ROOT\bin directory. You can create the database cluster by running the following command from the bin directory of your PostgreSQL installation:

initdb -U postgres -A password -E utf8 -W -d POSTGRESQL_ROOT\data

The command line parameters of the initdb command are described in following:

-U postgres means that the superuser account of your database is called ‘postgres’.
-A password means that password authentication is used.
-E utf8 means that the default encoding will be UTF-8.
-W means that you will enter the superuser password manually.
-d POSTGRESQL_ROOT\data specifies the data directory of your PostgreSQL installation.

After you have successfully created the database cluster, your PostgreSQL installation is ready to be used. You can start and stop your database instance by using the following commands:

The database can be started by running the following command:

"POSTGRESQL_ROOT/bin/pg_ctl" -D "POSTGRESQL_ROOT/data" -l "POSTGRESQL_ROOT/log/pgsql.log" start

The database can be stopped by running the following command:

"POSTGRESQL_ROOT/bin/pg_ctl" -D “POSTGRESQL_ROOT/data" -l "POSTGRESQL_ROOT/log/pgsql.log" stop

To make things as easy as possible, you should create new shortcuts to your desktop and use them for starting and stopping the database server.

Congratulations

Your PostgreSQL 9.1 installation should now be functional. The next step is to start the database server by using the created shortcut and verify that you can connect to your database instance. You can use the PgAdmin database management tool for this task and congratulate yourself for a job well done.

Spring Data JPA Tutorial Part Four: JPA Criteria Queries

Petri Kainulainen — Sun, 12 Feb 2012 18:45:37 +0000

The third part of my Spring Data JPA tutorial described 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 the toPredicate() method.

Before going in to the details, I will introduce the source code of my static metal model class which is used to create type safe queries with the JPA criteria API. The source code of the Person_ class is given in following:

/**
* 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 called PersonSpecifications and its source code given in following:

/**
* 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:

/**
* @author Petri Kainulainen
*/
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 the Specifications 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 the findAll(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:

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:

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:

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:

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.

Spring Data JPA Tutorial Part Three: Custom Queries with Query Methods

Petri Kainulainen — Sun, 05 Feb 2012 17:55:56 +0000

The second part of my Spring Data JPA tutorial described how you can create a simple CRUD application with Spring Data JPA. This blog entry will describe how you can use query methods for creating custom queries with Spring Data JPA. In order to have a reasonable example, I have created three new requirements for my example application:

It must be possible to search persons by using their last name as a search criteria.
The search function must return only such persons which last name is an exact match with the given search criteria.
The search must be case insensitive.

It is time to get to work and start extending the example application.

Required Steps

The steps required to fulfill the given requirements are following:

Creating a query method.
Using the created query method.

Spring Data JPA provides three different approaches for creating custom queries with query methods. Each of these approaches is described in following.

Query Creation from Method Name

Spring Data JPA has a built in query creation mechanism which can be used for parsing queries straight from the method name of a query method. This mechanism first removes common prefixes from the method name and parses the constraints of the query from the rest of the method name. The query builder mechanism is described with more details in Defining Query Methods Subsection of Spring Data JPA reference documentation.

Using this approach is quite simple. All you have to do is to ensure that the method names of your repository interface are created by combining the property names of an entity object and the supported keywords. The Query Creation Subsection of the Spring Data JPA reference documentation has nice examples concerning the usage of supported keywords.

The source code of the repository method which is using this approach is given in following:

/**
* 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> {

/**
* Finds persons by using the last name as a search criteria.
* @param lastName
* @return A list of persons which last name is an exact match with the given last name.
* If no persons is found, this method returns an empty list.
*/
public List<Person> findByLastName(String lastName);
}

The strength of this approach is that it is rather fast to implement simple queries. On the other hand, if your query has many parameters, your method name will be rather long and ugly. Also, if the keyword you need is not supported by Spring Data JPA, you are out of luck.

A good example of this is the fact that at the moment you cannot use the lower keyword in your method names. This means that this approach cannot be used to fulfill the requirements which I specified in the beginning.

JPA Named Queries

Spring Data JPA provides also support for the JPA Named Queries. You have got following alternatives for declaring the named queries:

You can use either named-query XML element or @NamedQuery annotation to create named queries with the JPA query language.
You can use either named-native-query XML element or @NamedNative query annotation to create queries with SQL if you are ready to tie your application with a specific database platform.

The only thing you have to do to use the created named queries is to name the query method of your repository interface to match with the name of your named query. I have chosen to specify the named query by using @NamedQuery annotation in my entity class.

The source code of the Person class is given in following:

/**
* An entity class which contains the information of a single person.
* @author Petri Kainulainen
*/
@Entity
@NamedQuery(name = "Person.findByName", query = "SELECT p FROM Person p WHERE LOWER(p.lastName) = LOWER(?1)")
@Table(name = "persons")
public class Person {

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

@Column(name = "creation_time", nullable = false)
private Date creationTime;

@Column(name = "first_name", nullable = false)
private String firstName;

@Column(name = "last_name", nullable = false)
private String lastName;

@Column(name = "modification_time", nullable = false)
private Date modificationTime;

@Version
private long version = 0;

public Long getId() {
return id;
}

/**
* Gets a builder which is used to create Person objects.
* @param firstName The first name of the created user.
* @param lastName The last name of the created user.
* @return A new Builder instance.
*/
public static Builder getBuilder(String firstName, String lastName) {
return new Builder(firstName, lastName);
}

public Date getCreationTime() {
return creationTime;
}

public String getFirstName() {
return firstName;
}

public String getLastName() {
return lastName;
}

/**
* Gets the full name of the person.
* @return The full name of the person.
*/
@Transient
public String getName() {
StringBuilder name = new StringBuilder();

name.append(firstName);
name.append(" ");
name.append(lastName);

return name.toString();
}

public Date getModificationTime() {
return modificationTime;
}

public long getVersion() {
return version;
}

public void update(String firstName, String lastName) {
this.firstName = firstName;
this.lastName = lastName;
}

@PreUpdate
public void preUpdate() {
modificationTime = new Date();
}

@PrePersist
public void prePersist() {
Date now = new Date();
creationTime = now;
modificationTime = now;
}

@Override
public String toString() {
return ToStringBuilder.reflectionToString(this);
}

/**
* A Builder class used to create new Person objects.
*/
public static class Builder {
Person built;

/**
* Creates a new Builder instance.
* @param firstName The first name of the created Person object.
* @param lastName The last name of the created Person object.
*/
Builder(String firstName, String lastName) {
built = new Person();
built.firstName = firstName;
built.lastName = lastName;
}

/**
* Builds the new Person object.
* @return The created Person object.
*/
public Person build() {
return built;
}
}

/**
* This setter method should only be used by unit tests.
* @param id
*/
protected void setId(Long id) {
this.id = id;
}
}

The relevant part of my PersonRepository interface looks following:

/**
* 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> {

/**
* Finds person by using the last name as a search criteria.
* @param lastName
* @return A list of persons whose last name is an exact match with the given last name.
* If no persons is found, this method returns null.
*/
public List<Person> findByName(String lastName);
}

Using named queries is valid option if your application is small or if you have to use native queries. If your application has a lot of custom queries, this approach will litter the code of your entity class with query declarations (You can of course use the XML configuration to avoid this but in my opinion this approach is even more horrible).

@Query Annotation

The @Query annotation can be used to create queries by using the JPA query language and to bind these queries directly to the methods of your repository interface. When the query method is called, Spring Data JPA will execute the query specified by the @Query annotation (If there is a collision between the @Query annotation and the named queries, the query specified by using @Query annotation will be executed).

The source code of the repository method which is implemented by using this approach is given in following:

/**
* 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> {

/**
* Finds a person by using the last name as a search criteria.
* @param lastName
* @return A list of persons whose last name is an exact match with the given last name.
* If no persons is found, this method returns an empty list.
*/
@Query("SELECT p FROM Person p WHERE LOWER(p.lastName) = LOWER(:lastName)")
public List<Person> find(@Param("lastName") String lastName);
}

This approach gives you access to the JPA query language and keeps your queries in the repository layer where they belong. On the other hand, you cannot use the @Query annotation (I will describe more advanced strategies in the next parts of this tutorial) if the JPA query language cannot be used to create the query you need.

Using Created Query Methods

I have now described you three ways to create query methods with Spring Data JPA. The next step is to take a look of the service class which uses the created query methods.

The SearchType enumeration identifies the used query method. Its source code is given in following:

/**
* Describes the search type of the search. Legal values are:
*

METHOD_NAME which means that the query is obtained from the method name of the query method.

NAMED_QUERY which means that a named query is used.

QUERY_ANNOTATION which means that the query method annotated with @Query annotation is used.

* @author Petri Kainulainen
*/
public enum SearchType {
METHOD_NAME,
NAMED_QUERY,
QUERY_ANNOTATION;
}

The SearchDTO is a simple DTO object which contains the search term given by the user and identifies the used query method. Its source code is given in following:

/**
* A DTO class which is used as a form object in the search form.
* @author Petri Kainulainen
*/
public class SearchDTO {

private String searchTerm;

private SearchType searchType;

public SearchDTO() {

}

public String getSearchTerm() {
return searchTerm;
}

public void setSearchTerm(String searchTerm) {
this.searchTerm = searchTerm;
}

public SearchType getSearchType() {
return searchType;
}

public void setSearchType(SearchType searchType) {
this.searchType = searchType;
}

@Override
public String toString() {
return ToStringBuilder.reflectionToString(this);
}
}

The PersonService interface has got one new method . The relevant part of the PersonService interface is described in following:

/**
* Declares methods used to obtain and modify person information.
* @author Petri Kainulainen
*/
public interface PersonService {

/**
* Searches persons by using the search criteria given as a parameter.
* @param searchCriteria
* @return A list of persons matching with the search criteria. If no persons is found, this method
* returns an empty list.
* @throws IllegalArgumentException if search type is not given.
*/
public List<Person> search(SearchDTO searchCriteria);
}

The actual implementation of the search() method is responsible of selecting the correct query method and passing the given search term to it. The source code of my search() method implementation is given in following:

Naturally the created search() must be tested as well. The source code of the relevant unit tests is given in following:

/**
* @author Petri Kainulainen
*/
public class RepositoryPersonServiceTest {

private static final String LAST_NAME = "Bar";

private RepositoryPersonService personService;

private PersonRepository personRepositoryMock;

@Before
public void setUp() {
personService = new RepositoryPersonService();

personRepositoryMock = mock(PersonRepository.class);
personService.setPersonRepository(personRepositoryMock);
}

@Test
public void searchWhenSearchTypeIsMethodName() {
SearchDTO searchCriteria = createSearchDTO(LAST_NAME, SearchType.METHOD_NAME);
List<Person> expected = new ArrayList<Person>();
when(personRepositoryMock.findByLastName(searchCriteria.getSearchTerm())).thenReturn(expected);

List<Person> actual = personService.search(searchCriteria);

verify(personRepositoryMock, times(1)).findByLastName(searchCriteria.getSearchTerm());
verifyNoMoreInteractions(personRepositoryMock);

assertEquals(expected, actual);
}

@Test
public void searchWhenSearchTypeIsNamedQuery() {
SearchDTO searchCriteria = createSearchDTO(LAST_NAME, SearchType.NAMED_QUERY);
List<Person> expected = new ArrayList<Person>();
when(personRepositoryMock.findByName(searchCriteria.getSearchTerm())).thenReturn(expected);

List<Person> actual = personService.search(searchCriteria);

verify(personRepositoryMock, times(1)).findByName(searchCriteria.getSearchTerm());
verifyNoMoreInteractions(personRepositoryMock);

assertEquals(expected, actual);
}

@Test
public void searchWhenSearchTypeIsQueryAnnotation() {
SearchDTO searchCriteria = createSearchDTO(LAST_NAME, SearchType.QUERY_ANNOTATION);
List<Person> expected = new ArrayList<Person>();
when(personRepositoryMock.find(searchCriteria.getSearchTerm())).thenReturn(expected);

List<Person> actual = personService.search(searchCriteria);

verify(personRepositoryMock, times(1)).find(searchCriteria.getSearchTerm());
verifyNoMoreInteractions(personRepositoryMock);

assertEquals(expected, actual);
}

@Test(expected = IllegalArgumentException.class)
public void searchWhenSearchTypeIsNull() {
SearchDTO searchCriteria = createSearchDTO(LAST_NAME, null);

personService.search(searchCriteria);

verifyZeroInteractions(personRepositoryMock);
}

private SearchDTO createSearchDTO(String searchTerm, SearchType searchType) {
SearchDTO searchCriteria = new SearchDTO();
searchCriteria.setSearchTerm(searchTerm);
searchCriteria.setSearchType(searchType);
return searchCriteria;
}
}

What is Next?

I have now described to you how you can use query methods for creating custom queries with Spring Data JPA. If you are interested of seeing my example application in action, you can get it from Github. The next part of my Spring Data JPA tutorial will describe how you can create JPA criteria queries with Spring Data JPA.

Spring Data JPA Tutorial Part Two: CRUD

Petri Kainulainen — Tue, 24 Jan 2012 19:48:06 +0000

The first part of my Spring Data JPA tutorial described, how you configure Spring Data JPA. This blog entry goes a bit deeper and describes how you can use Spring Data JPA for creating a simple CRUD application. The requirements of the application are following:

The person must have a first name and last name. Both of these properties are mandatory.
It must be possible to list persons.
It must be possible to add new persons.
It must be possible to edit the information of existing persons.
It must be possible to delete persons.

I have now described the requirements of the created application. Now it is time to get to work and start implementing it.

Required Steps

The implementation of CRUD application can be divided to following steps:

Implementing the Person model object
Creating a repository for the Person object
Using the created repository

Each of these steps is explained with more details in following.

Implementing the Model Object

The implementation of the Person class is pretty simple. However, there are few issues which I would like to point out:

A builder is used to to create new instances of Person class. This might seem like over engineering but I like this approach for two reasons: First, it makes code easier to read than using the telescopic constructor pattern. Second, it ensures that you cannot create an object which in an inconsistent state during its construction (This is something that the common JavaBeans pattern cannot guarantee).
The only way to change the information stored in a Person object is to call the update() method. I am fan of putting as much logic to the model objects as possible. This approach does not clutter the service layer with domain logic and and ensures that you do not end up with an anemic domain model.

The source code of my Person class is given in following:

/**
* An entity class which contains the information of a single person.
* @author Petri Kainulainen
*/
@Entity
@Table(name = "persons")
public class Person {

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

@Column(name = "creation_time", nullable = false)
private Date creationTime;

@Column(name = "first_name", nullable = false)
private String firstName;

@Column(name = "last_name", nullable = false)
private String lastName;

@Column(name = "modification_time", nullable = false)
private Date modificationTime;

@Version
private long version = 0;

public Long getId() {
return id;
}

/**
* Gets a builder which is used to create Person objects.
* @param firstName The first name of the created user.
* @param lastName The last name of the created user.
* @return A new Builder instance.
*/
public static Builder getBuilder(String firstName, String lastName) {
return new Builder(firstName, lastName);
}

public Date getCreationTime() {
return creationTime;
}

public String getFirstName() {
return firstName;
}

public String getLastName() {
return lastName;
}

/**
* Gets the full name of the person.
* @return The full name of the person.
*/
@Transient
public String getName() {
StringBuilder name = new StringBuilder();

name.append(firstName);
name.append(" ");
name.append(lastName);

return name.toString();
}

public Date getModificationTime() {
return modificationTime;
}

public long getVersion() {
return version;
}

public void update(String firstName, String lastName) {
this.firstName = firstName;
this.lastName = lastName;
}

@PreUpdate
public void preUpdate() {
modificationTime = new Date();
}

@PrePersist
public void prePersist() {
Date now = new Date();
creationTime = now;
modificationTime = now;
}

@Override
public String toString() {
return ToStringBuilder.reflectionToString(this);
}

/**
* A Builder class used to create new Person objects.
*/
public static class Builder {
Person built;

/**
* Creates a new Builder instance.
* @param firstName The first name of the created Person object.
* @param lastName The last name of the created Person object.
*/
Builder(String firstName, String lastName) {
built = new Person();
built.firstName = firstName;
built.lastName = lastName;
}

/**
* Builds the new Person object.
* @return The created Person object.
*/
public Person build() {
return built;
}
}

/**
* This setter method should only be used by unit tests.
* @param id
*/
protected void setId(Long id) {
this.id = id;
}
}

Creating the Repository

Implementing a repository which provides CRUD operations for the Person model object is pretty straightforward. All you have to do is to create an interface which extends the JpaRepository interface. The JpaRepository interface is a JPA specific extension to the Repository interface and it gives you the access to following methods which are used to implement the CRUD application:

delete(T entity) which deletes the entity given as a parameter.
findAll() which returns a list of entities.
findOne(ID id) which returns the entity using the id given a parameter as a search criteria.
save(T entity) which saves the entity given as a parameter.

The source code of my PersonRepository interface is given in following:

Using the Created Repository

You have now created both the model object and the repository which is needed to communicate with the database. The next step is to implement a service class which acts as an intermediary between the controllers and the implemented repository. The structure of the service layer is described next.

The PersonDTO is a simple DTO object which is used as a form object in my example application. Its source code is given in following:

/**
* A DTO object which is used as a form object
* in create person and edit person forms.
* @author Petri Kainulainen
*/
public class PersonDTO {

private Long id;

@NotEmpty
private String firstName;

@NotEmpty
private String lastName;

public PersonDTO() {

}

public Long getId() {
return id;
}

public void setId(Long id) {
this.id = id;
}

public String getFirstName() {
return firstName;
}

public void setFirstName(String firstName) {
this.firstName = firstName;
}

public String getLastName() {
return lastName;
}

public void setLastName(String lastName) {
this.lastName = lastName;
}

@Override
public String toString() {
return ToStringBuilder.reflectionToString(this);
}
}

The PersonService interface specifies the methods which are provided by the actual implementation. Its source code is given in following:

/**
* Declares methods used to obtain and modify person information.
* @author Petri Kainulainen
*/
public interface PersonService {

/**
* Creates a new person.
* @param created The information of the created person.
* @return The created person.
*/
public Person create(PersonDTO created);

/**
* Deletes a person.
* @param personId The id of the deleted person.
* @return The deleted person.
* @throws PersonNotFoundException if no person is found with the given id.
*/
public Person delete(Long personId) throws PersonNotFoundException;

/**
* Finds all persons.
* @return A list of persons.
*/
public List<Person> findAll();

/**
* Finds person by id.
* @param id The id of the wanted person.
* @return The found person. If no person is found, this method returns null.
*/
public Person findById(Long id);

/**
* Updates the information of a person.
* @param updated The information of the updated person.
* @return The updated person.
* @throws PersonNotFoundException if no person is found with given id.
*/
public Person update(PersonDTO updated) throws PersonNotFoundException;
}

The source code of the RepositoryPersonService class which implements the PersonService interface is given in following:

/**
* 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
@Override
public Person create(PersonDTO created) {
LOGGER.debug("Creating a new person with information: " + created);

Person person = Person.getBuilder(created.getFirstName(), created.getLastName()).build();

return personRepository.save(person);
}

@Transactional(rollbackFor = PersonNotFoundException.class)
@Override
public Person delete(Long personId) throws PersonNotFoundException {
LOGGER.debug("Deleting person with id: " + personId);

Person deleted = personRepository.findOne(personId);

if (deleted == null) {
LOGGER.debug("No person found with id: " + personId);
throw new PersonNotFoundException();
}

personRepository.delete(deleted);
return deleted;
}

@Transactional(readOnly = true)
@Override
public List<Person> findAll() {
LOGGER.debug("Finding all persons");
return personRepository.findAll();
}

@Transactional(readOnly = true)
@Override
public Person findById(Long id) {
LOGGER.debug("Finding person by id: " + id);
return personRepository.findOne(id);
}

@Transactional(rollbackFor = PersonNotFoundException.class)
@Override
public Person update(PersonDTO updated) throws PersonNotFoundException {
LOGGER.debug("Updating person with information: " + updated);

Person person = personRepository.findOne(updated.getId());

if (person == null) {
LOGGER.debug("No person found with id: " + updated.getId());
throw new PersonNotFoundException();
}

person.update(updated.getFirstName(), updated.getLastName());

return person;
}

/**
* This setter method should be used only by unit tests.
* @param personRepository
*/
protected void setPersonRepository(PersonRepository personRepository) {
this.personRepository = personRepository;
}
}

The last part of this step was to write unit tests for the RepositoryPersonService class. The source code of these unit tests is given in following:

public class RepositoryPersonServiceTest {

private static final Long PERSON_ID = Long.valueOf(5);
private static final String FIRST_NAME = "Foo";
private static final String FIRST_NAME_UPDATED = "FooUpdated";
private static final String LAST_NAME = "Bar";
private static final String LAST_NAME_UPDATED = "BarUpdated";

private RepositoryPersonService personService;

private PersonRepository personRepositoryMock;

@Before
public void setUp() {
personService = new RepositoryPersonService();

personRepositoryMock = mock(PersonRepository.class);
personService.setPersonRepository(personRepositoryMock);
}

@Test
public void create() {
PersonDTO created = PersonTestUtil.createDTO(null, FIRST_NAME, LAST_NAME);
Person persisted = PersonTestUtil.createModelObject(PERSON_ID, FIRST_NAME, LAST_NAME);

when(personRepositoryMock.save(any(Person.class))).thenReturn(persisted);

Person returned = personService.create(created);

ArgumentCaptor<Person> personArgument = ArgumentCaptor.forClass(Person.class);
verify(personRepositoryMock, times(1)).save(personArgument.capture());
verifyNoMoreInteractions(personRepositoryMock);

assertPerson(created, personArgument.getValue());
assertEquals(persisted, returned);
}

@Test
public void delete() throws PersonNotFoundException {
Person deleted = PersonTestUtil.createModelObject(PERSON_ID, FIRST_NAME, LAST_NAME);
when(personRepositoryMock.findOne(PERSON_ID)).thenReturn(deleted);

Person returned = personService.delete(PERSON_ID);

verify(personRepositoryMock, times(1)).findOne(PERSON_ID);
verify(personRepositoryMock, times(1)).delete(deleted);
verifyNoMoreInteractions(personRepositoryMock);

assertEquals(deleted, returned);
}

@Test(expected = PersonNotFoundException.class)
public void deleteWhenPersonIsNotFound() throws PersonNotFoundException {
when(personRepositoryMock.findOne(PERSON_ID)).thenReturn(null);

personService.delete(PERSON_ID);

verify(personRepositoryMock, times(1)).findOne(PERSON_ID);
verifyNoMoreInteractions(personRepositoryMock);
}

@Test
public void findAll() {
List<Person> persons = new ArrayList<Person>();
when(personRepositoryMock.findAll()).thenReturn(persons);

List<Person> returned = personService.findAll();

verify(personRepositoryMock, times(1)).findAll();
verifyNoMoreInteractions(personRepositoryMock);

assertEquals(persons, returned);
}

@Test
public void findById() {
Person person = PersonTestUtil.createModelObject(PERSON_ID, FIRST_NAME, LAST_NAME);
when(personRepositoryMock.findOne(PERSON_ID)).thenReturn(person);

Person returned = personService.findById(PERSON_ID);

verify(personRepositoryMock, times(1)).findOne(PERSON_ID);
verifyNoMoreInteractions(personRepositoryMock);

assertEquals(person, returned);
}

@Test
public void update() throws PersonNotFoundException {
PersonDTO updated = PersonTestUtil.createDTO(PERSON_ID, FIRST_NAME_UPDATED, LAST_NAME_UPDATED);
Person person = PersonTestUtil.createModelObject(PERSON_ID, FIRST_NAME, LAST_NAME);

when(personRepositoryMock.findOne(updated.getId())).thenReturn(person);

Person returned = personService.update(updated);

verify(personRepositoryMock, times(1)).findOne(updated.getId());
verifyNoMoreInteractions(personRepositoryMock);

assertPerson(updated, returned);
}

@Test(expected = PersonNotFoundException.class)
public void updateWhenPersonIsNotFound() throws PersonNotFoundException {
PersonDTO updated = PersonTestUtil.createDTO(PERSON_ID, FIRST_NAME_UPDATED, LAST_NAME_UPDATED);

when(personRepositoryMock.findOne(updated.getId())).thenReturn(null);

personService.update(updated);

verify(personRepositoryMock, times(1)).findOne(updated.getId());
verifyNoMoreInteractions(personRepositoryMock);
}

private void assertPerson(PersonDTO expected, Person actual) {
assertEquals(expected.getId(), actual.getId());
assertEquals(expected.getFirstName(), actual.getFirstName());
assertEquals(expected.getLastName(), expected.getLastName());
}
}

What is Next?

I have now demonstrated to you how you can implement a simple CRUD application with Spring Data JPA. If you are interested of seeing my fully functional example in action, you can get it from Github. The third part of my Spring Data JPA tutorial describes how you can create custom queries with query methods.

Spring Data JPA Tutorial Part One: Configuration

Petri Kainulainen — Sat, 21 Jan 2012 10:19:05 +0000

Spring Data JPA is a project which aims both to simplify the creation of JPA based repositories and to reduce the amount of code needed to communicate with a database. I have been using it for a while at my work and in my personal hobby projects and it has indeed make things a lot more simpler and cleaner. Now it is time to share my knowledge with you.

This is the first part of my Spring Data JPA tutorial and it will describe to you, how you can configure Spring Data JPA when you are using Hibernate as your JPA provider. Before we will get started, I want to make one thing straight: This tutorial is not an introductory level tutorial to Hibernate, JPA or Spring. You must have some experience about these technologies if you want to understand the concepts described in my Spring Data JPA tutorial.

The dependencies of this tutorial are following:

BoneCP 0.7.1.RELEASE (You can use other data source implementations as well)
Hibernate 4.0.1.Final
Spring Framework 3.1.0.RELEASE
Spring Data JPA 1.0.2
Servlet API 3.0

Also, since I am using Maven as a build tool, you must install it if you want to run my example application.

Getting Started

It is time to get started. You can configure the Spring Data JPA by following these steps:

You have to obtain the needed dependencies.
You must configure the needed beans in your Spring application context configuration. The beans needed by the Spring Data JPA are: data source, transaction manager and entity manager factory.
You have to configure the Spring Data JPA.

These steps are explained with more details in following:

Obtaining the Needed Depedencies

First, you need to obtain the needed dependencies. You can do this by configuring the needed dependencies in your pom.xml file. The pom.xml of my example looks following:

xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
>4.0.0>
>net.petrikainulainen.spring>
>data-jpa-tutorial-part-one>
>war>
>0.1>
>Spring Data JPA Tutorial Part One>
>Spring Data JPA Tutorial Part One>
>
>
>Apache License 2.0>
>http://www.apache.org/licenses/LICENSE-2.0>
>
>
>http://www.petrikainulainen.net>
>
>
>repository.jboss.org-public>
>JBoss repository>
>https://repository.jboss.org/nexus/content/groups/public>
>
>
>
>4.0.1.Final>
>5.1.18>
>1.6.1>
>3.1.0.RELEASE>
>UTF-8>
>
>

>
>org.springframework>
>spring-beans>
>${spring.version}>
>
>
>org.springframework>
>spring-core>
>${spring.version}>
>
>
>org.springframework>
>spring-context-support>
>${spring.version}>
>
>
>org.springframework>
>spring-context>
>${spring.version}>
>
>
>org.springframework>
>spring-jdbc>
>${spring.version}>
>
>
>org.springframework>
>spring-orm>
>${spring.version}>
>
>
>org.springframework>
>spring-tx>
>${spring.version}>
>

>
>org.springframework>
>spring-web>
>${spring.version}>
>
>
>org.springframework>
>spring-webmvc>
>${spring.version}>
>
>
>cglib>
>cglib>
>2.2.2>
>

>
>org.springframework.data>
>spring-data-jpa>
>1.0.2.RELEASE>
>

>
>org.hibernate>
>hibernate-core>
>${hibernate.version}>
>
>
>org.hibernate>
>hibernate-entitymanager>
>${hibernate.version}>
>

>
>com.h2database>
>h2>
>1.3.160>
>

>
>com.jolbox>
>bonecp>
>0.7.1.RELEASE>
>

>
>javax.servlet>
>javax.servlet-api>
>3.0.1>
>provided>
>
>
>javax.servlet>
>jstl>
>1.2>
>

>
>org.slf4j>
>slf4j-api>
>${slf4j.version}>
>
>
>org.slf4j>
>slf4j-log4j12>
>${slf4j.version}>
>
>
>log4j>
>log4j>
>1.2.16>
>

>
>junit>
>junit>
>4.9>
>test>
>
>
>
>data-jpa-tutorial-part-one>
>
>
>org.apache.maven.plugins>
>maven-compiler-plugin>
>2.3.2>
>
>1.6>
>1.6>
>
>
>
>org.apache.maven.plugins>
>maven-war-plugin>
>2.1.1>
>
>false>
>
>
>
>org.mortbay.jetty>
>jetty-maven-plugin>
>8.1.0.RC2>
>
>0>
>
>src/main/resources/webdefault.xml>
>
>
>
>
>org.apache.maven.plugins>
>maven-site-plugin>
>3.0>
>
>

>
>org.codehaus.mojo>
>cobertura-maven-plugin>
>2.5.1>
>
>
>
>
>
>
>

Configuring the Spring Application Context

Second, you must configure the Spring application context. As you might remember, you need to configure the data source, transaction manager and entity manager factory beans. If you are using Spring 3.1 and Servlet 3.0, you can do this by implementing a Java configuration class and loading that configuration class in your web application initializer. The content of my application context configuration class is given in following:

/**
* An application context Java configuration class. The usage of Java configuration
* requires Spring Framework 3.0 or higher with following exceptions:
*

@EnableWebMvc annotation requires Spring Framework 3.1

* @author Petri Kainulainen
*/
@Configuration
@ComponentScan(basePackages = {"net.petrikainulainen.spring.datajpa.controller"})
@EnableWebMvc
@ImportResource("classpath:applicationContext.xml")
@PropertySource("classpath:application.properties")
public class ApplicationContext {

private static final String VIEW_RESOLVER_PREFIX = "/WEB-INF/jsp/";
private static final String VIEW_RESOLVER_SUFFIX = ".jsp";

private static final String PROPERTY_NAME_DATABASE_DRIVER = "db.driver";
private static final String PROPERTY_NAME_DATABASE_PASSWORD = "db.password";
private static final String PROPERTY_NAME_DATABASE_URL = "db.url";
private static final String PROPERTY_NAME_DATABASE_USERNAME = "db.username";

private static final String PROPERTY_NAME_HIBERNATE_DIALECT = "hibernate.dialect";
private static final String PROPERTY_NAME_HIBERNATE_FORMAT_SQL = "hibernate.format_sql";
private static final String PROPERTY_NAME_HIBERNATE_NAMING_STRATEGY = "hibernate.ejb.naming_strategy";
private static final String PROPERTY_NAME_HIBERNATE_SHOW_SQL = "hibernate.show_sql";
private static final String PROPERTY_NAME_ENTITYMANAGER_PACKAGES_TO_SCAN = "entitymanager.packages.to.scan";

private static final String PROPERTY_NAME_MESSAGESOURCE_BASENAME = "message.source.basename";
private static final String PROPERTY_NAME_MESSAGESOURCE_USE_CODE_AS_DEFAULT_MESSAGE = "message.source.use.code.as.default.message";

@Resource
private Environment environment;

@Bean
public DataSource dataSource() {
BoneCPDataSource dataSource = new BoneCPDataSource();

dataSource.setDriverClass(environment.getRequiredProperty(PROPERTY_NAME_DATABASE_DRIVER));
dataSource.setJdbcUrl(environment.getRequiredProperty(PROPERTY_NAME_DATABASE_URL));
dataSource.setUsername(environment.getRequiredProperty(PROPERTY_NAME_DATABASE_USERNAME));
dataSource.setPassword(environment.getRequiredProperty(PROPERTY_NAME_DATABASE_PASSWORD));

return dataSource;
}

@Bean
public JpaTransactionManager transactionManager() throws ClassNotFoundException {
JpaTransactionManager transactionManager = new JpaTransactionManager();

transactionManager.setEntityManagerFactory(entityManagerFactoryBean().getObject());

return transactionManager;
}

@Bean
public LocalContainerEntityManagerFactoryBean entityManagerFactoryBean() throws ClassNotFoundException {
LocalContainerEntityManagerFactoryBean entityManagerFactoryBean = new LocalContainerEntityManagerFactoryBean();

entityManagerFactoryBean.setDataSource(dataSource());
entityManagerFactoryBean.setPackagesToScan(environment.getRequiredProperty(PROPERTY_NAME_ENTITYMANAGER_PACKAGES_TO_SCAN));
entityManagerFactoryBean.setPersistenceProviderClass(HibernatePersistence.class);

Properties jpaProterties = new Properties();
jpaProterties.put(PROPERTY_NAME_HIBERNATE_DIALECT, environment.getRequiredProperty(PROPERTY_NAME_HIBERNATE_DIALECT));
jpaProterties.put(PROPERTY_NAME_HIBERNATE_FORMAT_SQL, environment.getRequiredProperty(PROPERTY_NAME_HIBERNATE_FORMAT_SQL));
jpaProterties.put(PROPERTY_NAME_HIBERNATE_NAMING_STRATEGY, environment.getRequiredProperty(PROPERTY_NAME_HIBERNATE_NAMING_STRATEGY));
jpaProterties.put(PROPERTY_NAME_HIBERNATE_SHOW_SQL, environment.getRequiredProperty(PROPERTY_NAME_HIBERNATE_SHOW_SQL));

entityManagerFactoryBean.setJpaProperties(jpaProterties);

return entityManagerFactoryBean;
}

@Bean
public MessageSource messageSource() {
ResourceBundleMessageSource messageSource = new ResourceBundleMessageSource();

messageSource.setBasename(environment.getRequiredProperty(PROPERTY_NAME_MESSAGESOURCE_BASENAME));
messageSource.setUseCodeAsDefaultMessage(Boolean.parseBoolean(environment.getRequiredProperty(PROPERTY_NAME_MESSAGESOURCE_USE_CODE_AS_DEFAULT_MESSAGE)));

return messageSource;
}

@Bean
public ViewResolver viewResolver() {
InternalResourceViewResolver viewResolver = new InternalResourceViewResolver();

viewResolver.setViewClass(JstlView.class);
viewResolver.setPrefix(VIEW_RESOLVER_PREFIX);
viewResolver.setSuffix(VIEW_RESOLVER_SUFFIX);

return viewResolver;
}
}

My web application initializer looks like this:

/**
* Web application Java configuration class. The usage of web application
* initializer requires Spring Framework 3.1 and Servlet 3.0.
* @author Petri Kainulainen
*/
public class DataJPAExampleInitializer implements WebApplicationInitializer {

private static final String DISPATCHER_SERVLET_NAME = "dispatcher";
private static final String DISPATCHER_SERVLET_MAPPING = "/";

@Override
public void onStartup(ServletContext servletContext) throws ServletException {
AnnotationConfigWebApplicationContext rootContext = new AnnotationConfigWebApplicationContext();
rootContext.register(ApplicationContext.class);

ServletRegistration.Dynamic dispatcher = servletContext.addServlet(DISPATCHER_SERVLET_NAME, new DispatcherServlet(rootContext));
dispatcher.setLoadOnStartup(1);
dispatcher.addMapping(DISPATCHER_SERVLET_MAPPING);

servletContext.addListener(new ContextLoaderListener(rootContext));
}
}

You might have noticed that I used the @PropertySource annotation to specify the location of a properties file which contains the values of used configuration parameters. The content of my application.properties file is following:

# The default database is H2 memory database but I have also
# added configuration needed to use either MySQL and PostgreSQL.

#Database Configuration
db.driver=org.h2.Driver
#db.driver=com.mysql.jdbc.Driver
#db.driver=org.postgresql.Driver
db.url=jdbc:h2:mem:datajpa
#db.url=jdbc:mysql://localhost:3306/datajpa
#db.url=jdbc:postgresql://localhost/datajpa
db.username=sa
db.password=

#Hibernate Configuration
hibernate.dialect=org.hibernate.dialect.H2Dialect
#hibernate.dialect=org.hibernate.dialect.MySQL5InnoDBDialect
#hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect
hibernate.format_sql=true
hibernate.ejb.naming_strategy=org.hibernate.cfg.ImprovedNamingStrategy
hibernate.show_sql=true

#MessageSource
message.source.basename=i18n/messages
message.source.use.code.as.default.message=true

#EntityManager
#Declares the base package of the entity classes
entitymanager.packages.to.scan=net.petrikainulainen.spring.datajpa.model

Configuring Spring Data JPA

Third, you must configure the Spring Data JPA. If you were paying attention, you might have noticed that I used the @ImportResource annotation in my application context configuration class to import additional configuration from a XML configuration file. At the moment Spring Data JPA does not support Java configuration. Thus, the only way to configure it is to use a XML configuration file. My applicationContext.xml file looks following:

version="1.0" encoding="UTF-8"?>
xmlns="http://www.springframework.org/schema/beans"
xmlns:jpa="http://www.springframework.org/schema/data/jpa"
xmlns:mvc="http://www.springframework.org/schema/mvc"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-3.1.xsd
http://www.springframework.org/schema/data/jpa
http://www.springframework.org/schema/data/jpa/spring-jpa-1.0.xsd
http://www.springframework.org/schema/mvc
http://www.springframework.org/schema/mvc/spring-mvc-3.1.xsd">

mapping="/static/**" location="/static/"/>

base-package="net.petrikainulainen.spring.datajpa.repository"/>
>

You Are Done

That is it. I have now demonstrated to you how you can configure the Spring Data JPA. I also have created an example application to demonstrate that this configuration is actually working. You can test the configuration yourself by getting my example application from Github and running the example web application by using the Maven Jetty plugin (Note: Remember to create the model and repository packages first. Since it is not possible to add empty directories to the Git staging area, the Github repository does not have them either).

The second part of my Spring Data JPA tutorial describes how you can create a simple CRUD web application by using Spring Data JPA. Stay tuned.

Petri Kainulainen » Programming

Spring Data JPA Tutorial Part Nine: Conclusions

Table of Contents

Promises Kept

Making It Work for You

Creating Queries

JPA Criteria API Versus Querydsl

Readability

Testability

Conclusions

There is Still More to Learn

Reference Documentation

JPA Criteria API 2.0

Querydsl

Spring Data JPA Tutorial Part Eight: Adding Functionality to a Repository

Adding Functionality to a Spring Data Repository

Implementing The Example Application

Creating an interface for the custom functionality.

Implementing the Declared Interface

Creating the Spring Data JPA repository

Using the Custom Functionality

What is Next?

Spring Data JPA Tutorial Part Seven: Pagination

Pagination with Spring Data JPA

Adding Pagination to Person Search Results

What is Next?

Spring Data JPA Tutorial Part Six: Sorting

Sorting with Method Name

Sorting with JPQL

Sorting with Sort Class

Query Generation by Method Name

JpaRepository

JPA Criteria API

Example

Sorting with Querydsl

What is Next?

Spring Data JPA Tutorial Part Five: Querydsl

Required Steps

Configuring the Maven Integration of Querydsl

Generating the Querydsl Query Type

Implementing the Predicate Builder Class

Extending the Repository to Support Querydsl Predicates

Using the Created Repository

What is Next?

Installing PostgreSQL 9.1 to Windows 7 from the Binary Zip Distribution

Preparing the PostgreSQL 9.1 Installation

Configuring the PostgreSQL 9.1 Installation

Congratulations

Spring Data JPA Tutorial Part Four: JPA Criteria Queries

Required Steps

Building the JPA Criteria Query

Extending the Repository

Using the Specification Builder and the Repository

What is Next?

Spring Data JPA Tutorial Part Three: Custom Queries with Query Methods

Required Steps

Query Creation from Method Name

JPA Named Queries

@Query Annotation

Using Created Query Methods

What is Next?

Spring Data JPA Tutorial Part Two: CRUD

Required Steps

Implementing the Model Object

Creating the Repository

Using the Created Repository

What is Next?

Spring Data JPA Tutorial Part One: Configuration

Getting Started

Obtaining the Needed Depedencies

Configuring the Spring Application Context

Configuring Spring Data JPA

You Are Done