DATACMNS-810 - Add common documentation for Query by Example.

Author: mp911de

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

@@ -0,0 +1,147 @@
+[[query.by.example]]
+= Query by Example
+
+== Introduction
+
+This chapter will give you an introduction to Query by Example and explain how to use Examples.
+
+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 or a subtype of it) and a specification how to match properties.
+
+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. 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 `of` factory method or by using the <<query.by.example.examplespec,`ExampleSpec`>>. Once the `Example` is constructed it becomes immutable.
+
+.Simple Example
+====
+[source,xml]
+----
+Person person = new Person();                         <1>
+
+person.setFirstname("Dave");                          <2>
+
+Example<Person> example = Example.of(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.
+
+Examples can be executed ideally with Repositories. To do so, let your repository extend from `QueryByExampleExecutor`, here's an excerpt from the interface:
+
+.The `QueryByExampleExecutor`
+====
+[source, java]
+----
+public interface QueryByExampleExecutor<T> {
+
+	<S extends T> T findOne(Example<S> example);
+
+	<S extends T> Iterable<T> findAll(Example<S> example);
+
+  // … more functionality omitted.
+}
+----
+====
+
+
+[[query.by.example.examplespec]]
+== Example Spec
+
+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.
+
+
+.Example Spec with customized matching
+====
+[source,xml]
+----
+Person person = new Person();                                                 <1>
+
+person.setFirstname("Dave");                                                  <2>
+
+ExampleSpec<Person> exampleSpec = ExampleSpec.of(Person.class)                <3>
+
+                                         .withIgnorePaths("lastname")         <4>
+
+                                         .withIncludeNullValues()             <5>
+
+                                         .withStringMatcherEnding();          <6>
+
+Example example = Example.of(person, exampleSpec);                            <7>
+
+----
+<1> Create a new instance of the domain object
+<2> Set the properties to query
+<3> Create an `ExampleSpec` for the `Person` type. The ExampleSpec is already usable at this stage.
+<4> Construct a new `ExampleSpec` to ignore the property path `lastname`
+<5> Construct a new `ExampleSpec` to ignore the property path `lastname` and to include null values
+<6> Construct a new `ExampleSpec` to ignore the property path `lastname`, to include null values, and use perform suffix string matching
+<6> Create a new `Example` based on the domain object and the configured `ExampleSpec`
+====
+
+`ExampleSpec` is immutable. It creates a new `ExampleSpec` instance on each `with…(…)` invocation so intermediate objects can be safely reused. An `ExampleSpec` can be used to create ad-hoc example specs or to be reused across the application as specification for `Example`. You can use `ExampleSpec` as template to configure a default behavior for your example spec and derive from it to create a more specific `ExampleSpec` where you need to customize it.
+
+You can specify behavior for individual properties (e.g. "firstname" and "lastname", "address.city" for nested properties) You can tune it with matching options and case sensitivity.
+
+.Configuring matcher options
+====
+[source,java]
+----
+ExampleSpec<Person> example = ExampleSpec.of(Person.class)
+		.withMatcher("firstname", endsWith())
+		.withMatcher("lastname", startsWith().ignoreCase());
+}
+----
+====
+
+Another style to configure matcher options is by using Java 8 lambdas. This approach is a callback that asks the implementor to modify the matcher. It's not required to return the matcher because configuration options are held within the matcher instance.
+
+.Configuring matcher options with lambdas
+====
+[source,java]
+----
+ExampleSpec<Person> example = ExampleSpec.of(Person.class)
+		.withMatcher("firstname", matcher -> matcher.endsWith())
+		.withMatcher("firstname", matcher -> matcher.startsWith());
+}
+----
+====
+
+Matcher settings are merged at the time of creating the data-store specific query. Any options that are not explicitly configured on a property-specific matcher are used from the default settings.