#153 - Add examples for Query by Example functionality with JPA and MongoDB.

Original pull request: #154.

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

@@ -0,0 +1,27 @@
+/*
+ * 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.mongodb.querybyexample;
+
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+/**
+ * @author Mark Paluch
+ */
+@SpringBootApplication
+public class ApplicationConfiguration {
+
+}

mongodb/query-by-example/src/main/java/example/springdata/mongodb/querybyexample/Contact.java

@@ -0,0 +1,42 @@
+/*
+ * 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.mongodb.querybyexample;
+
+import lombok.Data;
+import lombok.RequiredArgsConstructor;
+
+import org.bson.types.ObjectId;
+import org.springframework.data.annotation.Id;
+import org.springframework.data.mongodb.core.mapping.Document;
+
+/**
+ * Sample contact class.
+ *
+ * @author Mark Paluch
+ */
+@Data
+@RequiredArgsConstructor
+@Document(collection = "collectionStoringTwoTypes")
+public class Contact {
+
+	@Id //
+	private ObjectId id;
+	private final String firstname;
+	private final String lastname;
+	private final Integer age;
+
+}

mongodb/query-by-example/src/main/java/example/springdata/mongodb/querybyexample/ContactRepository.java

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

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

@@ -0,0 +1,43 @@
+/*
+ * 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.mongodb.querybyexample;
+
+import lombok.Data;
+import lombok.NoArgsConstructor;
+import lombok.RequiredArgsConstructor;
+
+import org.bson.types.ObjectId;
+import org.springframework.data.annotation.Id;
+import org.springframework.data.mongodb.core.mapping.Document;
+
+/**
+ * Sample user class.
+ *
+ * @author Mark Paluch
+ */
+@Data
+@RequiredArgsConstructor
+@Document(collection = "collectionStoringTwoTypes")
+public class User {
+
+	@Id //
+	private ObjectId id;
+	private final String firstname;
+	private final String lastname;
+	private final Integer age;
+
+}

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

@@ -0,0 +1,30 @@
+/*
+ * 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.mongodb.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> {
+
+}

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

@@ -0,0 +1,22 @@
+/*
+ * 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.
+ */
+
+/**
+ * Sample showing Query-by-Example related features of Spring Data MongoDB.
+ *
+ * @author Mark Paluch
+ */
+package example.springdata.mongodb.querybyexample;

mongodb/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>

mongodb/query-by-example/src/test/java/example/springdata/mongodb/querybyexample/ContactRepositoryIntegrationTests.java

@@ -0,0 +1,114 @@
+/*
+ * 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.mongodb.querybyexample;
+
+import static org.hamcrest.CoreMatchers.*;
+import static org.hamcrest.Matchers.containsInAnyOrder;
+import static org.junit.Assert.*;
+
+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.StringMatcher;
+import org.springframework.data.mongodb.core.MongoOperations;
+import org.springframework.data.mongodb.core.query.Query;
+import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
+
+/**
+ * Integration test showing the usage of MongoDB Query-by-Example support through Spring Data repositories for a case where two domain types are stored in one collection.
+ *
+ * @author Mark Paluch
+ * @soundtrack Paul van Dyk - VONYC Sessions Episode 496 with guest Armin van Buuren
+ */
+@RunWith(SpringJUnit4ClassRunner.class)
+@SpringApplicationConfiguration(classes = ApplicationConfiguration.class)
+public class ContactRepositoryIntegrationTests {
+
+	@Autowired UserRepository userRepository;
+	@Autowired ContactRepository contactRepository;
+	@Autowired MongoOperations mongoOperations;
+
+	User skyler, walter, flynn;
+	Contact marie, hank;
+
+	@Before
+	public void setUp() {
+
+		userRepository.deleteAll();
+
+		this.skyler = userRepository.save(new User("Skyler", "White", 45));
+		this.walter = userRepository.save(new User("Walter", "White", 50));
+		this.flynn = userRepository.save(new User("Walter Jr. (Flynn)", "White", 17));
+		this.marie = contactRepository.save(new Contact("Marie", "Schrader", 38));
+		this.hank = contactRepository.save(new Contact("Hank", "Schrader", 43));
+	}
+
+	/**
+	 * @see DATAMONGO-1245
+	 */
+	@Test
+	public void countUsersByUntypedExample() {
+
+		Example<User> example = Example.of(new User(null, null, null));
+
+		// the count is 5 because untyped examples do not restrict the type
+		assertThat(userRepository.count(example), is(5L));
+		assertThat(mongoOperations.count(new Query(), "collectionStoringTwoTypes"), is(5L));
+	}
+
+	/**
+	 * @see DATAMONGO-1245
+	 */
+	@Test
+	public void countByTypedExample() {
+
+		Example<User> example = Example.of(new User(null, null, null), ExampleSpec.typed(User.class));
+
+		assertThat(userRepository.count(example), is(3L));
+	}
+
+	/**
+	 * @see DATAMONGO-1245
+	 */
+	@Test
+	public void findAllUsersBySimpleExample() {
+
+		Example<User> example = Example.of(new User(".*", null, null), //
+				ExampleSpec.typed(User.class).withStringMatcher(StringMatcher.REGEX));
+
+		assertThat(userRepository.findAll(example), containsInAnyOrder(skyler, walter, flynn));
+		assertThat(userRepository.findAll(example), not(containsInAnyOrder(hank, marie)));
+	}
+
+	/**
+	 * @see DATAMONGO-1245
+	 */
+	@Test
+	public void findAllContactsBySimpleExample() {
+
+		Example<Contact> example = Example.of(new Contact(".*", null, null), //
+				ExampleSpec.typed(Contact.class).withStringMatcher(StringMatcher.REGEX));
+
+		assertThat(contactRepository.findAll(example), containsInAnyOrder(hank, marie));
+		assertThat(contactRepository.findAll(example), not(containsInAnyOrder(skyler, walter, flynn)));
+	}
+
+}

