DATAJPA-218 - Documentation for Query-by-Example.

Author: mp911de

src/main/asciidoc/index.adoc

@@ -24,6 +24,7 @@ include::{spring-data-commons-docs}/repositories.adoc[]
 
 :leveloffset: +1
 include::jpa.adoc[]
+include::{spring-data-commons-docs}/query-by-example.adoc[]
 include::query-by-example.adoc[]
 :leveloffset: -1
 

src/main/asciidoc/query-by-example.adoc

@@ -1,109 +1,29 @@
-[[query.by.example]]
-= Query by Example
+[[query.by.example.execution]]
+== Executing Query by Example
 
-== Introduction
-
-This chapter will give you an introduction to Query by Example and explain how to use example specifications.
-
-Query by Example (QBE) is a user-friendly querying technique with a simple interface. It allows dynamic query creation and does not require to write queries containing field names. In fact, Query by Example does not require to write queries using store-specific query languages at all.
-
-== Usage
-
-An `Example` takes a data object (usually the entity object or a subtype of it) and a specification how to match properties. You can use Query by Example with Repositories.
-
-Query by Example is suited for several use-cases but also comes with limitations:
-
-**When to use**
-
-* Querying your data store with a set of static or dynamic constraints
-* Frequent refactoring of the entities without worrying about breaking existing queries
-* Works independently from the data store API
-
-**Limitations**
-
-* Query predicates are combined using the `AND` keyword
-* No support for nested/grouped property constraints like `firstname = ?0 or (firstname = ?1 and lastname = ?2)`
-* Only supports starts/contains/ends/regex matching for strings and exact matching for other property types
-
-
-Before getting started with Query by Example you need to have your interface to the data store set up.
-
-.Sample Person object
-====
-[source,java]
-----
-@Entity
-public class Person {
-
-  @Id
-  private String id;
-  private String firstname;
-  private String lastname;
-  private Address address;
-
-  // … getters and setters omitted
-}
-----
-====
-
-This is a simple entity. You can use it to create an Example specification. By default, fields having `null` values are ignored, and strings are matched using the store specific defaults. Examples can be built by either using the `exampleOf` factory method or by using the <<query.by.example.builder,Example builder>>. Once the `Example` is constructed it becomes immutable.
-
-.Simple Example specification
-====
-[source,xml]
-----
-Person person = new Person();                         <1>
-
-person.setFirstname("Dave");                          <2>
-
-Example<Person> example = Example.exampleOf(person);  <3>
-----
-<1> Create a new instance of the entity
-<2> Set the properties to query
-<3> Create an `Example`
-====
-
-
-NOTE: Property names of the sample object must correlate with the property names of the queried entity.
+In Spring Data JPA you can use Query by Example with Repositories.
 
 .Query by Example using a Repository
 ====
 [source, java]
 ----
-public interface JpaRepository<Person, String> {
+public interface PersonRepository extends JpaRepository<Person, String> {
 
-  List<Person> findAllByExample(Example<Person> example);
+}
 
-  List<Person> findAllByExample(Example<Person> example, Sort sort);
+public class PersonService {
 
-  Page<Person> findAllByExample(Example<Person> example, Pageable pageable);
+  @Autowired PersonRepository personRepository;
 
-  // … more functionality omitted.
+  public List<Person> findPeople(Person probe) {
+    return personRepository.findAll(Example.of(probe));
+  }
 }
 ----
 ====
 
-[[query.by.example.builder]]
-== Example builder
+NOTE: Only SingularAttribute properties can be used for property matching.
 
-Examples are not limited to default settings. You can specify own defaults for string matching, null handling and property-specific settings using the example builder.
-
-.Query by Example builder
-====
-[source, java]
-----
-Example.newExampleOf(person)
-    .withStringMatcher(StringMatcher.ENDING)
-    .includeNullValues()
-    .withPropertySpecifier(
-            newPropertySpecifier("firstname").matchString(StringMatcher.CONTAINING).get())
-    .withPropertySpecifier(
-            newPropertySpecifier("lastname").matchStringsWithIgnoreCase().get())
-    .withPropertySpecifier(
-            newPropertySpecifier("address.city").matchStringStartingWith().get())
-    .get();
-----
-====
 
 Property specifier accepts property names (e.g. "firstname" and "lastname"). You can navigate by chaining properties together with dots ("address.city"). You can tune it with matching options and case sensitivity.