#153 - Create example module for Query by Example with Spring Data JPA.

Author: mp911de

jpa/pom.xml

@@ -25,6 +25,7 @@
 		<module>security</module>
 		<module>multiple-datasources</module>
 		<module>eclipselink</module>
+		<module>query-by-example</module>
 	</modules>
 
 	<dependencies>

jpa/query-by-example/README.md

@@ -0,0 +1,10 @@
+# Spring Data JPA - Query-by-Example (QBE) example
+
+This project contains samples of Query-by-Example of Spring Data JPA.
+
+## Support for Query-by-Example
+
+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 JPA-QL at all.
+
+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 JPA Repositories.
+

jpa/query-by-example/pom.xml

@@ -0,0 +1,14 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+
+	<parent>
+		<groupId>org.springframework.data.examples</groupId>
+		<artifactId>spring-data-jpa-examples</artifactId>
+		<version>1.0.0.BUILD-SNAPSHOT</version>
+	</parent>
+
+	<artifactId>spring-data-jpa-query-by-example</artifactId>
+	<name>Spring Data JPA - Query-by-Example (QBE)</name>
+
+</project>

jpa/query-by-example/src/main/java/example/springdata/jpa/querybyexample/ApplicationConfiguration.java

@@ -0,0 +1,32 @@
+/*
+ * 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 example.springdata.jpa.querybyexample;
+
+import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
+import org.springframework.boot.orm.jpa.EntityScan;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.data.jpa.repository.config.EnableJpaAuditing;
+
+/**
+ * @author Mark Paluch
+ */
+@Configuration
+@EnableAutoConfiguration
+@EntityScan(basePackageClasses = { ApplicationConfiguration.class })
+@EnableJpaAuditing
+public class ApplicationConfiguration {
+
+}

jpa/query-by-example/src/main/java/example/springdata/jpa/querybyexample/User.java

@@ -0,0 +1,50 @@
+/*
+ * 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 example.springdata.jpa.querybyexample;
+
+import javax.persistence.Entity;
+import javax.persistence.GeneratedValue;
+import javax.persistence.Id;
+
+import lombok.Data;
+
+/**
+ * Sample user class.
+ *
+ * @author Mark Paluch
+ */
+@Entity
+@Data
+public class User {
+
+	@Id @GeneratedValue //
+	private Long id;
+	private String firstname;
+	private String lastname;
+	private Integer age;
+
+	public User() {
+		super();
+	}
+
+	public User(String firstname, String lastname, Integer age) {
+		super();
+		this.firstname = firstname;
+		this.lastname = lastname;
+		this.age = age;
+	}
+
+}

jpa/query-by-example/src/main/java/example/springdata/jpa/querybyexample/UserRepository.java

@@ -0,0 +1,29 @@
+/*
+ * 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 example.springdata.jpa.querybyexample;
+
+import org.springframework.data.repository.CrudRepository;
+import org.springframework.data.repository.query.QueryByExampleExecutor;
+
+/**
+ * Simple repository interface for {@link User} instances. The interface implements {@link QueryByExampleExecutor} and
+ * allows execution of methods accepting {@link org.springframework.data.domain.Example}.
+ *
+ * @author Mark Paluch
+ */
+public interface UserRepository extends CrudRepository<User, Long>, QueryByExampleExecutor<User> {
+
+}

jpa/query-by-example/src/main/java/example/springdata/jpa/querybyexample/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Sample showing Query-by-Example related features of Spring Data JPA.
+ *
+ * @author Mark Paluch
+ */
+package example.springdata.jpa.querybyexample;

jpa/query-by-example/src/main/resources/application.properties

@@ -0,0 +1 @@
+spring.datasource.separator=/;

jpa/query-by-example/src/main/resources/logback.xml

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<configuration>
+
+	<appender name="console" class="ch.qos.logback.core.ConsoleAppender">
+		<encoder>
+			<pattern>%d %5p %40.40c:%4L - %m%n</pattern>
+		</encoder>
+	</appender>
+
+	<logger name="org.springframework" level="error" />
+
+	<root level="error">
+		<appender-ref ref="console" />
+	</root>
+
+</configuration>

