DATAJPA-218 - Further work on Query by Example.

Add reference documentation. Adapted to API changes in Spring Data Commons.

Related tickets: DATACMNS-810.
Original pull request: #164.

Author: mp911de

.gitignore

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

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

@@ -34,7 +34,8 @@
 
 import org.springframework.dao.InvalidDataAccessApiUsageException;
 import org.springframework.data.domain.Example;
-import org.springframework.data.domain.Example.NullHandler;
+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;
@@ -48,8 +49,9 @@
  * 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 {
@@ -63,7 +65,7 @@ public class QueryByExamplePredicateBuilder {
 
 	/**
 	 * 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}.
@@ -73,13 +75,14 @@ public static <T> Predicate getPredicate(Root<T> root, CriteriaBuilder cb, Examp
 
 		Assert.notNull(root, "Root must not be null!");
 		Assert.notNull(cb, "CriteriaBuilder must not be null!");
-		Assert.notNull(example, "Root must not be null!");
+		Assert.notNull(example, "Example must not be null!");
 
-		List<Predicate> predicates = getPredicates("", cb, root, root.getModel(), example.getSampleObject(), example,
-				new PathNode("root", null, example.getSampleObject()));
+		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(false));
+			return cb.isTrue(cb.literal(true));
 		}
 
 		if (predicates.size() == 1) {
@@ -90,8 +93,8 @@ public static <T> Predicate getPredicate(Root<T> root, CriteriaBuilder cb, Examp
 	}
 
 	@SuppressWarnings({ "rawtypes", "unchecked" })
-	static List<Predicate> getPredicates(String path, CriteriaBuilder cb, Path<?> from, ManagedType<?> type,
-			Object value, Example<?> example, PathNode currentNode) {
+	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);
@@ -100,16 +103,16 @@ static List<Predicate> getPredicates(String path, CriteriaBuilder cb, Path<?> fr
 
 			String currentPath = !StringUtils.hasText(path) ? attribute.getName() : path + "." + attribute.getName();
 
-			if (example.isIgnoredPath(currentPath)) {
+			if (exampleAccessor.isIgnoredPath(currentPath)) {
 				continue;
 			}
 
-			Object attributeValue = example.getValueTransformerForPath(currentPath).convert(
-					beanWrapper.getPropertyValue(attribute.getName()));
+			Object attributeValue = exampleAccessor.getValueTransformerForPath(currentPath)
+					.convert(beanWrapper.getPropertyValue(attribute.getName()));
 
 			if (attributeValue == null) {
 
-				if (example.getNullHandler().equals(NullHandler.INCLUDE)) {
+				if (exampleAccessor.getNullHandler().equals(ExampleSpec.NullHandler.INCLUDE)) {
 					predicates.add(cb.isNull(from.get(attribute)));
 				}
 				continue;
@@ -118,39 +121,39 @@ static List<Predicate> getPredicates(String path, CriteriaBuilder cb, Path<?> fr
 			if (attribute.getPersistentAttributeType().equals(PersistentAttributeType.EMBEDDED)) {
 
 				predicates.addAll(getPredicates(currentPath, cb, from.get(attribute.getName()),
-						(ManagedType<?>) attribute.getType(), attributeValue, example, currentNode));
+						(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)));
+					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(example.getSampleType()), node));
+					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, example, node));
+						(ManagedType<?>) attribute.getType(), attributeValue, probeType, exampleAccessor, node));
 
 				continue;
 			}
 
 			if (attribute.getJavaType().equals(String.class)) {
 
 				Expression<String> expression = from.get(attribute);
-				if (example.isIgnoreCaseForPath(currentPath)) {
+				if (exampleAccessor.isIgnoreCaseForPath(currentPath)) {
 					expression = cb.lower(expression);
 					attributeValue = attributeValue.toString().toLowerCase();
 				}
 
-				switch (example.getStringMatcherForPath(currentPath)) {
+				switch (exampleAccessor.getStringMatcherForPath(currentPath)) {
 
 					case DEFAULT:
 					case EXACT:
@@ -166,8 +169,8 @@ static List<Predicate> getPredicates(String path, CriteriaBuilder cb, Path<?> fr
 						predicates.add(cb.like(expression, "%" + attributeValue));
 						break;
 					default:
-						throw new IllegalArgumentException("Unsupported StringMatcher "
-								+ example.getStringMatcherForPath(currentPath));
+						throw new IllegalArgumentException(
+								"Unsupported StringMatcher " + exampleAccessor.getStringMatcherForPath(currentPath));
 				}
 			} else {
 				predicates.add(cb.equal(from.get(attribute), attributeValue));
@@ -184,7 +187,7 @@ private static boolean isAssociation(Attribute<?, ?> attribute) {
 	/**
 	 * {@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 {

src/main/java/org/springframework/data/jpa/provider/PersistenceProvider.java

@@ -52,7 +52,7 @@
  * @author Oliver Gierke
  * @author Thomas Darimont
  */
-public enum PersistenceProvider implements QueryExtractor, ProxyIdAccessor {
+public enum PersistenceProvider implements QueryExtractor,ProxyIdAccessor {
 
 	/**
 	 * Hibernate persistence provider.
@@ -117,14 +117,13 @@ public <T> Collection<T> potentiallyConvertEmptyCollection(Collection<T> collect
 		public CloseableIterator<Object> executeQueryWithResultStream(Query jpaQuery) {
 			return new HibernateScrollableResultsIterator<Object>(jpaQuery);
 		}
-
 	},
 
 	/**
 	 * EclipseLink persistence provider.
 	 */
-	ECLIPSELINK(Collections.singleton(ECLIPSELINK_ENTITY_MANAGER_INTERFACE), Collections
-			.singleton(ECLIPSELINK_JPA_METAMODEL_TYPE)) {
+	ECLIPSELINK(Collections.singleton(ECLIPSELINK_ENTITY_MANAGER_INTERFACE),
+			Collections.singleton(ECLIPSELINK_JPA_METAMODEL_TYPE)) {
 
 		public String extractQueryString(Query query) {
 			return ((JpaQuery<?>) query).getDatabaseQuery().getJPQLString();
@@ -164,7 +163,6 @@ public <T> Collection<T> potentiallyConvertEmptyCollection(Collection<T> collect
 		public CloseableIterator<Object> executeQueryWithResultStream(Query jpaQuery) {
 			return new EclipseLinkScrollableResultsIterator<Object>(jpaQuery);
 		}
-
 	},
 
 	/**
@@ -203,7 +201,6 @@ public Object getIdentifierFrom(Object entity) {
 		public CloseableIterator<Object> executeQueryWithResultStream(Query jpaQuery) {
 			return new OpenJpaResultStreamingIterator<Object>(jpaQuery);
 		}
-
 	},
 
 	/**
@@ -246,7 +243,6 @@ public boolean shouldUseAccessorFor(Object entity) {
 		public Object getIdentifierFrom(Object entity) {
 			return null;
 		}
-
 	};
 
 	/**
@@ -388,8 +384,8 @@ public <T> Collection<T> potentiallyConvertEmptyCollection(Collection<T> collect
 	}
 
 	public CloseableIterator<Object> executeQueryWithResultStream(Query jpaQuery) {
-		throw new UnsupportedOperationException("Streaming results is not implement for this PersistenceProvider: "
-				+ name());
+		throw new UnsupportedOperationException(
+				"Streaming results is not implement for this PersistenceProvider: " + name());
 	}
 
 	/**

src/main/java/org/springframework/data/jpa/repository/JpaRepository.java

@@ -21,20 +21,21 @@
 import javax.persistence.EntityManager;
 
 import org.springframework.data.domain.Example;
-import org.springframework.data.domain.Page;
-import org.springframework.data.domain.Pageable;
 import org.springframework.data.domain.Sort;
 import org.springframework.data.repository.NoRepositoryBean;
 import org.springframework.data.repository.PagingAndSortingRepository;
+import org.springframework.data.repository.query.QueryByExampleExecutor;
 
 /**
  * JPA specific extension of {@link org.springframework.data.repository.Repository}.
- * 
+ *
  * @author Oliver Gierke
  * @author Christoph Strobl
+ * @author Mark Paluch
  */
 @NoRepositoryBean
-public interface JpaRepository<T, ID extends Serializable> extends PagingAndSortingRepository<T, ID> {
+public interface JpaRepository<T, ID extends Serializable>
+		extends PagingAndSortingRepository<T, ID>, QueryByExampleExecutor<T> {
 
 	/*
 	 * (non-Javadoc)
@@ -95,33 +96,16 @@ public interface JpaRepository<T, ID extends Serializable> extends PagingAndSort
 	 */
 	T getOne(ID id);
 
-	/**
-	 * Returns all instances of the type specified by the given {@link Example}.
-	 * 
-	 * @param example must not be {@literal null}.
-	 * @return
-	 * @since 1.10
+	/* (non-Javadoc)
+	 * @see org.springframework.data.repository.query.QueryByExampleExecutor#findAll(org.springframework.data.domain.Example)
 	 */
-	List<T> findAllByExample(Example<T> example);
+	@Override
+	<S extends T> List<S> findAll(Example<S> example);
 
-	/**
-	 * Returns all instances of the type specified by the given {@link Example}.
-	 * 
-	 * @param example must not be {@literal null}.
-	 * @param sort can be {@literal null}.
-	 * @return all entities sorted by the given options
-	 * @since 1.10
+	/* (non-Javadoc)
+	 * @see org.springframework.data.repository.query.QueryByExampleExecutor#findAll(org.springframework.data.domain.Example, org.springframework.data.domain.Sort)
 	 */
-	List<T> findAllByExample(Example<T> example, Sort sort);
+	@Override
+	<S extends T> List<S> findAll(Example<S> example, Sort sort);
 
-	/**
-	 * Returns a {@link Page} of entities meeting the paging restriction specified by the given {@link Example} limited to
-	 * criteria provided in the {@code Pageable} object.
-	 * 
-	 * @param example must not be {@literal null}.
-	 * @param pageable can be {@literal null}.
-	 * @return a {@link Page} of entities
-	 * @since 1.10
-	 */
-	Page<T> findAllByExample(Example<T> example, Pageable pageable);
 }

src/main/java/org/springframework/data/jpa/repository/query/AbstractJpaQuery.java

@@ -189,8 +189,8 @@ private Query applyEntityGraphConfiguration(Query query, JpaQueryMethod method)
 		Assert.notNull(query, "Query must not be null!");
 		Assert.notNull(method, "JpaQueryMethod must not be null!");
 
-		Map<String, Object> hints = Jpa21Utils.tryGetFetchGraphHints(em, method.getEntityGraph(), getQueryMethod()
-				.getEntityInformation().getJavaType());
+		Map<String, Object> hints = Jpa21Utils.tryGetFetchGraphHints(em, method.getEntityGraph(),
+				getQueryMethod().getEntityInformation().getJavaType());
 
 		for (Map.Entry<String, Object> hint : hints.entrySet()) {
 			query.setHint(hint.getKey(), hint.getValue());