feat: Allow cascading updates to be disabled. (#2897)

This adds a boolean attribute `cascadeUpdates` to `@Relationship`, selectively preventing the cascade of updates. This attribute will be `false` by default.

It does not have an effect when storing new entities.
It does not affect the deletion of relationships.
It does not affect the storing of relationships with or without properties.

Be aware that with a non-cascading update, you can bring your aggregate root in a state in which it is no longer in sync with the actual state of it in the graph.

Thanks to @shanon84 for valuable input.

Closes #2604

Author: michael-simons

pom.xml

@@ -114,6 +114,7 @@
 		<skipUnitTests>${skipTests}</skipUnitTests>
 
 		<springdata.commons>3.3.0-SNAPSHOT</springdata.commons>
+		<junit-pioneer.version>2.2.0</junit-pioneer.version>
 	</properties>
 
 	<dependencyManagement>
@@ -141,6 +142,11 @@
 				<version>${junit-cc-testcontainer}</version>
 				<scope>test</scope>
 			</dependency>
+			<dependency>
+				<groupId>org.junit-pioneer</groupId>
+				<artifactId>junit-pioneer</artifactId>
+				<version>${junit-pioneer.version}</version>
+			</dependency>
 			<dependency>
 				<groupId>io.github.classgraph</groupId>
 				<artifactId>classgraph</artifactId>
@@ -441,6 +447,11 @@
 			<artifactId>blockhound</artifactId>
 			<scope>test</scope>
 		</dependency>
+		<dependency>
+			<groupId>org.junit-pioneer</groupId>
+			<artifactId>junit-pioneer</artifactId>
+			<scope>test</scope>
+		</dependency>
 	</dependencies>
 
 	<repositories>

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

@@ -890,8 +890,7 @@ private <T> T processNestedRelations(
 				// here a map entry is not always anymore a dynamic association
 				Object relatedObjectBeforeCallbacksApplied = relationshipContext.identifyAndExtractRelationshipTargetNode(relatedValueToStore);
 				Neo4jPersistentEntity<?> targetEntity = neo4jMappingContext.getRequiredPersistentEntity(relatedObjectBeforeCallbacksApplied.getClass());
-
-				boolean isEntityNew = targetEntity.isNew(relatedObjectBeforeCallbacksApplied);
+				boolean isNewEntity = targetEntity.isNew(relatedObjectBeforeCallbacksApplied);
 
 				Object newRelatedObject = stateMachine.hasProcessedValue(relatedObjectBeforeCallbacksApplied)
 						? stateMachine.getProcessedAs(relatedObjectBeforeCallbacksApplied)
@@ -903,7 +902,13 @@ private <T> T processNestedRelations(
 				if (stateMachine.hasProcessedValue(relatedValueToStore)) {
 					relatedInternalId = stateMachine.getObjectId(relatedValueToStore);
 				} else {
-					savedEntity = saveRelatedNode(newRelatedObject, targetEntity, includeProperty, currentPropertyPath);
+					if (isNewEntity || relationshipDescription.cascadeUpdates()) {
+						savedEntity = saveRelatedNode(newRelatedObject, targetEntity, includeProperty, currentPropertyPath);
+					} else {
+						var targetPropertyAccessor = targetEntity.getPropertyAccessor(newRelatedObject);
+						var requiredIdProperty = targetEntity.getRequiredIdProperty();
+						savedEntity = loadRelatedNode(targetEntity, targetPropertyAccessor.getProperty(requiredIdProperty));
+					}
 					relatedInternalId = TemplateSupport.rendererCanUseElementIdIfPresent(renderer, targetEntity) ? savedEntity.elementId() : savedEntity.id();
 					stateMachine.markEntityAsProcessed(relatedValueToStore, relatedInternalId);
 					if (relatedValueToStore instanceof MappingSupport.RelationshipPropertiesWithEntityHolder) {
@@ -987,7 +992,7 @@ private <T> T processNestedRelations(
 				}
 
 				if (processState != ProcessState.PROCESSED_ALL_VALUES) {
-					processNestedRelations(targetEntity, targetPropertyAccessor, isEntityNew, stateMachine, includeProperty, currentPropertyPath);
+					processNestedRelations(targetEntity, targetPropertyAccessor, isNewEntity, stateMachine, includeProperty, currentPropertyPath);
 				}
 
 				Object potentiallyRecreatedNewRelatedObject = MappingSupport.getRelationshipOrRelationshipPropertiesObject(neo4jMappingContext,
@@ -1039,6 +1044,23 @@ private <T> T processNestedRelations(
 		return finalSubgraphRoot;
 	}
 
+	// The pendant to {@link #saveRelatedNode(Object, NodeDescription, PropertyFilter, PropertyFilter.RelaxedPropertyPath)}
+	// We can't do without a query, as we need to refresh the internal id
+	private Entity loadRelatedNode(NodeDescription<?> targetNodeDescription, Object relatedInternalId) {
+
+		var targetPersistentEntity = (Neo4jPersistentEntity<?>) targetNodeDescription;
+		var queryFragmentsAndParameters = QueryFragmentsAndParameters.forFindById(targetPersistentEntity, convertIdValues(targetPersistentEntity.getRequiredIdProperty(), relatedInternalId));
+		var nodeName = Constants.NAME_OF_TYPED_ROOT_NODE.apply(targetNodeDescription).getValue();
+
+		return neo4jClient
+				.query(() -> renderer.render(
+						cypherGenerator.prepareFindOf(targetNodeDescription, queryFragmentsAndParameters.getQueryFragments().getMatchOn(),
+								queryFragmentsAndParameters.getQueryFragments().getCondition()).returning(nodeName).build()))
+				.bindAll(queryFragmentsAndParameters.getParameters())
+				.fetchAs(Entity.class).mappedBy((t, r) -> r.get(nodeName).asNode())
+				.one().orElseThrow();
+	}
+
 	private void assignIdToRelationshipProperties(
 			NestedRelationshipContext relationshipContext,
 			Object relatedValueToStore,

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

@@ -969,14 +969,16 @@ private <T> Mono<T> processNestedRelations(Neo4jPersistentEntity<?> sourceEntity
 			Flux<RelationshipHandler> relationshipCreation = Flux.fromIterable(relatedValuesToStore).concatMap(relatedValueToStore -> {
 
 				Object relatedObjectBeforeCallbacksApplied = relationshipContext.identifyAndExtractRelationshipTargetNode(relatedValueToStore);
+				Neo4jPersistentEntity<?> targetEntity = neo4jMappingContext.getRequiredPersistentEntity(relatedObjectBeforeCallbacksApplied.getClass());
+				boolean isNewEntity = targetEntity.isNew(relatedObjectBeforeCallbacksApplied);
+
 				return Mono.deferContextual(ctx ->
 
 						(stateMachine.hasProcessedValue(relatedObjectBeforeCallbacksApplied)
 								? Mono.just(stateMachine.getProcessedAs(relatedObjectBeforeCallbacksApplied))
 								: eventSupport.maybeCallBeforeBind(relatedObjectBeforeCallbacksApplied))
 
 						.flatMap(newRelatedObject -> {
-							Neo4jPersistentEntity<?> targetEntity = neo4jMappingContext.getRequiredPersistentEntity(relatedObjectBeforeCallbacksApplied.getClass());
 
 							Mono<Tuple2<AtomicReference<Object>, AtomicReference<Entity>>> queryOrSave;
 							if (stateMachine.hasProcessedValue(relatedValueToStore)) {
@@ -987,7 +989,16 @@ private <T> Mono<T> processNestedRelations(Neo4jPersistentEntity<?> sourceEntity
 								}
 								queryOrSave = Mono.just(Tuples.of(relatedInternalId, new AtomicReference<>()));
 							} else {
-								queryOrSave = saveRelatedNode(newRelatedObject, targetEntity, includeProperty, currentPropertyPath)
+								Mono<Entity> savedEntity;
+								if (isNewEntity || relationshipDescription.cascadeUpdates()) {
+									savedEntity = saveRelatedNode(newRelatedObject, targetEntity, includeProperty, currentPropertyPath);
+								} else {
+									var targetPropertyAccessor = targetEntity.getPropertyAccessor(newRelatedObject);
+									var requiredIdProperty = targetEntity.getRequiredIdProperty();
+									savedEntity = loadRelatedNode(targetEntity, targetPropertyAccessor.getProperty(requiredIdProperty));
+								}
+
+								queryOrSave = savedEntity
 										.map(entity -> Tuples.of(new AtomicReference<>((Object) (TemplateSupport.rendererCanUseElementIdIfPresent(renderer, targetEntity) ? entity.elementId() : entity.id())), new AtomicReference<>(entity)))
 										.doOnNext(t -> {
 											var relatedInternalId = t.getT1().get();
@@ -998,6 +1009,7 @@ private <T> Mono<T> processNestedRelations(Neo4jPersistentEntity<?> sourceEntity
 											}
 										});
 							}
+
 							return queryOrSave.flatMap(idAndEntity -> {
 									Object relatedInternalId = idAndEntity.getT1().get();
 									Entity savedEntity = idAndEntity.getT2().get();
@@ -1088,6 +1100,23 @@ private <T> Mono<T> processNestedRelations(Neo4jPersistentEntity<?> sourceEntity
 
 	}
 
+	// The pendant to {@link #saveRelatedNode(Object, Neo4jPersistentEntity, PropertyFilter, PropertyFilter.RelaxedPropertyPath)}
+	// We can't do without a query, as we need to refresh the internal id
+	private Mono<Entity> loadRelatedNode(NodeDescription<?> targetNodeDescription, Object relatedInternalId) {
+
+		var targetPersistentEntity = (Neo4jPersistentEntity<?>) targetNodeDescription;
+		var queryFragmentsAndParameters = QueryFragmentsAndParameters.forFindById(targetPersistentEntity, convertIdValues(targetPersistentEntity.getRequiredIdProperty(), relatedInternalId));
+		var nodeName = Constants.NAME_OF_TYPED_ROOT_NODE.apply(targetNodeDescription).getValue();
+
+		return neo4jClient
+				.query(() -> renderer.render(
+						cypherGenerator.prepareFindOf(targetNodeDescription, queryFragmentsAndParameters.getQueryFragments().getMatchOn(),
+								queryFragmentsAndParameters.getQueryFragments().getCondition()).returning(nodeName).build()))
+				.bindAll(queryFragmentsAndParameters.getParameters())
+				.fetchAs(Entity.class).mappedBy((t, r) -> r.get(nodeName).asNode())
+				.one();
+	}
+
 	private Mono<Entity> saveRelatedNode(Object relatedNode, Neo4jPersistentEntity<?> targetNodeDescription, PropertyFilter includeProperty, PropertyFilter.RelaxedPropertyPath currentPropertyPath) {
 
 		return determineDynamicLabels(relatedNode, targetNodeDescription)

src/main/java/org/springframework/data/neo4j/core/mapping/CypherGenerator.java

@@ -756,6 +756,12 @@ public Collection<Expression> createGenericReturnStatement() {
 		return returnExpressions;
 	}
 
+
+	public StatementBuilder.OngoingReading prepareFindOf(NodeDescription<?> nodeDescription, @Nullable List<PatternElement> initialMatchOn, @Nullable Condition condition) {
+		var rootNode = createRootNode(nodeDescription);
+		return prepareMatchOfRootNode(rootNode, initialMatchOn).where(conditionOrNoCondition(condition));
+	}
+
 	private MapProjection projectPropertiesAndRelationships(PropertyFilter.RelaxedPropertyPath parentPath, Neo4jPersistentEntity<?> nodeDescription, SymbolicName nodeName,
 															Predicate<PropertyFilter.RelaxedPropertyPath> includedProperties, @Nullable RelationshipDescription relationshipDescription, List<RelationshipDescription> processedRelationships) {
 

src/main/java/org/springframework/data/neo4j/core/mapping/DefaultNeo4jPersistentProperty.java

@@ -169,7 +169,7 @@ protected Association<Neo4jPersistentProperty> createAssociation() {
 
 		DefaultRelationshipDescription relationshipDescription = new DefaultRelationshipDescription(this,
 				obverseRelationshipDescription.orElse(null), type, dynamicAssociation, (NodeDescription<?>) getOwner(),
-				this.getName(), obverseOwner, direction, relationshipPropertiesClass);
+				this.getName(), obverseOwner, direction, relationshipPropertiesClass, relationship == null || relationship.cascadeUpdates());
 
 		// Update the previous found, if any, relationship with the newly created one as its counterpart.
 		obverseRelationshipDescription

src/main/java/org/springframework/data/neo4j/core/mapping/DefaultRelationshipDescription.java

@@ -44,9 +44,12 @@ final class DefaultRelationshipDescription extends Association<Neo4jPersistentPr
 
 	private RelationshipDescription relationshipObverse;
 
+	private final boolean cascadeUpdates;
+
 	DefaultRelationshipDescription(Neo4jPersistentProperty inverse, @Nullable RelationshipDescription relationshipObverse,
 			String type, boolean dynamic, NodeDescription<?> source, String fieldName, NodeDescription<?> target,
-			Relationship.Direction direction, @Nullable NodeDescription<?> relationshipProperties) {
+			Relationship.Direction direction, @Nullable NodeDescription<?> relationshipProperties,
+			boolean cascadeUpdates) {
 
 		// the immutable obverse association-wise is always null because we cannot determine them on both sides
 		// if we consider to support bidirectional relationships.
@@ -60,6 +63,7 @@ final class DefaultRelationshipDescription extends Association<Neo4jPersistentPr
 		this.target = target;
 		this.direction = direction;
 		this.relationshipPropertiesClass = relationshipProperties;
+		this.cascadeUpdates = cascadeUpdates;
 	}
 
 	@Override
@@ -117,6 +121,11 @@ public boolean hasRelationshipObverse() {
 		return this.relationshipObverse != null;
 	}
 
+	@Override
+	public boolean cascadeUpdates() {
+		return cascadeUpdates;
+	}
+
 	@Override
 	public String toString() {
 		return "DefaultRelationshipDescription{" + "type='" + type + '\'' + ", source='" + source + '\'' + ", direction='"

src/main/java/org/springframework/data/neo4j/core/mapping/RelationshipDescription.java

@@ -138,4 +138,9 @@ default String generateRelatedNodesCollectionName(NodeDescription<?> mostAbstrac
 	 * @return true if a logically same relationship in the target entity exists, otherwise false.
 	 */
 	boolean hasRelationshipObverse();
+
+	/**
+	 * {@return true if updates should be cascaded along this relationship}
+	 */
+	boolean cascadeUpdates();
 }

src/main/java/org/springframework/data/neo4j/core/schema/Relationship.java

@@ -82,4 +82,13 @@ public Direction opposite() {
 	 * @return The direction of the relationship.
 	 */
 	Direction direction() default Direction.OUTGOING;
+
+	/**
+	 * Set this attribute to {@literal false} if you don't want updates on an aggregate root to be cascaded to related objects.
+	 * Be aware that in this case you are responsible to manually save the related objects and that you might end up with a local
+	 * object graph that is not in sync with the actual graph.
+	 *
+	 * @return whether updates to the owning instance should be cascaded to the related objects
+	 */
+	boolean cascadeUpdates() default true;
 }

src/test/java/org/springframework/data/neo4j/integration/cascading/AbstractCascadingTestBase.java

@@ -0,0 +1,127 @@
+/*
+ * Copyright 2011-2024 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.integration.cascading;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import org.junit.jupiter.api.BeforeAll;
+import org.neo4j.driver.Driver;
+import org.neo4j.driver.types.TypeSystem;
+import org.springframework.beans.factory.annotation.Autowired;
+
+abstract class AbstractCascadingTestBase {
+
+	@Autowired
+	Driver driver;
+
+	static Map<Class<? extends Parent>, String> EXISTING_IDS = new HashMap<>();
+
+	@BeforeAll
+	static void clean(@Autowired Driver driver) {
+
+		EXISTING_IDS.clear();
+		driver.executableQuery("MATCH (n) DETACH DELETE n").execute();
+		for (Class<? extends Parent> type : List.of(PUI.class, PUE.class, PVI.class, PVE.class)) {
+			var label = type.getSimpleName();
+			var id = "";
+			var idReturn = "elementId(p) AS id";
+			var version = "";
+			if (ExternalId.class.isAssignableFrom(type)) {
+				id = "SET p.id = randomUUID()";
+				idReturn = "p.id AS id";
+			}
+			if (Versioned.class.isAssignableFrom(type)) {
+				version = "SET p.version = 1";
+
+			}
+			var newId = driver.executableQuery("""
+					WITH 'ParentDB' AS name
+					CREATE (p:%s {id: randomUUID(), name: name})
+					%s
+					%s
+					CREATE (p) -[:HAS_SINGLE_CUI]-> (sCUI:CUI {name: name + '.singleCUI'})
+					CREATE (p) -[:HAS_SINGLE_CUE]-> (sCUE:CUE {name: name + '.singleCUE', id: randomUUID()})
+					CREATE (p) -[:HAS_MANY_CUI]->   (mCUI1:CUI {name: name + '.cUI1'})
+					CREATE (p) -[:HAS_MANY_CUI]->   (mCUI2:CUI {name: name + '.cUI2'})
+					CREATE (p) -[:HAS_SINGLE_CVI]-> (sCVI:CVI {name: name + '.singleCVI', version: 0})
+					CREATE (p) -[:HAS_SINGLE_CVE]-> (sCVE:CVE {name: name + '.singleCVE', version: 0, id: randomUUID()})
+					CREATE (p) -[:HAS_MANY_CVI]->   (mCVI1:CVI {name: name + '.cVI1', version: 0})
+					CREATE (p) -[:HAS_MANY_CVI]->   (mCVI2:CVI {name: name + '.cVI2', version: 0})
+					CREATE (sCUI) -[:HAS_NESTED_CHILDREN]-> (:CUI {name: name + '.singleCUI.c1'})
+					CREATE (sCUI) -[:HAS_NESTED_CHILDREN]-> (:CUI {name: name + '.singleCUI.c2'})
+					CREATE (mCUI1) -[:HAS_NESTED_CHILDREN]-> (:CUI {name: name + '.cUI1.cc1'})
+					CREATE (mCUI1) -[:HAS_NESTED_CHILDREN]-> (:CUI {name: name + '.cUI1.cc2'})
+					CREATE (mCUI2) -[:HAS_NESTED_CHILDREN]-> (:CUI {name: name + '.cUI2.cc1'})
+					CREATE (mCUI2) -[:HAS_NESTED_CHILDREN]-> (:CUI {name: name + '.cUI2.cc2'})
+					RETURN %s
+					""".formatted(label, id, version, idReturn)).execute().records().get(0).get("id").asString();
+			EXISTING_IDS.put(type, newId);
+		}
+	}
+
+
+	<T extends Parent> void assertAllRelationshipsHaveBeenCreated(T instance) {
+
+		var type = instance.getClass();
+		try (var session = driver.session()) {
+			var result = session.run("""
+							MATCH (p:%s WHERE %s)
+							MATCH (p) -[:HAS_SINGLE_CUI]-> (sCUI)
+							MATCH (p) -[:HAS_SINGLE_CUE]-> (sCUE)
+							MATCH (p) -[:HAS_MANY_CUI]->   (mCUI)
+							MATCH (p) -[:HAS_SINGLE_CVI]-> (sCVI {version: 0})
+							MATCH (p) -[:HAS_SINGLE_CVE]-> (sCVE {version: 0})
+							MATCH (p) -[:HAS_MANY_CVI]->    (mCVI {version: 0})
+							MATCH (sCUI) -[:HAS_NESTED_CHILDREN]-> (nc1)
+							MATCH (mCUI) -[:HAS_NESTED_CHILDREN]-> (nc2)
+							RETURN p, sCUI, sCUE, collect(DISTINCT mCUI) AS mCUI, collect(DISTINCT nc1) AS nc1, collect(DISTINCT nc2) AS nc2,
+							          sCVI, sCVE, collect(DISTINCT mCVI) AS mCVI
+							""".formatted(type.getSimpleName(), instance instanceof ExternalId ? "p.id = $id" : "elementId(p) = $id"), Map.of("id", instance.getId()))
+					.list();
+
+			assertThat(result).hasSize(1).element(0)
+					.satisfies(r -> {
+						if (instance instanceof Versioned) {
+							assertThat(r.get("p").asNode().get("version").asLong()).isZero();
+						}
+						if (instance instanceof ExternalId) {
+							assertThat(r.get("p").asNode().get("id").asString()).isEqualTo(instance.getId());
+						} else {
+							assertThat(r.get("p").asNode().elementId()).isEqualTo(instance.getId());
+						}
+						assertThat(r.get("sCUI").hasType(TypeSystem.getDefault().NODE())).isTrue();
+						assertThat(r.get("sCUE").hasType(TypeSystem.getDefault().NODE())).isTrue();
+						assertThat(r.get("mCUI").asList(v -> v.asNode().get("name").asString()))
+								.containsExactlyInAnyOrder("Parent.cUI1", "Parent.cUI2");
+						assertThat(r.get("nc1").asList(v -> v.asNode().get("name").asString()))
+								.containsExactlyInAnyOrder("Parent.singleCUI.cc1", "Parent.singleCUI.cc2");
+						assertThat(r.get("nc2").asList(v -> v.asNode().get("name").asString()))
+								.containsExactlyInAnyOrder("Parent.cUI1.cc1", "Parent.cUI1.cc2", "Parent.cUI2.cc1", "Parent.cUI2.cc2");
+						assertThat(r.get("sCVI").asNode().get("version").asLong()).isZero();
+						assertThat(r.get("sCVE").asNode().get("version").asLong()).isZero();
+						assertThat(r.get("mCVI").asList(v -> {
+							var node = v.asNode();
+							return node.get("name").asString() + "." + node.get("version").asLong();
+						}))
+								.containsExactlyInAnyOrder("Parent.cVI1.0", "Parent.cVI2.0");
+					});
+		}
+	}
+}