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 rather want to be selective about the methods being expose 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's roughly two main ways how the repository proxy is generally able to come up with the store specific query from the method name. The first option is to derive the quer 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 the decision which actual query to is made.

There's three strategies 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 might be the case that some of the strategies are not supported for the specific datastore. Here are your options:

The query builder mechanism built into Spring Data repository infrastructue is useful to build constraining queries over entities of the repository. We will strip the prefixes findBy, find, readBy, read, getBy as well as get 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 PersonRepository extends Repository<User, Long> {

  List<Person> findByEmailAddressAndLastname(EmailAddress emailAddress, 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 expression 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 will 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.

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 in 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 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 a 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.

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 packge Spring shall 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 it's sub packages for interfaces extending Repository or one of its sub-interfaces. For each interface found it will register the presistence 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 to use wildcards, so that you can have a pattern of packages parsed.

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

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

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