GH-2313 - Enable multi-level projections.

Closes #2313

Author: meistermeier

src/main/asciidoc/object-mapping/projections.adoc

@@ -29,7 +29,66 @@ can add additional properties.
 The rules are as follows: first, the properties of the domain type are used to populate the DTO. In case the DTO declares
 additional properties - via accessors or fields - Spring Data Neo4j looks in the resulting record for matching properties.
 Properties must match exactly by name and can be of simple types (as defined in `org.springframework.data.neo4j.core.convert.Neo4jSimpleTypes`)
-or of known persistent entites. Collections of those are supported, but maps are not.
+or of known persistent entities. Collections of those are supported, but maps are not.
+
+[[projections.sdn.multi-level]]
+== Multi-level projections
+
+Spring Data Neo4j also supports multi-level projections.
+
+[source,java]
+.Example of multi-level projection
+----
+interface ProjectionWithNestedProjection {
+
+    String getName();
+
+    List<Subprojection1> getLevel1();
+
+    interface Subprojection1 {
+        String getName();
+        List<Subprojection2> getLevel2();
+    }
+
+    interface Subprojection2 {
+        String getName();
+    }
+}
+----
+
+Even though it is possible to model cyclic projections or point towards entities that will create a cycle,
+the projection logic will not follow those cycles but only create cycle-free queries.
+
+Multi-level projections are bounded to the entities they should project.
+`RelationshipProperties` fall into the category of entities in this case and needs to get respected if projections get applied.
+
+[[projections.sdn.persistence]]
+== Persistence of projections
+
+Analogue to the retrieval of data via projections, they can also be used as a blueprint for persistence.
+The `Neo4jTemplate` offers a fluent API to apply those projections to a save operation.
+
+You could either save a projection for a given domain class
+
+[source,java]
+.Save projection for a given domain class
+----
+Projection projection = neo4jTemplate.save(DomainClass.class).one(projectionValue);
+----
+
+or you could save a domain object but only respect the fields defined in the projection.
+
+[source,java]
+.Save domain object with a given projection blueprint
+----
+Projection projection = neo4jTemplate.saveAs(domainObject, Projection.class);
+----
+
+In both cases, that also are available for collection based operations, only the fields and relationships
+defined in the projection will get updated.
+
+NOTE: To prevent deletion of data (e.g. removal of relationships),
+you should always load at least all the data that should get persisted later.
 
 [[projections.sdn.full-example]]
 == A full example

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

@@ -26,11 +26,11 @@
 
 /**
  * {@link FluentFindOperation} allows creation and execution of Neo4j find operations in a fluent API style.
- * <br />
+ * <p>
  * The starting {@literal domainType} is used for mapping the query provided via {@code by} into the
  * Neo4j specific representation. By default, the originating {@literal domainType} is also used for mapping back the
  * result. However, it is possible to define an different {@literal returnType} via
- * {@code as} to mapping the result.<br />
+ * {@code as} to mapping the result.
  *
  * @author Michael Simons
  * @since 6.1

src/main/java/org/springframework/data/neo4j/core/FluentFindOperationSupport.java renamed to src/main/java/org/springframework/data/neo4j/core/FluentOperationSupport.java

@@ -27,11 +27,11 @@
  * @author Michael J. Simons
  * @since 6.1
  */
-final class FluentFindOperationSupport implements FluentFindOperation {
+final class FluentOperationSupport implements FluentFindOperation, FluentSaveOperation {
 
 	private final Neo4jTemplate template;
 
-	FluentFindOperationSupport(Neo4jTemplate template) {
+	FluentOperationSupport(Neo4jTemplate template) {
 		this.template = template;
 	}
 
@@ -98,4 +98,43 @@ private List<T> doFind(TemplateSupport.FetchType fetchType) {
 			return template.doFind(query, parameters, domainType, returnType, fetchType);
 		}
 	}
+
+	@Override
+	public <T> ExecutableSave<T> save(Class<T> domainType) {
+
+		Assert.notNull(domainType, "DomainType must not be null!");
+
+		return new ExecutableSaveSupport<>(this.template, domainType);
+	}
+
+	private static class ExecutableSaveSupport<DT> implements ExecutableSave<DT> {
+
+		private final Neo4jTemplate template;
+		private final Class<DT> domainType;
+
+		ExecutableSaveSupport(Neo4jTemplate template, Class<DT> domainType) {
+			this.template = template;
+			this.domainType = domainType;
+		}
+
+		@Override
+		public <T> T one(T instance) {
+
+			List<T> result = doSave(Collections.singleton(instance));
+			if (result.isEmpty()) {
+				return null;
+			}
+			return result.get(0);
+		}
+
+		@Override
+		public <T> List<T> all(Iterable<T> instances) {
+
+			return doSave(instances);
+		}
+
+		private <T> List<T> doSave(Iterable<T> instances) {
+			return template.doSave(instances, domainType);
+		}
+	}
 }

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

@@ -0,0 +1,70 @@
+/*
+ * Copyright 2011-2021 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.List;
+
+import org.apiguardian.api.API;
+
+/**
+ * {@link FluentSaveOperation} allows creation and execution of Neo4j save operations in a fluent API style. It
+ * is designed to be used together with the {@link FluentFindOperation fluent find operations}.
+ * <p>
+ * Both interfaces provide a way to specify a pair of two types: A domain type and a result (projected) type.
+ * The fluent save operations are mainly used with DTO based projections. Closed interface projections won't be that
+ * helpful when you received them via {@link FluentFindOperation fluent find operations} as they won't be modifiable.
+ *
+ * @author Michael J. Simons
+ * @since TBA
+ */
+@API(status = API.Status.STABLE, since = "TBA")
+public interface FluentSaveOperation {
+
+	/**
+	 * Start creating a save operation for the given {@literal domainType}.
+	 *
+	 * @param domainType must not be {@literal null}.
+	 * @return new instance of {@link ExecutableSave}.
+	 * @throws IllegalArgumentException if domainType is {@literal null}.
+	 */
+	<T> ExecutableSave<T> save(Class<T> domainType);
+
+	/**
+	 * After the domain type has been specified, related projections or instances of the domain type can be saved.
+	 *
+	 * @param <DT> the domain type
+	 */
+	interface ExecutableSave<DT> {
+
+		/**
+		 * @param instance The instance to be saved
+		 * @param <T>      The type of the instance passed to this method. It should be the same as the domain type before
+		 *                 or a projection of the domain type. If they are not related, the results may be undefined.
+		 * @return The saved instance, can also be a new object, so you are recommended to use this instance after
+		 * the save operation
+		 */
+		<T> T one(T instance);
+
+		/**
+		 * @param instances The instances to be saved
+		 * @param <T>       The type of the instances passed to this method. It should be the same as the domain type before
+		 *                  or a projection of the domain type. If they are not related, the results may be undefined.
+		 * @return The saved instances, can also be a new objects, so you are recommended to use those instances
+		 * after the save operation
+		 */
+		<T> List<T> all(Iterable<T> instances);
+	}
+}