Usually you will have your repository interface extend Repository, CrudRepository or PagingAndSortingRepository. If you don't like extending Spring Data interfaces at all you can also annotate your repository interface with @RepositoryDefinition. Extending CrudRepository will expose a complete set of methods to manipulate your entities. If you would rather be selective about the methods being exposed, simply copy the ones you want to expose from CrudRepository into your domain repository.

interface MyBaseRepository<T, ID extends Serializable> extends Repository<T, ID> {
  T findOne(ID id);
  T save(T entity);
}

interface UserRepository extends MyBaseRepository<User, Long> {

  User findByEmailAddress(EmailAddress emailAddress);
}

In the first step we define a common base interface for all our domain repositories and expose findOne(…) as well as save(…).These methods will be routed into the base repository implementation of the store of your choice because they are matching the method signatures in CrudRepository. So our UserRepository will now be able to save users, find single ones by id as well as triggering a query to find Users by their email address.

The next thing we have to discuss is the definition of query methods. There are two main ways that the repository proxy is able to come up with the store specific query from the method name. The first option is to derive the query from the method name directly, the second is using some kind of additionally created query. What detailed options are available pretty much depends on the actual store, however, there's got to be some algorithm that decides what actual query is created.

There are three strategies available for the repository infrastructure to resolve the query. The strategy to be used can be configured at the namespace through the query-lookup-strategy attribute. However, It might be the case that some of the strategies are not supported for specific datastores. Here are your options:

The query builder mechanism built into Spring Data repository infrastructure is useful to build constraining queries over entities of the repository. We will strip the prefixes find…By, read…By, as well as get…By from the method and start parsing the rest of it. The introducing clause can contain further expressions such as a Distinct to set a distinct flag on the query to be created. However, the first By acts as delimiter to indicate the start of the actual criterias. At a very basic level you can define conditions on entity properties and concatenate them with AND and OR.

public interface PersonRepository extends Repository<User, Long> {

  List<Person> findByEmailAddressAndLastname(EmailAddress emailAddress, String lastname);

  // Enables the distinct flag for the query
  List<Person> findDistinctPeopleByLastnameOrFirstname(String lastname, String firstname);
  List<Person> findPeopleDistinctByLastnameOrFirstname(String lastname, String firstname);

  // Enabling ignoring case for an individual property
  List<Person> findByLastnameIgnoreCase(String lastname);
  // Enabling ignoring case for all suitable properties
  List<Person> findByLastnameAndFirstnameAllIgnoreCase(String lastname, String firstname);

  // Enabling static ORDER BY for a query
  List<Person> findByLastnameOrderByFirstnameAsc(String lastname);
  List<Person> findByLastnameOrderByFirstnameDesc(String lastname);
}

The actual result of parsing that method will of course depend on the persistence store we create the query for, however, there are some general things to notice. The expressions are usually property traversals combined with operators that can be concatenated. As you can see in the example you can combine property expressions with And and Or. Beyond that you also get support for various operators like Between, LessThan, GreaterThan, Like for the property expressions. As the operators supported can vary from datastore to datastore please consult the according part of the reference documentation.

As you can see the method parser also supports setting an ignore case flag for individual properties (e.g. findByLastnameIgnoreCase(…)) or for all properties of a type that support ignoring case (i.e. usually Strings, e.g. findByLastnameAndFirstnameAllIgnoreCase(…)). Whether ignoring cases is supported my differ from store to store, so consult the relevant sections of the store specific query method reference docs.

Static ordering can be applied by appending an OrderBy clause to the query method referencing a property and providing a sorting direction (Asc or Desc). To create a query method that supports dynamic sorting have a look at the section called “Special parameter handling”.

List<Person> findByAddressZipCode(ZipCode zipCode);

List<Person> findByAddress_ZipCode(ZipCode zipCode);

To hand parameters to your query you simply define method parameters as already seen in the examples above. Besides that we will recognizes certain specific types to apply pagination and sorting to your queries dynamically.

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

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

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

The first method allows you to pass a org.springframework.data.domain.Pageable instance to the query method to dynamically add paging to your statically defined query. Sorting options are handed via the Pageable instance too. If you only need sorting, simply add an org.springframework.data.domain.Sort parameter to your method. As you also can see, simply returning a List is possible as well. We will then not retrieve the additional metadata required to build the actual Page instance but rather simply restrict the query to lookup only the given range of entities.

	Note
	To find out how many pages you get for a query entirely we have to trigger an additional count query. This will be derived from the query you actually trigger by default.

The easiest way to do so is by using the Spring namespace that is shipped with each Spring Data module that supports the repository mechanism. Each of those includes a repositories element that allows you to simply define a base package that Spring will scan for you.

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

  <repositories base-package="com.acme.repositories" />

</beans:beans>

In this case we instruct Spring to scan com.acme.repositories and all its sub packages for interfaces extending Repository or one of its sub-interfaces. For each interface found it will register the persistence technology specific FactoryBean to create the according proxies that handle invocations of the query methods. Each of these beans will be registered under a bean name that is derived from the interface name, so an interface of UserRepository would be registered under userRepository. The base-package attribute allows the use of wildcards, so that you can have a pattern of scanned packages.

<repositories base-package="com.acme.repositories">
  <context:exclude-filter type="regex" expression=".*SomeRepository" />
</repositories>

The repository infrastructure can also be triggered using a store-specific @Enable${store}Repositories annotation on a JavaConfig class. For an introduction into Java based configuration of the Spring container please have a look at the reference documentation.^[1]

A sample configuration to enable Spring Data repositories would look something like this.

@Configuration
@EnableJpaRepositories("com.acme.repositories")
class ApplicationConfiguration {

  @Bean
  public EntityManagerFactory entityManagerFactory() {
    // …
  }
}

Note that the sample uses the JPA specific annotation which would have to be exchanged dependingon which store module you actually use. The same applies to the definition of the EntityManagerFactory bean. Please consult the sections covering the store-specific configuration.

You can also use the repository infrastructure outside of a Spring container usage. You will still need to have some of the Spring libraries on your classpath but you can generally setup repositories programmatically as well. The Spring Data modules providing repository support ship a persistence technology specific RepositoryFactory that can be used as follows:

RepositoryFactorySupport factory = … // Instantiate factory here
UserRepository repository = factory.getRepository(UserRepository.class);