DATACMNS-810 - Polishing.

Renamed ExampleSpecification to ExampleMatcher and introduced a matching() factory method, dropping the dedicated override mechanism for types for now. Updated documentation accordingly.

Used Lombok for constructor creation, field defaults, toString() as well as equals(…) and hashCode() implementations.

Tweaked imports in unit tests. Renamed methods to express expected behavior.

Original pull request: #153.

Author: odrotbohm

lombok.config

@@ -0,0 +1,2 @@
+lombok.nonNull.exceptionType = IllegalArgumentException
+lombok.log.fieldName = LOG

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

@@ -12,8 +12,8 @@ Query by Example (QBE) is a user-friendly querying technique with a simple inter
 The Query by Example API consists of three parts:
 
 * Probe: That is the actual example of a domain object with populated fields.
-* `ExampleSpec`: The `ExampleSpec` carries details on how to match particular fields. It can be reused across multiple Examples. `ExampleSpec` comes in two flavors: <<query.by.example.examplespec,untyped>> and <<query.by.example.examplespec.typed,typed>>.
-* `Example`: An Example consists of the probe and the ExampleSpec. It is used to create the query. An `Example` takes a probe (usually the domain object or a subtype of it) and the `ExampleSpec`.
+* `ExampleMatcher`: The `ExampleMatcher` carries details on how to match particular fields. It can be reused across multiple Examples.
+* `Example`: An `Example` consists of the probe and the `ExampleMatcher`. It is used to create the query.
 
 Query by Example is suited for several use-cases but also comes with limitations:
 
