The interface we just saw had a simple query method declared. The method declaration was inspected by the infrastructure and parsed, and a store-specific query was derived eventually. However, as the queries become more complex, the method names would just become awkwardly long. For more complex queries, the keywords supported by the method parser wouldn’t even suffice. Thus, the individual store modules ship with an @Query annotation, demonstrated in Example 2-8, that takes a query string in the store-specific query language and potentially allows further tweaks regarding the query execution.

public interface CustomerRepository extends Repository<Customer, Long> {
  
  @Query("select c from Customer c where c.emailAddress = ?1")
  Customer findByEmailAddress(EmailAddress email);
}

Here we use JPA as an example and manually define the query that would have been derived anyway.

The queries can even be externalized into a properties file—$store-named-queries.properties, located in META-INF—where $store is a placeholder for jpa, mongo, neo4j, etc. The key has to follow the convention of $domainType.$methodName. Thus, to back our existing method with a externalized named query, the key would have to be Customer.findByEmailAddress. The @Query annotation is not needed if named queries are used.

The query derivation mechanism built into the Spring Data repository infrastructure, shown in Example 2-9, is useful to build constraining queries over entities of the repository. We will strip the prefixes findBy, readBy, and getBy from the method and start parsing the rest of it. At a very basic level, you can define conditions on entity properties and concatenate them with And and Or.

public interface CustomerRepository extends Repository<Customer, Long> {

  List<Customer> findByEmailAndLastname(EmailAddress email, String lastname);
}

The actual result of parsing that method will depend on the data store we use. There are also some general things to notice. The expressions are usually property traversals combined with operators that can be concatenated. As you can see in Example 2-9, you can combine property expressions with And and Or. Beyond that, you also get support for various operators like Between, LessThan, GreaterThan, and Like for the property expressions. As the operators supported can vary from data store to data store, be sure to look at each store’s corresponding chapter.

List<Customer> findByAddressZipCode(ZipCode zipCode);

List<Customer> findByAddress_ZipCode(ZipCode zipCode);

If the number of results returned from a query grows significantly, it might make sense to access the data in chunks. To achieve that, Spring Data provides a pagination API that can be used with the repositories. The definition for what chunk of data needs to be read is hidden behind the Pageable interface alongside its implementation PageRequest. The data returned from accessing it page by page is held in a Page, which not only contains the data itself but also metainformation about whether it is the first or last page, how many pages there are in total, etc. To calculate this metadata, we will have to trigger a second query as well as the initial one.

We can use the pagination functionality with the repository by simply adding a Pageable as a method parameter. Unlike the others, this will not be bound to the query, but rather used to restrict the result set to be returned. One option is to have a return type of Page, which will restrict the results, but require another query to calculate the metainformation (e.g., the total number of elements available). Our other option is to use List, which will avoid the additional query but won’t provide the metadata. If you don’t need pagination functionality, but plain sorting only, add a Sort parameter to the method signature (see Example 2-10).

Page<Customer> findByLastname(String lastname, Pageable pageable);

List<Customer> findByLastname(String lastname, Sort sort);

List<Customer> findByLastname(String lastname, Pageable pageable);

The first method allows you to pass a Pageable instance to the query method to dynamically add paging to your statically defined query. Sorting options can either be handed into the method by the Sort parameter explicitly, or embedded in the PageRequest value object, as you can see in Example 2-11.

Pageable pageable = new PageRequest(2, 10, Direction.ASC, "lastname", "firstname");
Page<Customer> result = findByLastname("Matthews", pageable);

Sort sort = new Sort(Direction.DESC, "Matthews");
List<Customer> result = findByLastname("Matthews", sort);

As we’ve just seen, it’s very easy to pull in chunks of predefined functionality by extending the appropriate Spring Data repository interface. The decision to implement this level of granularity was actually driven by the trade-off between the number of interfaces (and thus complexity) we would expose in the event that we had separator interfaces for all find methods, all save methods, and so on, versus the ease of use for developers.

However, there might be scenarios in which you’d like to expose only the reading methods (the R in CRUD) or simply prevent the delete methods from being exposed in your repository interfaces. Spring Data now allows you to tailor a custom base repository with the following steps:

To illustrate this, let’s assume we’d like to expose only the findAll(…) method taking a Pageable as well as the save methods. The base repository interface would look like Example 2-15.

@NoRepositoryBean
public interface BaseRepository<T, ID extends Serializable> extends Repository<T, ID> {

  Iterable<T> findAll(Pageable sort);

  <S extends T> S save(S entity);

  <S extends T> S save(Iterable<S> entities);
}

Note that we additionally annotated the interface with @NoRepositoryBean to make sure the Spring Data repository infrastructure doesn’t actually try to create a bean instance for it. Letting your CustomerRepository extend this interface will now expose exactly the API you defined.

It’s perfectly fine to come up with a variety of base interfaces (e.g., a ReadOnlyRepository or a SaveOnlyRepository) or even a hierarchy of them depending on the needs of your project. We usually recommend starting with locally defined CRUD methods directly in the concrete repository for an entity and then moving either to the Spring Data–provided base repository interfaces or tailor-made ones if necessary. That way, you keep the number of artifacts naturally growing with the project’s complexity.

So far we have seen two categories of methods on a repository: CRUD methods and query methods. Both types are implemented by the Spring Data infrastructure, either by a backing implementation or the query execution engine. These two cases will probably cover a broad range of data access operations you’ll face when building applications. However, there will be scenarios that require manually implemented code. Let’s see how we can achieve that.

We start by implementing just the functionality that actually needs to be implemented manually, and follow some naming conventions with the implementation class (as shown in Example 2-16).

interface CustomerRepositoryCustom {

  Customer myCustomMethod(…);
}


class CustomerRepositoryImpl implements CustomerRepositoryCustom {

  // Potentially wire dependencies

  public Customer myCustomMethod(…) {
    // custom implementation code goes here
  }
}

Neither the interface nor the implementation class has to know anything about Spring Data. This works pretty much the way that you would manually implement code with Spring. The most interesting piece of this code snippet in terms of Spring Data is that the name of the implementation class follows the naming convention to suffix the core repository interface’s (CustomerRepository in our case) name with Impl. Also note that we kept both the interface as well as the implementation class as package private to prevent them being accessed from outside the package.

The final step is to change the declaration of our original repository interface to extend the just-introduced one, as shown in Example 2-17.

public interface CustomerRepository extends CrudRepository<Customer, Long>, 
                                            CustomerRepositoryCustom { … }

Now we have essentially pulled the API exposed in CustomerRepositoryCustom into our CustomerRepository, which makes it the central access point of the data access API for Customers. Thus, client code can now call CustomerRepository.myCustomMethod(…). But how does the implementation class actually get discovered and brought into the proxy to be executed eventually? The bootstrap process for a repository essentially looks as follows:

This mechanism allows you to easily implement custom code for a dedicated repository. The suffix used for implementation lookup can be customized on the XML namespace element or an attribute of the repository enabling annotation (see the individual store chapters for more details on that). The reference documentation also contains some material on how to implement custom behavior to be applied to multiple repositories.

Finally, with the JPA support enabled, IDEA offers repository finder method completion derived from property names and the available keyword, as shown in Figure 2-5.

Figure 2-5. Finder method completion in IDEA editor