DATAMONGO-1245 - Documentation for Query-by-Example.

Author: mp911de

src/main/asciidoc/index.adoc

@@ -27,6 +27,7 @@ include::{spring-data-commons-docs}/repositories.adoc[]
 include::reference/introduction.adoc[]
 include::reference/mongodb.adoc[]
 include::reference/mongo-repositories.adoc[]
+include::{spring-data-commons-docs}/query-by-example.adoc[]
 include::reference/query-by-example.adoc[]
 include::{spring-data-commons-docs}/auditing.adoc[]
 include::reference/mongo-auditing.adoc[]

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

@@ -1,126 +1,47 @@
-[[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 domain object object or a subtype of it) and a specification how to match properties. You can use Query by Example with the `MongoTemplate` and 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 domain objects 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]
-----
-public class Person {
-
-  @Id
-  private String id;
-  private String firstname;
-  private String lastname;
-  private Address address;
-
-  // … getters and setters omitted
-}
-----
-====
-
-This is a simple domain object. 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 domain object
-<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 domain object.
+In Spring Data MongoDB you can use Query by Example with the `MongoTemplate` and with Repositories.
 
 .Query by Example using MongoTemplate
 ====
 [source,xml]
 ----
-@Autowired
-MongoTemplate template;
+public class PersonService {
+  @Autowired MongoTemplate template;
 
-public List<Person> findPeople(Person sampleObject) {
-  return template.findByExample(Example.exampleOf(person));
+  public List<Person> findPeople(Person probe) {
+    return template.findByExample(Example.of(probe));
+  }
 }
 ----
 ====
 
-`MongoTemplate.findByExample` accepts either the sample object or an `Example` object to create and execute a query.
+`MongoTemplate.findByExample` accepts either the probe or an `Example` object to create and execute a query.
 
 
 .Query by Example using a Repository
 ====
 [source, java]
 ----
-public interface MongoRepository<Person, String> {
+public interface PersonRepository extends MongoRepository<Person, String> {
 
-  <S extends Person> List<Person> findAllByExample(Example<S> example);
+}
 
-  <S extends Person> List<Person> findAllByExample(Example<S> example, Sort sort);
+public class PersonService {
 
-  <S extends Person> Page<Person> findAllByExample(Example<S> 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
-
-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();
-----
-====
+NOTE: When including `null` values in the `ExampleSpec` Spring Data Mongo uses embedded document matching instead of dot notation property matching. This forces exact document matching for all property values and the property order in the embedded document.
 
-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.
+Spring Data MongoDB provides support for the following matching options:
 
 [cols="1,2", options="header"]
 .`StringMatcher` options