DATAJPA-218 - Add documentation for Query by Example.

Author: mp911de

src/main/asciidoc/index.adoc

@@ -1,13 +1,13 @@
 = Spring Data JPA - Reference Documentation
-Oliver Gierke; Thomas Darimont; Christoph Strobl
+Oliver Gierke; Thomas Darimont; Christoph Strobl; Mark Paluch
 :revnumber: {version}
 :revdate: {localdate}
 :toc:
 :toc-placement!:
 :spring-data-commons-docs: ../../../../spring-data-commons/src/main/asciidoc
 :spring-framework-docs: http://docs.spring.io/spring-framework/docs/current/spring-framework-reference/html
 
-(C) 2008-2015 The original authors.
+(C) 2008-2016 The original authors.
 
 NOTE: Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.
 
@@ -24,6 +24,7 @@ include::{spring-data-commons-docs}/repositories.adoc[]
 
 :leveloffset: +1
 include::jpa.adoc[]
+include::query-by-example.adoc[]
 :leveloffset: -1
 
 [[appendix]]

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

@@ -0,0 +1,146 @@
+[[query.by.example]]
+= 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.
+
+.Query by Example using a Repository
+====
+[source, java]
+----
+public interface JpaRepository<Person, String> {
+
+  List<Person> findAllByExample(Example<Person> example);
+
+  List<Person> findAllByExample(Example<Person> example, Sort sort);
+
+  Page<Person> findAllByExample(Example<Person> example, Pageable pageable);
+
+  // … more functionality omitted.
+}
+----
+====
+
+[[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();
+----
+====
+
+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.
+
+[cols="1,2", options="header"]
+.`StringMatcher` options
+|===
+| Matching
+| Logical result
+
+| `DEFAULT` (case-sensitive)
+| `firstname = ?0`
+
+| `DEFAULT` (case-insensitive)
+| `LOWER(firstname) = LOWER(?0)`
+
+| `EXACT`  (case-sensitive)
+| `firstname = ?0`
+
+| `EXACT` (case-insensitive)
+| `LOWER(firstname) = LOWER(?0)`
+
+| `STARTING`  (case-sensitive)
+| `firstname like ?0 + '%'`
+
+| `STARTING` (case-insensitive)
+| `LOWER(firstname) like LOWER(?0) + '%'`
+
+| `ENDING`  (case-sensitive)
+| `firstname like '%' + ?0`
+
+| `ENDING` (case-insensitive)
+| `LOWER(firstname) like '%' + LOWER(?0)`
+
+| `CONTAINING`  (case-sensitive)
+| `firstname like '%' + ?0 + '%'`
+
+| `CONTAINING` (case-insensitive)
+| `LOWER(firstname) like '%' + LOWER(?0) + '%'`
+
+|===