DATAJPA-218 - Add support for Query By Example.

.gitignore

@@ -1,5 +1,7 @@
 target/
+.idea/
 .settings/
+*.iml
 .project
 .classpath
 .springBeans

pom.xml

@@ -5,8 +5,7 @@
 
 	<groupId>org.springframework.data</groupId>
 	<artifactId>spring-data-jpa</artifactId>
-	<version>1.10.0.BUILD-SNAPSHOT</version>
-
+	<version>1.10.0.DATAJPA-218-SNAPSHOT</version>
 	<name>Spring Data JPA</name>
 	<description>Spring Data module for JPA repositories.</description>
 	<url>http://projects.spring.io/spring-data-jpa</url>
@@ -26,7 +25,7 @@
 		<hsqldb1>1.8.0.10</hsqldb1>
 		<jpa>2.0.0</jpa>
 		<openjpa>2.4.0</openjpa>
-		<springdata.commons>1.12.0.BUILD-SNAPSHOT</springdata.commons>
+		<springdata.commons>1.12.0.DATACMNS-810-SNAPSHOT</springdata.commons>
 
 		<sonar.dynamicAnalysis>reuseReports</sonar.dynamicAnalysis>
 

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.
 

src/main/asciidoc/jpa.adoc

@@ -604,6 +604,9 @@ List<Customer> customers = customerRepository.findAll(
 As you can see, `Specifications` offers some glue-code methods to chain and combine `Specification` instances. Thus extending your data access layer is just a matter of creating new `Specification` implementations and combining them with ones already existing.
 ====
 
+include::{spring-data-commons-docs}/query-by-example.adoc[]
+include::query-by-example.adoc[]
+
 [[transactions]]
 == Transactionality
 CRUD methods on repository instances are transactional by default. For reading operations the transaction configuration `readOnly` flag is set to true, all others are configured with a plain `@Transactional` so that default transaction configuration applies. For details see JavaDoc of `CrudRepository`. If you need to tweak transaction configuration for one of the methods declared in a repository simply redeclare the method in your repository interface as follows:

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

@@ -0,0 +1,68 @@
+[[query.by.example.execution]]
+== Executing Example
+
+In Spring Data JPA you can use Query by Example with Repositories.
+
+.Query by Example using a Repository
+====
+[source, java]
+----
+public interface PersonRepository extends JpaRepository<Person, String> {
+
+}
+
+public class PersonService {
+
+  @Autowired PersonRepository personRepository;
+
+  public List<Person> findPeople(Person probe) {
+    return personRepository.findAll(Example.of(probe));
+  }
+}
+----
+====
+
+An `Example` containing an untyped `ExampleSpec` uses the Repository type. Typed `ExampleSpec` use their type for creating JPA queries.
+
+NOTE: Only SingularAttribute properties can be used for property matching.
+
+
+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) + '%'`
+
+|===

src/main/java/org/springframework/data/jpa/convert/QueryByExamplePredicateBuilder.java

@@ -0,0 +1,251 @@
+/*
+ * Copyright 2016 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.data.jpa.convert;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+
+import javax.persistence.criteria.CriteriaBuilder;
+import javax.persistence.criteria.Expression;
+import javax.persistence.criteria.From;
+import javax.persistence.criteria.Path;
+import javax.persistence.criteria.Predicate;
+import javax.persistence.criteria.Root;
+import javax.persistence.metamodel.Attribute;
+import javax.persistence.metamodel.Attribute.PersistentAttributeType;
+import javax.persistence.metamodel.ManagedType;
+import javax.persistence.metamodel.SingularAttribute;
+
+import org.springframework.dao.InvalidDataAccessApiUsageException;
+import org.springframework.data.domain.Example;
+import org.springframework.data.domain.ExampleSpec;
+import org.springframework.data.repository.core.support.ExampleSpecAccessor;
+import org.springframework.data.util.DirectFieldAccessFallbackBeanWrapper;
+import org.springframework.orm.jpa.JpaSystemException;
+import org.springframework.util.Assert;
+import org.springframework.util.ClassUtils;
+import org.springframework.util.ObjectUtils;
+import org.springframework.util.StringUtils;
+
+/**
+ * {@link QueryByExamplePredicateBuilder} creates a single {@link CriteriaBuilder#and(Predicate...)} combined
+ * {@link Predicate} for a given {@link Example}. <br />
+ * The builder includes any {@link SingularAttribute} of the {@link Example#getProbe()} applying {@link String} and
+ * {@literal null} matching strategies configured on the {@link Example}. Ignored paths are no matter of their actual
+ * value not considered. <br />
+ *
+ * @author Christoph Strobl
+ * @author Mark Paluch
+ * @since 1.10
+ */
+public class QueryByExamplePredicateBuilder {
+
+	private static final Set<PersistentAttributeType> ASSOCIATION_TYPES;
+
+	static {
+		ASSOCIATION_TYPES = new HashSet<PersistentAttributeType>(Arrays.asList(PersistentAttributeType.MANY_TO_MANY,
+				PersistentAttributeType.MANY_TO_ONE, PersistentAttributeType.ONE_TO_MANY, PersistentAttributeType.ONE_TO_ONE));
+	}
+
+	/**
+	 * Extract the {@link Predicate} representing the {@link Example}.
+	 *
+	 * @param root must not be {@literal null}.
+	 * @param cb must not be {@literal null}.
+	 * @param example must not be {@literal null}.
+	 * @return never {@literal null}.
+	 */
+	public static <T> Predicate getPredicate(Root<T> root, CriteriaBuilder cb, Example<T> example) {
+
+		Assert.notNull(root, "Root must not be null!");
+		Assert.notNull(cb, "CriteriaBuilder must not be null!");
+		Assert.notNull(example, "Example must not be null!");
+
+		List<Predicate> predicates = getPredicates("", cb, root, root.getModel(), example.getProbe(),
+				example.getProbeType(), new ExampleSpecAccessor(example.getExampleSpec()),
+				new PathNode("root", null, example.getProbe()));
+
+		if (predicates.isEmpty()) {
+			return cb.isTrue(cb.literal(true));
+		}
+
+		if (predicates.size() == 1) {
+			return predicates.iterator().next();
+		}
+
+		return cb.and(predicates.toArray(new Predicate[predicates.size()]));
+	}
+
+	@SuppressWarnings({ "rawtypes", "unchecked" })
+	static List<Predicate> getPredicates(String path, CriteriaBuilder cb, Path<?> from, ManagedType<?> type, Object value,
+			Class<?> probeType, ExampleSpecAccessor exampleAccessor, PathNode currentNode) {
+
+		List<Predicate> predicates = new ArrayList<Predicate>();
+		DirectFieldAccessFallbackBeanWrapper beanWrapper = new DirectFieldAccessFallbackBeanWrapper(value);
+
+		for (SingularAttribute attribute : type.getSingularAttributes()) {
+
+			String currentPath = !StringUtils.hasText(path) ? attribute.getName() : path + "." + attribute.getName();
+
+			if (exampleAccessor.isIgnoredPath(currentPath)) {
+				continue;
+			}
+
+			Object attributeValue = exampleAccessor.getValueTransformerForPath(currentPath)
+					.convert(beanWrapper.getPropertyValue(attribute.getName()));
+
+			if (attributeValue == null) {
+
+				if (exampleAccessor.getNullHandler().equals(ExampleSpec.NullHandler.INCLUDE)) {
+					predicates.add(cb.isNull(from.get(attribute)));
+				}
+				continue;
+			}
+
+			if (attribute.getPersistentAttributeType().equals(PersistentAttributeType.EMBEDDED)) {
+
+				predicates.addAll(getPredicates(currentPath, cb, from.get(attribute.getName()),
+						(ManagedType<?>) attribute.getType(), attributeValue, probeType, exampleAccessor, currentNode));
+				continue;
+			}
+
+			if (isAssociation(attribute)) {
+
+				if (!(from instanceof From)) {
+					throw new JpaSystemException(new IllegalArgumentException(
+							String.format("Unexpected path type for %s. Found % where From.class was expected.", currentPath, from)));
+				}
+
+				PathNode node = currentNode.add(attribute.getName(), attributeValue);
+				if (node.spansCycle()) {
+					throw new InvalidDataAccessApiUsageException(
+							String.format("Path '%s' from root %s must not span a cyclic property reference!\r\n%s", currentPath,
+									ClassUtils.getShortName(probeType), node));
+				}
+
+				predicates.addAll(getPredicates(currentPath, cb, ((From<?, ?>) from).join(attribute.getName()),
+						(ManagedType<?>) attribute.getType(), attributeValue, probeType, exampleAccessor, node));
+
+				continue;
+			}
+
+			if (attribute.getJavaType().equals(String.class)) {
+
+				Expression<String> expression = from.get(attribute);
+				if (exampleAccessor.isIgnoreCaseForPath(currentPath)) {
+					expression = cb.lower(expression);
+					attributeValue = attributeValue.toString().toLowerCase();
+				}
+
+				switch (exampleAccessor.getStringMatcherForPath(currentPath)) {
+
+					case DEFAULT:
+					case EXACT:
+						predicates.add(cb.equal(expression, attributeValue));
+						break;
+					case CONTAINING:
+						predicates.add(cb.like(expression, "%" + attributeValue + "%"));
+						break;
+					case STARTING:
+						predicates.add(cb.like(expression, attributeValue + "%"));
+						break;
+					case ENDING:
+						predicates.add(cb.like(expression, "%" + attributeValue));
+						break;
+					default:
+						throw new IllegalArgumentException(
+								"Unsupported StringMatcher " + exampleAccessor.getStringMatcherForPath(currentPath));
+				}
+			} else {
+				predicates.add(cb.equal(from.get(attribute), attributeValue));
+			}
+		}
+
+		return predicates;
+	}
+
+	private static boolean isAssociation(Attribute<?, ?> attribute) {
+		return ASSOCIATION_TYPES.contains(attribute.getPersistentAttributeType());
+	}
+
+	/**
+	 * {@link PathNode} is used to dynamically grow a directed graph structure that allows to detect cycles within its
+	 * direct predecessor nodes by comparing parent node values using {@link System#identityHashCode(Object)}.
+	 *
+	 * @author Christoph Strobl
+	 */
+	private static class PathNode {
+
+		String name;
+		PathNode parent;
+		List<PathNode> siblings = new ArrayList<PathNode>();;
+		Object value;
+
+		public PathNode(String edge, PathNode parent, Object value) {
+
+			this.name = edge;
+			this.parent = parent;
+			this.value = value;
+		}
+
+		PathNode add(String attribute, Object value) {
+
+			PathNode node = new PathNode(attribute, this, value);
+			siblings.add(node);
+			return node;
+		}
+
+		boolean spansCycle() {
+
+			if (value == null) {
+				return false;
+			}
+
+			String identityHex = ObjectUtils.getIdentityHexString(value);
+			PathNode tmp = parent;
+
+			while (tmp != null) {
+
+				if (ObjectUtils.getIdentityHexString(tmp.value).equals(identityHex)) {
+					return true;
+				}
+				tmp = tmp.parent;
+			}
+
+			return false;
+		}
+
+		@Override
+		public String toString() {
+
+			StringBuilder sb = new StringBuilder();
+			if (parent != null) {
+				sb.append(parent.toString());
+				sb.append(" -");
+				sb.append(name);
+				sb.append("-> ");
+			}
+
+			sb.append("[{ ");
+			sb.append(ObjectUtils.nullSafeToString(value));
+			sb.append(" }]");
+			return sb.toString();
+		}
+	}
+}