jpa/query-by-example/src/test/java/example/springdata/jpa/querybyexample/UserRepositoryIntegrationTests.java

@@ -0,0 +1,137 @@
+/*
+ * 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 example.springdata.jpa.querybyexample;
+
+import static org.hamcrest.CoreMatchers.*;
+import static org.junit.Assert.*;
+import static org.springframework.data.domain.ExampleSpec.GenericPropertyMatchers.*;
+
+import org.junit.Before;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.SpringApplicationConfiguration;
+import org.springframework.data.domain.Example;
+import org.springframework.data.domain.ExampleSpec;
+import org.springframework.data.domain.ExampleSpec.GenericPropertyMatchers;
+import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
+import org.springframework.transaction.annotation.Transactional;
+
+/**
+ * Integration test showing the usage of JPA Query-by-Example support through Spring Data repositories.
+ *
+ * @author Mark Paluch
+ */
+@RunWith(SpringJUnit4ClassRunner.class)
+@Transactional
+@SpringApplicationConfiguration(classes = ApplicationConfiguration.class)
+public class UserRepositoryIntegrationTests {
+
+	@Autowired UserRepository repository;
+
+	User skyler, walter, flynn, marie, hank;
+
+	@Before
+	public void setUp() {
+		repository.deleteAll();
+
+		this.skyler = repository.save(new User("Skyler", "White", 45));
+		this.walter = repository.save(new User("Walter", "White", 50));
+		this.flynn = repository.save(new User("Walter Jr. (Flynn)", "White", 17));
+		this.marie = repository.save(new User("Marie", "Schrader", 38));
+		this.hank = repository.save(new User("Hank", "Schrader", 43));
+	}
+
+	/**
+	 * @see DATAJPA-218
+	 */
+	@Test
+	public void countBySimpleExample() {
+
+		Example<User> example = Example.of(new User(null, "White", null));
+
+		assertThat(repository.count(example), is(3L));
+	}
+
+	/**
+	 * @see DATAJPA-218
+	 */
+	@Test
+	public void ignorePropertiesAndMatchByAge() {
+
+		Example<User> example = ExampleSpec.of(User.class). //
+				withIgnorePaths("firstname", "lastname").//
+				createExample(flynn);
+
+		assertThat(repository.findOne(example), is(flynn));
+	}
+
+	/**
+	 * @see DATAJPA-218
+	 */
+	@Test
+	public void substringMatching() {
+
+		Example<User> example = ExampleSpec.of(User.class).//
+				withStringMatcherEnding()//
+				.createExample(new User("er", null, null));
+
+		assertThat(repository.findAll(example), hasItems(skyler, walter));
+	}
+
+	/**
+	 * @see DATAJPA-218
+	 */
+	@Test
+	public void matchStartingStringsIgnoreCase() {
+
+		Example<User> example = ExampleSpec.of(User.class). //
+				withIgnorePaths("age").//
+				withMatcher("firstname", startsWith()).//
+				withMatcher("lastname", ignoreCase()).//
+				createExample(new User("Walter", "WHITE", null));
+
+		assertThat(repository.findAll(example), hasItems(flynn, walter));
+	}
+
+	/**
+	 * @see DATAJPA-218
+	 */
+	@Test
+	public void configuringMatchersUsingLambdas() {
+
+		Example<User> example = ExampleSpec.of(User.class).withIgnorePaths("age"). //
+				withMatcher("firstname", matcher -> matcher.startsWith()). //
+				withMatcher("lastname", matcher -> matcher.ignoreCase()). //
+				createExample(new User("Walter", "WHITE", null));
+
+		assertThat(repository.findAll(example), hasItems(flynn, walter));
+	}
+
+	/**
+	 * @see DATAJPA-218
+	 */
+	@Test
+	public void valueTransformer() {
+
+		Example<User> example = ExampleSpec.of(User.class). //
+				withMatcher("age", matcher -> matcher.transform(value -> Integer.valueOf(50))).//
+				createExample(new User(null, "White", 99));
+
+		assertThat(repository.findAll(example), hasItems(walter));
+	}
+
+}