mongodb/query-by-example/src/test/java/example/springdata/mongodb/querybyexample/MongoOperationsIntegrationTests.java

@@ -0,0 +1,142 @@
+/*
+ * 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.mongodb.querybyexample;
+
+import static org.hamcrest.CoreMatchers.*;
+import static org.junit.Assert.*;
+import static org.springframework.data.domain.ExampleSpec.GenericPropertyMatchers.*;
+import static org.springframework.data.domain.ExampleSpec.GenericPropertyMatchers.startsWith;
+
+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.TypedExampleSpec;
+import org.springframework.data.mongodb.core.MongoOperations;
+import org.springframework.data.mongodb.core.query.Query;
+import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
+
+/**
+ * Integration test showing the usage of MongoDB Query-by-Example support through Spring Data repositories.
+ *
+ * @author Mark Paluch
+ */
+@RunWith(SpringJUnit4ClassRunner.class)
+@SpringApplicationConfiguration(classes = ApplicationConfiguration.class)
+public class MongoOperationsIntegrationTests {
+
+	@Autowired MongoOperations operations;
+
+	User skyler, walter, flynn, marie, hank;
+
+	@Before
+	public void setUp() {
+
+		operations.remove(new Query(), User.class);
+
+		this.skyler = new User("Skyler", "White", 45);
+		this.walter = new User("Walter", "White", 50);
+		this.flynn = new User("Walter Jr. (Flynn)", "White", 17);
+		this.marie = new User("Marie", "Schrader", 38);
+		this.hank = new User("Hank", "Schrader", 43);
+
+		operations.save(this.skyler);
+		operations.save(this.walter);
+		operations.save(this.flynn);
+		operations.save(this.marie);
+		operations.save(this.hank);
+	}
+
+	/**
+	 * @see DATAMONGO-1245
+	 */
+	@Test
+	public void ignoreNullProperties() {
+
+		assertThat(operations.findByExample(new User(null, null, 17)), hasItems(flynn));
+	}
+
+	/**
+	 * @see DATAMONGO-1245
+	 */
+	@Test
+	public void substringMatching() {
+
+		TypedExampleSpec<User> exampleSpec = ExampleSpec.typed(User.class).//
+				withStringMatcherEnding();
+
+		assertThat(operations.findByExample(Example.of(new User("er", null, null), exampleSpec)), hasItems(skyler, walter));
+	}
+
+	/**
+	 * @see DATAMONGO-1245
+	 */
+	@Test
+	public void regexMatching() {
+
+		TypedExampleSpec<User> exampleSpec = ExampleSpec.typed(User.class).//
+				withMatcher("firstname", matcher -> matcher.regex());
+
+		assertThat(operations.findByExample(Example.of(new User("(Skyl|Walt)er", null, null), exampleSpec)),
+				hasItems(skyler, walter));
+	}
+
+	/**
+	 * @see DATAMONGO-1245
+	 */
+	@Test
+	public void matchStartingStringsIgnoreCase() {
+
+		TypedExampleSpec<User> exampleSpec = ExampleSpec.typed(User.class). //
+				withIgnorePaths("age").//
+				withMatcher("firstname", startsWith()).//
+				withMatcher("lastname", ignoreCase());
+
+		assertThat(operations.findByExample(Example.of(new User("Walter", "WHITE", null), exampleSpec)),
+				hasItems(flynn, walter));
+	}
+
+	/**
+	 * @see DATAMONGO-1245
+	 */
+	@Test
+	public void configuringMatchersUsingLambdas() {
+
+		TypedExampleSpec<User> exampleSpec = ExampleSpec.typed(User.class).withIgnorePaths("age"). //
+				withMatcher("firstname", matcher -> matcher.startsWith()). //
+				withMatcher("lastname", matcher -> matcher.ignoreCase());
+
+		assertThat(operations.findByExample(Example.of(new User("Walter", "WHITE", null), exampleSpec)),
+				hasItems(flynn, walter));
+	}
+
+	/**
+	 * @see DATAMONGO-1245
+	 */
+	@Test
+	public void valueTransformer() {
+
+		TypedExampleSpec<User> exampleSpec = ExampleSpec.typed(User.class). //
+				withMatcher("age", matcher -> matcher.transform(value -> Integer.valueOf(50)));
+
+		assertThat(operations.findByExample(Example.of(new User(null, "White", 99), exampleSpec)), hasItems(walter));
+	}
+
+}

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

