You may create an interface that
extends Repository directly, but because it specifies no methods, you will probably never do this. A more useful approach is to extend
org.springframework.data.repository.CrudRepository<T, ID>, which specifies numerous methods for basic CRUD operations. This interface uses a few conventions:
-
count() returns a long representing the total number of unfiltered entities extending
T.
-
delete(T) and
delete(ID) delete the single, specified entity, whereas
delete(Iterable<? extends T>) deletes multiple entities and
deleteAll() deletes every entity of that type.
-
exists(ID) returns a boolean indicating whether the entity of this type with the given surrogate key exists.
-
findAll() returns all entities of type
T, whereas
findAll(Iterable<ID>) returns the entities of type
T with the given surrogate keys. Both return
Iterable<T>.
-
findOne(ID) retrieves a single entity of type
T given its surrogate key.
-
save(S) saves the given entity (insert or update) of type
S where
S extends T, and returns
S, the saved entity.
-
save(Iterable<S>) saves all the entities (again,
S extends T) and returns the saved entities as a new
Iterable<S>.
All Spring Data projects already know how to implement all these methods for a given type. You’ll notice, however, that this repository still doesn’t specify methods that support paging and sorting.
This is so that these methods don’t clutter any repositories that you don’t want to support paging and sorting. If you want a repository to provide paging and sorting methods, its interface can extend
org.springframework.data.repository.PagingAndSortingRepository<T, ID extends Serializable>:
-
findAll(Sort) returns all
T entities as an
Iterable<T> sorted with the provided
Sort instructions.
-
findAll(Pageable) returns a single
org.springframework.data.domain.Page<T> of entities sorted and bounded with the provided
Pageable instructions.
An
org.springframework.data.domain.Sort object encapsulates information about the properties that should be used to sort a result set and in what direction they should be sorted.
An
org.springframework.data.domain.Pageable encapsulates a Sort as well as the number of entities per page and which page to return (both ints). In a web application, you don’t usually have to worry about creating Pageable objects on your own. Spring Data provides two
org.springframework.web.method.support.HandlerMethodArgumentResolver implementations that can turn HTTP request parameters into
Pageable and
Sort objects, respectively:
org.springframework.data.web.PageableHandlerMethodArgumentResolver and
org.springframework.data.web.SortHandlerMethodArgumentResolver.
All these predefined methods are helpful, and the standardized
Sort and
Pageable objects definitely come in handy, but you still have no way to find specific entities or lists of entities using anything other than surrogate keys, at least, not without creating your own method implementations. This is where Spring Data’s query methods come in to play.
Creating Query Methods for Finding Entities
Query methods are specially defined methods that tell Spring Data how to find entities. The name of a query method starts with find...By, get...By, or read...By and is followed by the names of properties that should be matched on. The method parameters provide the values that should match the properties specified in the method name (in the same order the properties are listed in the method name if the values are of the same type). The method return type tells Spring Data whether to expect a single result (
T) or multiple results (
Iterable<T>,
List<T>,
Collection<T>,
Page<T>, and so on). So, for example, in a
BookRepository you might need to locate a book by its
ISBN,
author, or
publisher:
public interface BookRepository extends PagingAndSortingRepository<Book, Long>
{
Book findByIsbn(String isbn);
List<Book> findByAuthor(String author);
List<Book> findByPublisher(String publisher);
}
The algorithm that analyzes these methods knows that
findByIsbn should match the
Book’s
isbn property to the method parameter and that the result should be unique. Likewise, it knows that
findByAuthor and
findByPublisher should match multiple records using the
author and
publisher Book properties, respectively. Notice that the property names referenced in the repository method names match the JPA property names of the
Book entity, this is the convention that you must follow. In most cases, this is also the JavaBean property names. Of course, an
author can write many books and a
publisher most certainly publishes many, so you probably need your query methods to support pagination.
public interface BookRepository extends PagingAndSortingRepository<Book, Long>
{
Book findByIsbn(String isbn);
Page<Book> findByAuthor(String author, Pageable instructions);
Page<Book> findByPublisher(String publisher, Pageable instructions);
}
You can put multiple properties in your query method name and separate those properties with logical operators as well:
List<Person> findByFirstNameAndLastName(String firstName, String lastName);
List<Person> findByFirstNameOrLastName (String firstName, String lastName);
Many databases ignore case when matching string-based fields (either by default or as an optional configuration), but you can explicitly indicate that case should be ignored using IgnoreCase:
Page<Person> findByFirstNameOrLastNameIgnoreCase(String firstName, String lastName, Pageable instructions);
In the preceding example, only the last name ignores case. You can also ignore case on the first name using the method name
findByFirstNameIgnoreCaseOrLastNameIgnoreCase, but that is very verbose. Instead, you can tell Spring Data to ignore the case for all String properties using
findByFirstNameOrLastNameAllIgnoreCase.
Sometimes properties are not simple types. For example, a
Person might have an
address property of type
Address. Spring Data can also match against this property if the parameter type is
Address, but often you don’t want to match on the whole
address. You may want to return a list of people in a certain postal code, for example. This is easily accomplished using Spring Data property expressions.
List<Person> findByAddressPostalCode(PostalCode code);
Assuming
Person has an
address property and that property’s type has a
postalCode property of type
PostalCode, Spring Data can find the people in the database with the given postal code. However, property expressions can create ambiguity in the matching algorithm. Spring Data greedily matches the property name before looking for a property expression, not unlike a regular expression might greedily match an “or more” control character. The algorithm could match on a different property name than you intended, and then fail to find a property within that property’s type matching the property expression. For this reason, it’s best to always separate property expressions using an underscore:
Page<Person> findByAddress_PostalCode(PostalCode code, Pageable instructions);
This removes the ambiguity so that Spring Data matches on the correct property.
You undoubtedly remember that method names begin with find...By, get...By, or read...By. These are introducing clauses, and By is a delimiter separating the introducing clause and the criteria to match on. To a large extent, you can place whatever you want to between find, get, or read and By. For example, to be more “plain language,” you could name a method
findBookByIsbn or
findPeopleByFirstNameAndLastName.
Book and
People are ignored in this case. However, if the word Distinct (matching that case) is in the introducing clause (such as
findDistinctBooksByAuthor), this triggers the special behavior of enabling the distinct flag on the underlying query. This may or may not apply to the storage medium in use, but for JPA or JdbcTemplate repositories, it’s the equivalent of using the DISTINCT keyword in the JPQL or SQL query.
In addition to the Or and And keywords that separate multiple criteria, the criteria in a query method name can contain many other keywords to refine the way the criteria match:
-
Is and
Equals are implied in the absence of other keywords, but you may explicitly use them. For example,
findByIsbn is equivalent to
findByIsbnIs and
findByIsbnEquals.
-
Not and
IsNot negate any other keyword except for Or and And. Is and Equals are still implied in the absence of other keywords, so
findByIsbnIsNot is equivalent to
findByIsbnIsNotEqual.
-
After and
IsAfter indicate that the property is a date and/or time that should come after the given value, whereas
Before and
IsBefore indicate that the property should come before the given value. Example:
findByDateFoundedIsAfter(Date date).
-
Containing,
IsContaining, and
Contains indicate that the property’s value may start and end with anything but should contain the given value. This is similar to
StartingWith,
IsStartingWith, and
StartsWith, which indicate that the property should start with the specified value. Likewise,
EndingWith,
IsEndingWith, and
EndsWith indicate that the property should end with the specified value. Example:
findByTitleContains(String value) is equivalent to the SQL criteria
WHERE title = '%value%'.
-
Like is similar to Contains, StartsWith, and EndsWith, except that value you provide should already contain the appropriate wildcards (instead of Spring Data adding them for you). This gives you the flexibility to specify more advanced patterns.
NotLike simply negates Like. Example:
findByTitleLike(String value) could be called with value
"%Catcher%Rye%" and would match
“The Catcher in the Rye” and
“Catcher Brings Home Rye Bread.”
-
Between and
IsBetween indicate that the property should be between the two specified values. This means that you must provide two parameters for this property criterion. You can use Between on any type that may be compared mathematically in this manner, such as numeric and date types. Example:
findByDateFoundedBetween(Date start, Date end).
-
Exists indicates that something should exist. Its meaning may vary wildly between storage mediums. It is roughly equivalent to the EXISTS keyword in JPQL and SQL.
-
True and
IsTrue indicate that the named property should be true, whereas
False and
IsFalse indicate that the named property should be false. These keywords do not require method parameters because the value is implied by the keywords themselves. Example:
findByApprovedIsFalse().
-
GreaterThan and
IsGreaterThan indicate that the property is greater than the parameter value. You can include the parameter value in the bounds with
GreaterThanEqual or
IsGreaterThanEqual. The inverse of these keywords are
LessThan,
IsLessThan,
LessThanEqual, and
IsLessThanEqual.
-
In indicates that the property value must be equal to at least one of the values specified. The parameter matching this criterion should be an
Iterable of the same type of the property. Example:
findByAuthorIn(Iterable<String> authors).
-
Null and
IsNull indicate that the value should be null. These keywords also do not require method parameters because the value is implied.
-
Near,
IsNear,
Within, and
IsWithin are keywords useful for certain NoSQL database types but have no useful meaning in JPA.
-
Regex,
MatchesRegex, and
Matches indicate that the property value should match the String regular expression (do not use Pattern) specified in the corresponding method parameter.
