GH-2703 - Add support for negating transformers to query-by-example.

Closes #2703.

Author: michael-simons

src/main/asciidoc/faq/index.adoc

@@ -1276,17 +1276,37 @@ Example<MovieEntity> movieExample = Example.of(new MovieEntity("The Matrix", nul
 Flux<MovieEntity> movies = this.movieRepository.findAll(movieExample);
 
 movieExample = Example.of(
-	new MovieEntity("Matrix", null),
-	ExampleMatcher
-	    .matchingAny()
+    new MovieEntity("Matrix", null),
+    ExampleMatcher
+        .matchingAny()
         .withMatcher(
-        	"title",
-        	ExampleMatcher.GenericPropertyMatcher.of(ExampleMatcher.StringMatcher.CONTAINING)
+            "title",
+            ExampleMatcher.GenericPropertyMatcher.of(ExampleMatcher.StringMatcher.CONTAINING)
         )
 );
 movies = this.movieRepository.findAll(movieExample);
 ----
 
+You can also negate individual properties. This will add an appropriate `NOT` operation, thus turning an `=` into a `<>`.
+All scalar datatypes and all string operators are supported:
+
+[source,java,indent=0,tabsize=4]
+[[find-by-example-example-with-negated-properties]]
+.findByExample with negated values
+----
+Example<MovieEntity> movieExample = Example.of(
+    new MovieEntity("Matrix", null),
+    ExampleMatcher
+        .matchingAny()
+        .withMatcher(
+            "title",
+            ExampleMatcher.GenericPropertyMatcher.of(ExampleMatcher.StringMatcher.CONTAINING)
+        )
+       .withTransformer("title", Neo4jPropertyValueTransformers.notMatching())
+);
+Flux<MovieEntity> allMoviesThatNotContainMatrix = this.movieRepository.findAll(movieExample);
+----
+
 [[faq.spring-boot.sdn]]
 == Do I need Spring Boot to use Spring Data Neo4j?
 

src/main/java/org/springframework/data/neo4j/core/Neo4jPropertyValueTransformers.java

@@ -0,0 +1,81 @@
+/*
+ * Copyright 2011-2023 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
+ *
+ *      https://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.neo4j.core;
+
+import java.util.Objects;
+
+import org.springframework.data.domain.ExampleMatcher;
+
+/**
+ * Contains some useful transformers for adding additional, supported transformations to {@link ExampleMatcher example matchers} via
+ * {@link org.springframework.data.domain.ExampleMatcher#withTransformer(String, ExampleMatcher.PropertyValueTransformer)}.
+ *
+ * @author Michael J. Simons
+ * @since 6.3.11
+ * @soundtrack Subway To Sally - Herzblut
+ */
+public abstract class Neo4jPropertyValueTransformers {
+
+	/**
+	 * A transformer that will indicate that the generated condition for the specific property shall be negated, creating
+	 * a {@code n.property != $property} for the equality operator for example.
+	 *
+	 * @return A value transformer negating values.
+	 */
+	public static ExampleMatcher.PropertyValueTransformer notMatching() {
+		return o -> o.map(NegatedValue::new);
+	}
+
+	/**
+	 * A wrapper indicating a negated value (will be used as {@code n.property != $parameter} (in case of string properties
+	 * all operators and not only the equality operator are supported, such as {@code not (n.property contains 'x')}.
+	 */
+	public static final class NegatedValue {
+
+		private final Object value;
+
+		/**
+		 * @param value The value used in the negated condition.
+		 */
+		public NegatedValue(Object value) {
+			this.value = value;
+		}
+
+		public Object value() {
+			return value;
+		}
+
+		@Override
+		public boolean equals(Object obj) {
+			if (obj == this) {
+				return true;
+			}
+			if (obj == null || obj.getClass() != this.getClass()) {
+				return false;
+			}
+			NegatedValue that = (NegatedValue) obj;
+			return Objects.equals(this.value, that.value);
+		}
+
+		@Override
+		public int hashCode() {
+			return Objects.hash(value);
+		}
+	}
+
+	private Neo4jPropertyValueTransformers() {
+	}
+}

src/main/java/org/springframework/data/neo4j/repository/query/Predicate.java

@@ -33,9 +33,10 @@
 import org.neo4j.cypherdsl.core.StatementBuilder;
 import org.springframework.data.domain.Example;
 import org.springframework.data.domain.ExampleMatcher;
+import org.springframework.data.neo4j.core.Neo4jPropertyValueTransformers.NegatedValue;
+import org.springframework.data.neo4j.core.convert.Neo4jConversionService;
 import org.springframework.data.neo4j.core.mapping.Constants;
 import org.springframework.data.neo4j.core.mapping.GraphPropertyDescription;
-import org.springframework.data.neo4j.core.convert.Neo4jConversionService;
 import org.springframework.data.neo4j.core.mapping.Neo4jMappingContext;
 import org.springframework.data.neo4j.core.mapping.Neo4jPersistentEntity;
 import org.springframework.data.neo4j.core.mapping.Neo4jPersistentProperty;
@@ -91,15 +92,17 @@ static <S> Predicate create(Neo4jMappingContext mappingContext, Example<S> examp
 
 			Neo4jConversionService conversionService = mappingContext.getConversionService();
 
+			Object theValue = optionalValue.map(v -> v instanceof NegatedValue ? ((NegatedValue) v).value() : v).get();
+			Condition condition = null;
+
 			if (graphProperty.isRelationship()) {
 				Neo4jQuerySupport.REPOSITORY_QUERY_LOG.error("Querying by example does not support traversing of relationships.");
 			} else if (graphProperty.isIdProperty() && probeNodeDescription.isUsingInternalIds()) {
-				predicate.add(mode,
-						predicate.neo4jPersistentEntity.getIdExpression().isEqualTo(literalOf(optionalValue.get())));
+				condition = predicate.neo4jPersistentEntity.getIdExpression().isEqualTo(literalOf(theValue));
 			} else {
 				Expression property = property(Constants.NAME_OF_TYPED_ROOT_NODE.apply(probeNodeDescription), propertyName);
 				Expression parameter = parameter(propertyName);
-				Condition condition = property.isEqualTo(parameter);
+				condition = property.isEqualTo(parameter);
 
 				if (String.class.equals(graphProperty.getActualType())) {
 
@@ -111,7 +114,6 @@ static <S> Predicate create(Neo4jMappingContext mappingContext, Example<S> examp
 					switch (matcherAccessor.getStringMatcherForPath(currentPath)) {
 						case DEFAULT:
 						case EXACT:
-							// This needs to be recreated as both property and parameter might have changed above
 							condition = property.isEqualTo(parameter);
 							break;
 						case CONTAINING:
@@ -132,20 +134,26 @@ static <S> Predicate create(Neo4jMappingContext mappingContext, Example<S> examp
 											.getStringMatcherForPath(currentPath));
 					}
 				}
-				predicate.add(mode, condition);
-				predicate.parameters.put(propertyName, optionalValue.map(
-						v -> {
-							Neo4jPersistentProperty neo4jPersistentProperty = (Neo4jPersistentProperty) graphProperty;
-							return conversionService.writeValue(v, neo4jPersistentProperty.getTypeInformation(),
-											neo4jPersistentProperty.getOptionalConverter());
-						})
-						.get());
+
+				Neo4jPersistentProperty neo4jPersistentProperty = (Neo4jPersistentProperty) graphProperty;
+				predicate.parameters.put(propertyName, conversionService.writeValue(theValue,
+						neo4jPersistentProperty.getTypeInformation(), neo4jPersistentProperty.getOptionalConverter()));
+			}
+			if (condition != null) {
+				predicate.add(mode, postProcess(condition, optionalValue.get()));
 			}
 		}
 
 		return predicate;
 	}
 
+	private static Condition postProcess(Condition condition, Object transformedValue) {
+		if (transformedValue instanceof NegatedValue) {
+			return condition.not();
+		}
+		return condition;
+	}
+
 	private final Neo4jPersistentEntity neo4jPersistentEntity;
 
 	private Condition condition = Conditions.noCondition();

src/test/java/org/springframework/data/neo4j/integration/imperative/RepositoryIT.java

@@ -85,6 +85,7 @@
 import org.springframework.data.neo4j.core.DatabaseSelection;
 import org.springframework.data.neo4j.core.DatabaseSelectionProvider;
 import org.springframework.data.neo4j.core.Neo4jClient;
+import org.springframework.data.neo4j.core.Neo4jPropertyValueTransformers;
 import org.springframework.data.neo4j.core.Neo4jTemplate;
 import org.springframework.data.neo4j.core.UserSelection;
 import org.springframework.data.neo4j.core.UserSelectionProvider;
@@ -2935,6 +2936,45 @@ void countByExampleFluent(@Autowired PersonRepository repository) {
 			assertThat(count).isEqualTo(1);
 		}
 
+		@Test // GH-2703
+		void negatedProperties(@Autowired PersonRepository repository) {
+
+			Example<PersonWithAllConstructor> example = Example.of(new PersonWithAllConstructor(null, person1.getName(), null, null, null, null, null, null, null, null, null),
+					ExampleMatcher.matchingAll().withTransformer("name", Neo4jPropertyValueTransformers.notMatching()));
+
+			Optional<PersonWithAllConstructor> optionalPerson = repository.findOne(example);
+			assertThat(optionalPerson)
+					.map(PersonWithAllConstructor::getName)
+					.hasValue(person2.getName());
+		}
+
+		@Test // GH-2703
+		void negatedInternalIdProperty(@Autowired PersonRepository repository) {
+
+			Example<PersonWithAllConstructor>  example = Example.of(new PersonWithAllConstructor(person1.getId(), null, null, null, null, null, null, null, null, null, null),
+					ExampleMatcher.matchingAll().withTransformer("id", Neo4jPropertyValueTransformers.notMatching()));
+
+			Optional<PersonWithAllConstructor> optionalPerson = repository.findOne(example);
+			assertThat(optionalPerson)
+					.map(PersonWithAllConstructor::getName)
+					.hasValue(person2.getName());
+		}
+
+		@Test // GH-2240
+		void negatedWithExternallyGeneratedId(@Autowired BidirectionalExternallyGeneratedIdRepository repository) {
+
+			BidirectionalExternallyGeneratedId a = repository.save(new BidirectionalExternallyGeneratedId());
+			BidirectionalExternallyGeneratedId b = repository.save(new BidirectionalExternallyGeneratedId());
+
+			Example<BidirectionalExternallyGeneratedId> example = Example.of(a,
+					ExampleMatcher.matchingAll().withTransformer("uuid", Neo4jPropertyValueTransformers.notMatching()));
+
+			Optional<BidirectionalExternallyGeneratedId> optionalResult = repository.findOne(example);
+			assertThat(optionalResult)
+					.map(BidirectionalExternallyGeneratedId::getUuid)
+					.hasValue(b.getUuid());
+		}
+
 		@Test
 		void findEntityWithRelationshipByFindOneByExample(@Autowired RelationshipRepository repository) {
 

src/test/java/org/springframework/data/neo4j/integration/shared/common/BidirectionalExternallyGeneratedId.java

@@ -35,4 +35,11 @@ public class BidirectionalExternallyGeneratedId {
 	@Relationship("OTHER")
 	public BidirectionalExternallyGeneratedId otter;
 
+	public UUID getUuid() {
+		return uuid;
+	}
+
+	public BidirectionalExternallyGeneratedId getOtter() {
+		return otter;
+	}
 }