@@ -48,14 +48,13 @@ public class Person {
 ----
 ====
 
-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 <<query.by.example.examplespec,`ExampleSpec`>>. `Example` is immutable.
+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 <<query.by.example.matcher,`ExampleMatcher`>>. `Example` is immutable.
 
 .Simple Example
 ====
 [source,java]
 ----
 Person person = new Person();                         <1>
-
 person.setFirstname("Dave");                          <2>
 
 Example<Person> example = Example.of(person);         <3>
@@ -65,19 +64,17 @@ Example<Person> example = Example.of(person);         <3>
 <3> Create the `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 `QueryByExampleExecutor` interface:
+Examples are ideally be executed with repositories. To do so, let your repository interface extend `QueryByExampleExecutor<T>`. Here's an excerpt from the `QueryByExampleExecutor` interface:
 
 .The `QueryByExampleExecutor`
 ====
 [source, java]
 ----
 public interface QueryByExampleExecutor<T> {
 
-    <S extends T> S findOne(Example<S> example);
+  <S extends T> S findOne(Example<S> example);
 
-    <S extends T> Iterable<S> findAll(Example<S> example);
+  <S extends T> Iterable<S> findAll(Example<S> example);
 
   // … more functionality omitted.
 }
@@ -86,50 +83,44 @@ public interface QueryByExampleExecutor<T> {
 
 You can read more about <<query.by.example.execution, Query by Example Execution>> below.
 
-[[query.by.example.examplespec]]
-=== Example Spec
+[[query.by.example.matcher]]
+=== Example matchers
 
-Examples are not limited to default settings. You can specify own defaults for string matching, null handling and property-specific settings using the `ExampleSpec`. `ExampleSpec` comes in two flavors: untyped and typed. By default `Example.of(Person.class)` uses an untyped `ExampleSpec`. Using untyped `ExampleSpec` will use the Repository entity information to determine the type to query and has no control over inheritance queries. Also, untyped `ExampleSpec` will use the probe type when using with a Template to determine the type to query. Read more about <<query.by.example.examplespec.typed,typed `ExampleSpec`>> below.
+Examples are not limited to default settings. You can specify own defaults for string matching, null handling and property-specific settings using the `ExampleMatcher`. `ExampleMatcher` comes in two flavors: untyped and typed. By default `Example.of(Person.class)` uses an untyped `ExampleMatcher`. Using untyped `ExampleMatcher` will use the Repository entity information to determine the type to query and has no control over inheritance queries. Also, untyped `ExampleMatcher` will use the probe type when using with a Template to determine the type to query. Read more about <<query.by.example.matcher.typed,typed `ExampleMatcher`>> below.
 
 .Untyped Example Spec with customized matching
 ====
 [source,java]
 ----
-Person person = new Person();                                          <1>
-
-person.setFirstname("Dave");                                           <2>
-
-ExampleSpec exampleSpec = ExampleSpec.untyped()                        <3>
+Person person = new Person();                          <1>
+person.setFirstname("Dave");                           <2>
 
-                                  .withIgnorePaths("lastname")         <4>
+ExampleMatcher matcher = ExampleMatcher.matching()     <3>
+  .withIgnorePaths("lastname")                         <4>
+  .withIncludeNullValues()                             <5>
+  .withStringMatcherEnding();                          <6>
 
-                                  .withIncludeNullValues()             <5>
-
-                                  .withStringMatcherEnding();          <6>
-
-Example<Person> example = Example.of(person, exampleSpec);             <7>
+Example<Person> example = Example.of(person, matcher); <7>
 
 ----
 <1> Create a new instance of the domain object.
 <2> Set properties.
-<3> Create an untyped `ExampleSpec`. The `ExampleSpec` is 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.
-<7> Create a new `Example` based on the domain object and the configured `ExampleSpec`.
+<3> Create an `ExampleMatcher` which is usable at this stage even without further configuration.
+<4> Construct a new `ExampleMatcher` to ignore the property path `lastname`.
+<5> Construct a new `ExampleMatcher` to ignore the property path `lastname` and to include null values.
+<6> Construct a new `ExampleMatcher` to ignore the property path `lastname`, to include null values, and use perform suffix string matching.
+<7> Create a new `Example` based on the domain object and the configured `ExampleMatcher`.
 ====
 
-`ExampleSpec` is immutable. Calls to `with…(…)` return a copy of `ExampleSpec` with the specific setting applied. 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 a specification for `Example`. You can use `ExampleSpec` as a template to configure a default behavior for your example spec. You also can derive from it 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 exampleSpec = ExampleSpec.untyped()
-        .withMatcher("firstname", endsWith())
-        .withMatcher("lastname", startsWith().ignoreCase());
+ExampleMatcher exampleSpec = ExampleMatcher.untyped()
+  .withMatcher("firstname", endsWith())
+  .withMatcher("lastname", startsWith().ignoreCase());
 }
 ----
 ====
@@ -140,74 +131,35 @@ Another style to configure matcher options is by using Java 8 lambdas. This appr
 ====
 [source,java]
 ----
-ExampleSpec exampleSpec = ExampleSpec.untyped()
-        .withMatcher("firstname", matcher -> matcher.endsWith())
-        .withMatcher("firstname", matcher -> matcher.startsWith());
+ExampleMatcher exampleSpec = ExampleMatcher.untyped()
+  .withMatcher("firstname", matcher -> matcher.endsWith())
+  .withMatcher("firstname", matcher -> matcher.startsWith());
 }
 ----
 ====
 
-Queries created by `Example` use a merged view of the configuration. Default matching settings can be set at `ExampleSpec` level while individual settings can be applied to particular property paths. Settings that are set on `ExampleSpec` are inherited by property path settings unless they are defined explicitly. Settings on a property patch have higher precedence than default settings.
+Queries created by `Example` use a merged view of the configuration. Default matching settings can be set at `ExampleMatcher` level while individual settings can be applied to particular property paths. Settings that are set on `ExampleMatcher` are inherited by property path settings unless they are defined explicitly. Settings on a property patch have higher precedence than default settings.
 
 [cols="1,2", options="header"]
-.Scope of `ExampleSpec` settings
+.Scope of `ExampleMatcher` settings
 |===
 | Setting
 | Scope
 
 | Null-handling
-| `ExampleSpec`
+| `ExampleMatcher`
 
 | String matching
-| `ExampleSpec` and property path
+| `ExampleMatcher` and property path
 
 | Ignoring properties
 | Property path
 
 | Case sensitivity
-| `ExampleSpec` and property path
+| `ExampleMatcher` and property path
 
 | Value transformation
 | Property path
 
 |===
 
-[[query.by.example.examplespec.typed]]
-==== Typed Example Spec
-You have now seen the usage of untyped `ExampleSpec`. The second flavor of `ExampleSpec` is typed which adds more control over the result type. When executing an `Example` containing a typed `ExampleSpec` the type of the `ExampleSpec` is used as domain type. Control over the domain type is useful in particular when querying along the inheritance hierarchy or the repository contains multiple types within one table/collection/keyspace.
-
-.Sample Person object
-====
-[source,java]
-----
-public class SpecialPerson extends Person {
-
-  // … more functionality omitted.
-}
-----
-====
-
-.Typed Example Spec with customized matching
-====
-[source,java]
-----
-QueryByExampleExecutor<Person> personRepository = … ;
-
-Person person = new Person();                                                    <1>
-
-person.setFirstname("Dave");                                                     <2>
-
-ExampleSpec<SpecialPerson> exampleSpec = ExampleSpec.typed(SpecialPerson.class); <3>
-
-Example<Person> example = Example.of(person, exampleSpec);                       <4>
-
-List<Person> result = personRepository.findAll(example);                         <5>
-
-----
-<1> Create a new instance of the domain object.
-<2> Set properties.
-<3> Create a typed `ExampleSpec` for `SpecialPerson` that extends `Person`.
-<4> Construct a new `Example` using the typed `ExampleSpec` and the `Person` probe.
-<5> Run a query to select all instances of `SpecialPerson` in the repository. Note that the result type is the base class `Person`.
-====
-

src/main/java/org/springframework/data/domain/Example.java

@@ -15,84 +15,51 @@
  */
 package org.springframework.data.domain;
 
-import org.springframework.util.Assert;
+import lombok.AccessLevel;
+import lombok.EqualsAndHashCode;
+import lombok.NonNull;
+import lombok.RequiredArgsConstructor;
+import lombok.ToString;
+
 import org.springframework.util.ClassUtils;
 
 /**
  * Support for query by example (QBE). An {@link Example} takes a {@code probe} to define the example. Matching options
- * and type safety can be tuned using {@link ExampleSpec}. {@link Example} uses {@link ExampleSpec#untyped()}
- * {@link ExampleSpec} by default.
- * <p>
- * This class is immutable.
+ * and type safety can be tuned using {@link ExampleMatcher}.
  *
  * @author Christoph Strobl
  * @author Mark Paluch
- * @param <T>
+ * @author Oliver Gierke
+ * @param <T> the type of the probe.
  * @since 1.12
  */
+@ToString
+@EqualsAndHashCode
+@RequiredArgsConstructor(access = AccessLevel.PRIVATE)
 public class Example<T> {
 
-	private final T probe;
-	private final ExampleSpec exampleSpec;
+	private final @NonNull T probe;
+	private final @NonNull ExampleMatcher matcher;
 
 	/**
 	 * Create a new {@link Example} including all non-null properties by default.
 	 *
-	 * @param probe The probe to use. Must not be {@literal null}.
-	 */
-	@SuppressWarnings("unchecked")
-	private Example(T probe) {
-
-		Assert.notNull(probe, "Probe must not be null!");
-
-		this.probe = probe;
-		this.exampleSpec = ExampleSpec.untyped();
-	}
-
-	/**
-	 * Create a new {@link Example} including all non-null properties by default.
-	 *
-	 * @param probe The probe to use. Must not be {@literal null}.
-	 * @param exampleSpec The example specification to use. Must not be {@literal null}.
-	 */
-	private Example(T probe, ExampleSpec exampleSpec) {
-
-		Assert.notNull(probe, "Probe must not be null!");
-
-		this.probe = probe;
-		this.exampleSpec = exampleSpec;
-	}
-
-	/**
-	 * Create a new {@link Example} including all non-null properties by default using an untyped {@link ExampleSpec}.
-	 *
 	 * @param probe must not be {@literal null}.
 	 * @return
 	 */
 	public static <T> Example<T> of(T probe) {
-		return new Example<T>(probe);
+		return new Example<T>(probe, ExampleMatcher.matching());
 	}
 
 	/**
-	 * Create a new {@link Example} with a configured untyped {@link ExampleSpec}.
+	 * Create a new {@link Example} using the given {@link ExampleMatcher}.
 	 *
 	 * @param probe must not be {@literal null}.
-	 * @param exampleSpec must not be {@literal null}.
+	 * @param matcher must not be {@literal null}.
 	 * @return
 	 */
-	public static <T> Example<T> of(T probe, ExampleSpec exampleSpec) {
-		return new Example<T>(probe, exampleSpec);
-	}
-
-	/**
-	 * Create a new {@link Example} with a configured {@link TypedExampleSpec}.
-	 *
-	 * @param probe must not be {@literal null}.
-	 * @param exampleSpec must not be {@literal null}.
-	 * @return
-	 */
-	public static <T, S extends T> Example<S> of(S probe, TypedExampleSpec<T> exampleSpec) {
-		return new Example<S>(probe, exampleSpec);
+	public static <T> Example<T> of(T probe, ExampleMatcher matcher) {
+		return new Example<T>(probe, matcher);
 	}
 
 	/**
@@ -105,12 +72,12 @@ public T getProbe() {
 	}
 
 	/**
-	 * Get the {@link ExampleSpec} used.
+	 * Get the {@link ExampleMatcher} used.
 	 *
 	 * @return never {@literal null}.
 	 */
-	public ExampleSpec getExampleSpec() {
-		return exampleSpec;
+	public ExampleMatcher getMatcher() {
+		return matcher;
 	}
 
 	/**
@@ -124,17 +91,4 @@ public ExampleSpec getExampleSpec() {
 	public Class<T> getProbeType() {
 		return (Class<T>) ClassUtils.getUserClass(probe.getClass());
 	}
-
-	/**
-	 * Get the actual result type for the query. The result type can be different when using {@link TypedExampleSpec}.
-	 *
-	 * @return
-	 * @see ClassUtils#getUserClass(Class)
-	 */
-	@SuppressWarnings("unchecked")
-	public <S extends T> Class<S> getResultType() {
-		return (Class<S>) (exampleSpec instanceof TypedExampleSpec<?> ? ((TypedExampleSpec<T>) exampleSpec).getType()
-				: getProbeType());
-	}
-
 }