@@ -0,0 +1,145 @@
+/*
+ * 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.mongodb.querybyexample;
+
+import static org.hamcrest.CoreMatchers.*;
+import static org.junit.Assert.*;
+import static org.springframework.data.domain.ExampleSpec.GenericPropertyMatchers.ignoreCase;
+import static org.springframework.data.domain.ExampleSpec.GenericPropertyMatchers.startsWith;
+
+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.test.context.junit4.SpringJUnit4ClassRunner;
+
+/**
+ * Integration test showing the usage of MongoDB Query-by-Example support through Spring Data repositories.
+ *
+ * @author Mark Paluch
+ */
+@RunWith(SpringJUnit4ClassRunner.class)
+@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 DATAMONGO-1245
+	 */
+	@Test
+	public void countBySimpleExample() {
+
+		Example<User> example = Example.of(new User(null, "White", null));
+
+		assertThat(repository.count(example), is(3L));
+	}
+
+	/**
+	 * @see DATAMONGO-1245
+	 */
+	@Test
+	public void ignorePropertiesAndMatchByAge() {
+
+		ExampleSpec exampleSpec = ExampleSpec.untyped(). //
+				withIgnorePaths("firstname", "lastname");
+
+		assertThat(repository.findOne(Example.of(flynn, exampleSpec)), is(flynn));
+	}
+
+	/**
+	 * @see DATAMONGO-1245
+	 */
+	@Test
+	public void substringMatching() {
+
+		ExampleSpec exampleSpec = ExampleSpec.untyped().//
+				withStringMatcherEnding();
+
+		assertThat(repository.findAll(Example.of(new User("er", null, null), exampleSpec)), hasItems(skyler, walter));
+	}
+
+	/**
+	 * @see DATAMONGO-1245
+	 */
+	@Test
+	public void regexMatching() {
+
+		ExampleSpec exampleSpec = ExampleSpec.untyped().//
+				withMatcher("firstname", matcher -> matcher.regex());
+
+		assertThat(repository.findAll(Example.of(new User("(Skyl|Walt)er", null, null), exampleSpec)),
+				hasItems(skyler, walter));
+	}
+
+	/**
+	 * @see DATAMONGO-1245
+	 */
+	@Test
+	public void matchStartingStringsIgnoreCase() {
+
+		ExampleSpec exampleSpec = ExampleSpec.untyped(). //
+				withIgnorePaths("age").//
+				withMatcher("firstname", startsWith()).//
+				withMatcher("lastname", ignoreCase());
+
+		assertThat(repository.findAll(Example.of(new User("Walter", "WHITE", null), exampleSpec)), hasItems(flynn, walter));
+	}
+
+	/**
+	 * @see DATAMONGO-1245
+	 */
+	@Test
+	public void configuringMatchersUsingLambdas() {
+
+		ExampleSpec exampleSpec = ExampleSpec.untyped().withIgnorePaths("age"). //
+				withMatcher("firstname", matcher -> matcher.startsWith()). //
+				withMatcher("lastname", matcher -> matcher.ignoreCase());
+
+		assertThat(repository.findAll(Example.of(new User("Walter", "WHITE", null), exampleSpec)), hasItems(flynn, walter));
+	}
+
+	/**
+	 * @see DATAMONGO-1245
+	 */
+	@Test
+	public void valueTransformer() {
+
+		ExampleSpec exampleSpec = ExampleSpec.untyped(). //
+				withMatcher("age", matcher -> matcher.transform(value -> Integer.valueOf(50)));
+
+		assertThat(repository.findAll(Example.of(new User(null, "White", 99), exampleSpec)), hasItems(walter));
+	}
+
+}