GH-2536 - Provide saveAs overloads with a predicate for selecting projected attributes.

Closes #2536.

Author: michael-simons

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

@@ -18,10 +18,12 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Optional;
+import java.util.function.BiPredicate;
 
 import org.apiguardian.api.API;
 import org.neo4j.cypherdsl.core.Statement;
 import org.springframework.dao.IncorrectResultSizeDataAccessException;
+import org.springframework.data.mapping.PropertyPath;
 import org.springframework.data.neo4j.core.mapping.Neo4jPersistentProperty;
 import org.springframework.data.neo4j.repository.NoResultException;
 import org.springframework.data.neo4j.repository.query.QueryFragmentsAndParameters;
@@ -191,6 +193,24 @@ public interface Neo4jOperations {
 	 */
 	<T> T save(T instance);
 
+	/**
+	 * Saves an instance of an entity, using the provided predicate to shape the stored graph. One can think of the predicate
+	 * as a dynamic projection. If you want to save or update properties of associations (aka related nodes), you must include
+	 * the association property as well (meaning the predicate must return {@literal true} for that property, too).
+	 * <p>
+	 * Be careful when reusing the returned instance for further persistence operations, as it will most likely not be
+	 * fully hydrated and without using a static or dynamic projection, you will most likely cause data loss.
+	 *
+	 * @param instance        the entity to be saved. Must not be {@code null}.
+	 * @param includeProperty A predicate to determine the properties to save.
+	 * @param <T>             the type of the entity.
+	 * @return the saved instance.
+	 * @since 6.3
+	 */
+	default <T> T saveAs(T instance, BiPredicate<PropertyPath, Neo4jPersistentProperty> includeProperty) {
+		throw new UnsupportedOperationException();
+	}
+
 	/**
 	 * Saves an instance of an entity, including the properties and relationship defined by the projected {@code resultType}.
 	 *
@@ -213,6 +233,24 @@ default <T, R> R saveAs(T instance, Class<R> resultType) {
 	 */
 	<T> List<T> saveAll(Iterable<T> instances);
 
+	/**
+	 * Saves several instances of an entity, using the provided predicate to shape the stored graph. One can think of the predicate
+	 * as a dynamic projection. If you want to save or update properties of associations (aka related nodes), you must include
+	 * the association property as well (meaning the predicate must return {@literal true} for that property, too).
+	 * <p>
+	 * Be careful when reusing the returned instances for further persistence operations, as they will most likely not be
+	 * fully hydrated and without using a static or dynamic projection, you will most likely cause data loss.
+	 *
+	 * @param instances       the instances to be saved. Must not be {@code null}.
+	 * @param includeProperty A predicate to determine the properties to save.
+	 * @param <T>             the type of the entity.
+	 * @return the saved instances.
+	 * @since 6.3
+	 */
+	default <T> List<T> saveAllAs(Iterable<T> instances, BiPredicate<PropertyPath, Neo4jPersistentProperty> includeProperty) {
+		throw new UnsupportedOperationException();
+	}
+
 	/**
 	 * Saves an instance of an entity, including the properties and relationship defined by the project {@code resultType}.
 	 *

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

@@ -32,6 +32,7 @@
 import java.util.Optional;
 import java.util.Set;
 import java.util.function.BiFunction;
+import java.util.function.BiPredicate;
 import java.util.function.Consumer;
 import java.util.function.Function;
 import java.util.function.Supplier;
@@ -343,6 +344,16 @@ public <T> T save(T instance) {
 		return saveImpl(instance, Collections.emptyMap(), null);
 	}
 
+	@Override
+	public <T> T saveAs(T instance, BiPredicate<PropertyPath, Neo4jPersistentProperty> includeProperty) {
+
+		if (instance == null) {
+			return null;
+		}
+
+		return saveImpl(instance, TemplateSupport.computeIncludedPropertiesFromPredicate(this.neo4jMappingContext, instance.getClass(), includeProperty), null);
+	}
+
 	@Override
 	public <T, R> R saveAs(T instance, Class<R> resultType) {
 
@@ -451,10 +462,10 @@ private <T> DynamicLabels determineDynamicLabels(T entityToBeSaved, Neo4jPersist
 
 	@Override
 	public <T> List<T> saveAll(Iterable<T> instances) {
-		return saveAllImpl(instances, Collections.emptyMap());
+		return saveAllImpl(instances, Collections.emptyMap(), null);
 	}
 
-	private <T> List<T> saveAllImpl(Iterable<T> instances, Map<PropertyPath, Boolean> includedProperties) {
+	private <T> List<T> saveAllImpl(Iterable<T> instances, @Nullable Map<PropertyPath, Boolean> includedProperties, @Nullable BiPredicate<PropertyPath, Neo4jPersistentProperty> includeProperty) {
 
 		Set<Class<?>> types = new HashSet<>();
 		List<T> entities = new ArrayList<>();
@@ -469,13 +480,19 @@ private <T> List<T> saveAllImpl(Iterable<T> instances, Map<PropertyPath, Boolean
 
 		boolean heterogeneousCollection = types.size() > 1;
 		Class<?> domainClass = types.iterator().next();
+
+		Map<PropertyPath, Boolean> pps = includeProperty == null ?
+				includedProperties :
+				TemplateSupport.computeIncludedPropertiesFromPredicate(this.neo4jMappingContext, domainClass,
+						includeProperty);
+
 		Neo4jPersistentEntity<?> entityMetaData = neo4jMappingContext.getRequiredPersistentEntity(domainClass);
 		if (heterogeneousCollection || entityMetaData.isUsingInternalIds() || entityMetaData.hasVersionProperty()
 				|| entityMetaData.getDynamicLabelsProperty().isPresent()) {
 			log.debug("Saving entities using single statements.");
 
 			NestedRelationshipProcessingStateMachine stateMachine = new NestedRelationshipProcessingStateMachine(neo4jMappingContext);
-			return entities.stream().map(e -> saveImpl(e, includedProperties, stateMachine)).collect(Collectors.toList());
+			return entities.stream().map(e -> saveImpl(e, pps, stateMachine)).collect(Collectors.toList());
 		}
 
 		class Tuple3<T> {
@@ -497,7 +514,7 @@ class Tuple3<T> {
 		// Save roots
 		@SuppressWarnings("unchecked") // We can safely assume here that we have a humongous collection with only one single type being either T or extending it
 		Function<T, Map<String, Object>> binderFunction = neo4jMappingContext.getRequiredBinderFunctionFor((Class<T>) domainClass);
-		binderFunction = TemplateSupport.createAndApplyPropertyFilter(includedProperties, entityMetaData, binderFunction);
+		binderFunction = TemplateSupport.createAndApplyPropertyFilter(pps, entityMetaData, binderFunction);
 		List<Map<String, Object>> entityList = entitiesToBeSaved.stream().map(h -> h.modifiedInstance).map(binderFunction)
 				.collect(Collectors.toList());
 		Map<Value, Long> idToInternalIdMapping = neo4jClient
@@ -515,10 +532,16 @@ class Tuple3<T> {
 			Neo4jPersistentProperty idProperty = entityMetaData.getRequiredIdProperty();
 			Object id = convertIdValues(idProperty, propertyAccessor.getProperty(idProperty));
 			Long internalId = idToInternalIdMapping.get(id);
-			return this.<T>processRelations(entityMetaData, propertyAccessor, t.wasNew, new NestedRelationshipProcessingStateMachine(neo4jMappingContext, t.originalInstance, internalId), TemplateSupport.computeIncludePropertyPredicate(includedProperties, entityMetaData));
+			return this.<T>processRelations(entityMetaData, propertyAccessor, t.wasNew, new NestedRelationshipProcessingStateMachine(neo4jMappingContext, t.originalInstance, internalId), TemplateSupport.computeIncludePropertyPredicate(pps, entityMetaData));
 		}).collect(Collectors.toList());
 	}
 
+	@Override
+	public <T> List<T> saveAllAs(Iterable<T> instances, BiPredicate<PropertyPath, Neo4jPersistentProperty> includeProperty) {
+
+		return saveAllImpl(instances, null, includeProperty);
+	}
+
 	@Override
 	public <T, R> List<R> saveAllAs(Iterable<T> instances, Class<R> resultType) {
 
@@ -537,7 +560,7 @@ public <T, R> List<R> saveAllAs(Iterable<T> instances, Class<R> resultType) {
 		Map<PropertyPath, Boolean> pps = PropertyFilterSupport.addPropertiesFrom(commonElementType, resultType,
 				projectionFactory, neo4jMappingContext);
 
-		List<T> savedInstances = saveAllImpl(instances, pps);
+		List<T> savedInstances = saveAllImpl(instances, pps, null);
 
 		if (projectionInformation.isClosed()) {
 			return savedInstances.stream().map(instance -> projectionFactory.createProjection(resultType, instance))

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

@@ -15,12 +15,14 @@
  */
 package org.springframework.data.neo4j.core;
 
+import org.springframework.data.mapping.PropertyPath;
 import org.springframework.data.neo4j.core.mapping.Neo4jPersistentProperty;
 import org.springframework.data.neo4j.repository.query.QueryFragmentsAndParameters;
 import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
 
 import java.util.Map;
+import java.util.function.BiPredicate;
 
 import org.apiguardian.api.API;
 import org.neo4j.cypherdsl.core.Statement;
@@ -190,6 +192,24 @@ public interface ReactiveNeo4jOperations {
 	 */
 	<T> Mono<T> save(T instance);
 
+	/**
+	 * Saves an instance of an entity, using the provided predicate to shape the stored graph. One can think of the predicate
+	 * as a dynamic projection. If you want to save or update properties of associations (aka related nodes), you must include
+	 * the association property as well (meaning the predicate must return {@literal true} for that property, too).
+	 * <p>
+	 * Be careful when reusing the returned instance for further persistence operations, as it will most likely not be
+	 * fully hydrated and without using a static or dynamic projection, you will most likely cause data loss.
+	 *
+	 * @param instance        the entity to be saved. Must not be {@code null}.
+	 * @param includeProperty A predicate to determine the properties to save.
+	 * @param <T>             the type of the entity.
+	 * @return the saved instance.
+	 * @since 6.3
+	 */
+	default <T> Mono<T> saveAs(T instance, BiPredicate<PropertyPath, Neo4jPersistentProperty> includeProperty) {
+		throw new UnsupportedOperationException();
+	}
+
 	/**
 	 * Saves an instance of an entity, including the properties and relationship defined by the projected {@code resultType}.
 	 *
@@ -212,6 +232,24 @@ default <T, R> Mono<R> saveAs(T instance, Class<R> resultType) {
 	 */
 	<T> Flux<T> saveAll(Iterable<T> instances);
 
+	/**
+	 * Saves several instances of an entity, using the provided predicate to shape the stored graph. One can think of the predicate
+	 * as a dynamic projection. If you want to save or update properties of associations (aka related nodes), you must include
+	 * the association property as well (meaning the predicate must return {@literal true} for that property, too).
+	 * <p>
+	 * Be careful when reusing the returned instances for further persistence operations, as they will most likely not be
+	 * fully hydrated and without using a static or dynamic projection, you will most likely cause data loss.
+	 *
+	 * @param instances       the instances to be saved. Must not be {@code null}.
+	 * @param includeProperty A predicate to determine the properties to save.
+	 * @param <T>             the type of the entity.
+	 * @return the saved instances.
+	 * @since 6.3
+	 */
+	default <T> Flux<T> saveAllAs(Iterable<T> instances, BiPredicate<PropertyPath, Neo4jPersistentProperty> includeProperty) {
+		throw new UnsupportedOperationException();
+	}
+
 	/**
 	 * Saves several instances of an entity,  including the properties and relationship defined by the project {@code resultType}.
 	 *

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

@@ -41,6 +41,7 @@
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.BiFunction;
+import java.util.function.BiPredicate;
 import java.util.function.Function;
 import java.util.function.Supplier;
 import java.util.stream.Collectors;
@@ -328,6 +329,16 @@ public <T> Mono<T> save(T instance) {
 		return saveImpl(instance, Collections.emptyMap(), null);
 	}
 
+	@Override
+	public <T> Mono<T> saveAs(T instance, BiPredicate<PropertyPath, Neo4jPersistentProperty> includeProperty) {
+
+		if (instance == null) {
+			return null;
+		}
+
+		return saveImpl(instance, TemplateSupport.computeIncludedPropertiesFromPredicate(this.neo4jMappingContext, instance.getClass(), includeProperty), null);
+	}
+
 	@Override
 	public <T, R> Mono<R> saveAs(T instance, Class<R> resultType) {
 
@@ -464,7 +475,13 @@ private <T> Mono<Tuple2<T, DynamicLabels>> determineDynamicLabels(T entityToBeSa
 
 	@Override
 	public <T> Flux<T> saveAll(Iterable<T> instances) {
-		return saveAllImpl(instances, Collections.emptyMap());
+		return saveAllImpl(instances, Collections.emptyMap(), null);
+	}
+
+	@Override
+	public <T> Flux<T> saveAllAs(Iterable<T> instances, BiPredicate<PropertyPath, Neo4jPersistentProperty> includeProperty) {
+
+		return saveAllImpl(instances, null, includeProperty);
 	}
 
 	@Override
@@ -482,7 +499,7 @@ public <T, R> Flux<R> saveAllAs(Iterable<T> instances, Class<R> resultType) {
 		Map<PropertyPath, Boolean> pps = PropertyFilterSupport.addPropertiesFrom(commonElementType, resultType,
 				projectionFactory, neo4jMappingContext);
 
-		Flux<T> savedInstances = saveAllImpl(instances, pps);
+		Flux<T> savedInstances = saveAllImpl(instances, pps, null);
 		if (projectionInformation.isClosed()) {
 			return savedInstances.map(instance -> projectionFactory.createProjection(resultType, instance));
 		}
@@ -496,7 +513,7 @@ public <T, R> Flux<R> saveAllAs(Iterable<T> instances, Class<R> resultType) {
 		}).map(instance -> projectionFactory.createProjection(resultType, instance));
 	}
 
-	private <T> Flux<T> saveAllImpl(Iterable<T> instances, @Nullable Map<PropertyPath, Boolean> includedProperties) {
+	private <T> Flux<T> saveAllImpl(Iterable<T> instances, @Nullable Map<PropertyPath, Boolean> includedProperties, @Nullable BiPredicate<PropertyPath, Neo4jPersistentProperty> includeProperty) {
 
 		Set<Class<?>> types = new HashSet<>();
 		List<T> entities = new ArrayList<>();
@@ -511,18 +528,24 @@ private <T> Flux<T> saveAllImpl(Iterable<T> instances, @Nullable Map<PropertyPat
 
 		boolean heterogeneousCollection = types.size() > 1;
 		Class<?> domainClass = types.iterator().next();
+
+		Map<PropertyPath, Boolean> pps = includeProperty == null ?
+				includedProperties :
+				TemplateSupport.computeIncludedPropertiesFromPredicate(this.neo4jMappingContext, domainClass,
+						includeProperty);
+
 		Neo4jPersistentEntity<?> entityMetaData = neo4jMappingContext.getRequiredPersistentEntity(domainClass);
 		if (heterogeneousCollection || entityMetaData.isUsingInternalIds() || entityMetaData.hasVersionProperty()
 			|| entityMetaData.getDynamicLabelsProperty().isPresent()) {
 			log.debug("Saving entities using single statements.");
 
 			NestedRelationshipProcessingStateMachine stateMachine = new NestedRelationshipProcessingStateMachine(neo4jMappingContext);
-			return Flux.fromIterable(entities).concatMap(e -> this.saveImpl(e, includedProperties, stateMachine));
+			return Flux.fromIterable(entities).concatMap(e -> this.saveImpl(e, pps, stateMachine));
 		}
 
 		@SuppressWarnings("unchecked") // We can safely assume here that we have a humongous collection with only one single type being either T or extending it
 		Function<T, Map<String, Object>> binderFunction = TemplateSupport.createAndApplyPropertyFilter(
-				includedProperties, entityMetaData,
+				pps, entityMetaData,
 				neo4jMappingContext.getRequiredBinderFunctionFor((Class<T>) domainClass));
 		return Flux.fromIterable(entities)
 				// Map all entities into a tuple <Original, OriginalWasNew>
@@ -551,7 +574,7 @@ private <T> Flux<T> saveAllImpl(Iterable<T> instances, @Nullable Map<PropertyPat
 							Object id = convertIdValues(idProperty, propertyAccessor.getProperty(idProperty));
 							Long internalId = idToInternalIdMapping.get(id);
 							return processRelations(entityMetaData, propertyAccessor, t.getT2(), new NestedRelationshipProcessingStateMachine(neo4jMappingContext, t.getT1(), internalId),
-								TemplateSupport.computeIncludePropertyPredicate(includedProperties, entityMetaData));
+								TemplateSupport.computeIncludePropertyPredicate(pps, entityMetaData));
 						}))
 				);
 	}

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

@@ -24,6 +24,7 @@
 import java.util.Map;
 import java.util.Set;
 import java.util.function.BiFunction;
+import java.util.function.BiPredicate;
 import java.util.function.Function;
 import java.util.function.Predicate;
 import java.util.function.Supplier;
@@ -45,8 +46,10 @@
 import org.springframework.data.neo4j.core.mapping.EntityInstanceWithSource;
 import org.springframework.data.neo4j.core.mapping.Neo4jMappingContext;
 import org.springframework.data.neo4j.core.mapping.Neo4jPersistentEntity;
+import org.springframework.data.neo4j.core.mapping.Neo4jPersistentProperty;
 import org.springframework.data.neo4j.core.mapping.NodeDescription;
 import org.springframework.data.neo4j.core.mapping.PropertyFilter;
+import org.springframework.data.neo4j.core.mapping.PropertyTraverser;
 import org.springframework.data.neo4j.repository.query.QueryFragments;
 import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
@@ -272,6 +275,27 @@ static <T> FilteredBinderFunction<T> createAndApplyPropertyFilter(
 		}));
 	}
 
+	/**
+	 * Helper function that computes the map of included properties for a dynamic projection as expected in 6.2, but
+	 * for fully dynamic projection
+	 *
+	 * @param mappingContext The context to work on
+	 * @param domainType     The projected domain type
+	 * @param predicate      The predicate to compute the included columns
+	 * @param <T>            Type of the domain type
+	 * @return A map as expected by the property filter.
+	 */
+	static <T> Map<PropertyPath, Boolean> computeIncludedPropertiesFromPredicate(Neo4jMappingContext mappingContext,
+			Class<T> domainType, @Nullable BiPredicate<PropertyPath, Neo4jPersistentProperty> predicate) {
+		if (predicate == null) {
+			return Collections.emptyMap();
+		}
+		Map<PropertyPath, Boolean> pps = new HashMap<>();
+		PropertyTraverser traverser = new PropertyTraverser(mappingContext);
+		traverser.traverse(domainType, predicate, (path, property) -> pps.put(path, false));
+		return Collections.unmodifiableMap(pps);
+	}
+
 	/**
 	 * A wrapper around a {@link Function} from entity to {@link Map} which is filtered the {@link PropertyFilter} included as well.
 	 *