GH-2182 - Add support for projections inside the Neo4j templates.

This adds support for projections inside Neo4j templates in a couple of places.
All changes are applied into the reactive and the imperative world:

- `saveAs`
- `saveAllAs`

Methods have been added directly to the `Neo4jOperations`. Those take in a class or interface that should be returned.
The same logic as with projections during reads is applied: Only properties and relationships that are part of the projection are save / updated. All others are left alone. This works exactly one level deep as of now and might change in the future with enhanced Spring Data Commons support. Those methods have been defaulted so that they don’t break peoples implementation of the operations.

In addition, `FluentNeo4jOperations` and some support classes have been introduced that allow to specify the project for finder methods.
The default templates implement does now.

Both templates bring now their own `ProjectionFactory`.

This closes #2182.

Author: michael-simons

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

@@ -0,0 +1,173 @@
+/*
+ * 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.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+
+import org.apiguardian.api.API;
+import org.neo4j.cypherdsl.core.Statement;
+import org.springframework.lang.Nullable;
+
+/**
+ * {@link FluentFindOperation} allows creation and execution of Neo4j find operations in a fluent API style.
+ * <br />
+ * 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 />
+ *
+ * @author Michael Simons
+ * @since 6.1
+ */
+@API(status = API.Status.STABLE, since = "6.1")
+public interface FluentFindOperation {
+
+	/**
+	 * Start creating a find operation for the given {@literal domainType}.
+	 *
+	 * @param domainType must not be {@literal null}.
+	 * @return new instance of {@link ExecutableFind}.
+	 * @throws IllegalArgumentException if domainType is {@literal null}.
+	 */
+	<T> ExecutableFind<T> find(Class<T> domainType);
+
+	/**
+	 * Trigger find execution by calling one of the terminating methods from a state where no query is yet defined.
+	 *
+	 * @param <T> returned type
+	 */
+	interface TerminatingFindWithoutQuery<T> {
+
+		/**
+		 * Get all matching elements.
+		 *
+		 * @return never {@literal null}.
+		 */
+		List<T> all();
+	}
+
+	/**
+	 * Triggers find execution by calling one of the terminating methods.
+	 *
+	 * @param <T> returned type
+	 */
+	interface TerminatingFind<T> extends TerminatingFindWithoutQuery<T> {
+
+		/**
+		 * Get exactly zero or one result.
+		 *
+		 * @return {@link Optional#empty()} if no match found.
+		 * @throws org.springframework.dao.IncorrectResultSizeDataAccessException if more than one match found.
+		 */
+		default Optional<T> one() {
+			return Optional.ofNullable(oneValue());
+		}
+
+		/**
+		 * Get exactly zero or one result.
+		 *
+		 * @return {@literal null} if no match found.
+		 * @throws org.springframework.dao.IncorrectResultSizeDataAccessException if more than one match found.
+		 */
+		@Nullable
+		T oneValue();
+	}
+
+	/**
+	 * Terminating operations invoking the actual query execution.
+	 *
+	 * @param <T> returned type
+	 */
+	interface FindWithQuery<T> extends TerminatingFindWithoutQuery<T> {
+
+		/**
+		 * Set the filter query to be used.
+		 *
+		 * @param query must not be {@literal null}.
+		 * @return new instance of {@link TerminatingFind}.
+		 * @throws IllegalArgumentException if query is {@literal null}.
+		 */
+		TerminatingFind<T> matching(String query, Map<String, Object> parameter);
+
+		/**
+		 * Set the filter query to be used.
+		 *
+		 * @param query must not be {@literal null}.
+		 * @return new instance of {@link TerminatingFind}.
+		 * @throws IllegalArgumentException if query is {@literal null}.
+		 */
+		default TerminatingFind<T> matching(String query) {
+			return matching(query, Collections.emptyMap());
+		}
+
+		/**
+		 * Set the filter {@link Statement statement} to be used.
+		 *
+		 * @param statement must not be {@literal null}.
+		 * @param parameter Will be merged with parameters in the statement. Parameters in {@code parameter} have precedence.
+		 * @return new instance of {@link TerminatingFind}.
+		 * @throws IllegalArgumentException if statement is {@literal null}.
+		 */
+		default TerminatingFind<T> matching(Statement statement, Map<String, Object> parameter) {
+			Map<String, Object> mergedParameters = new HashMap<>();
+			mergedParameters.putAll(statement.getParameters());
+			mergedParameters.putAll(parameter);
+			return matching(statement.getCypher(), mergedParameters);
+		}
+
+		/**
+		 * Set the filter {@link Statement statement} to be used.
+		 *
+		 * @param statement must not be {@literal null}.
+		 * @return new instance of {@link TerminatingFind}.
+		 * @throws IllegalArgumentException if criteria is {@literal null}.
+		 */
+		default TerminatingFind<T> matching(Statement statement) {
+			return matching(statement, Collections.emptyMap());
+		}
+	}
+
+	/**
+	 * Result type override (Optional).
+	 *
+	 * @param <T> returned type
+	 */
+	interface FindWithProjection<T> extends FindWithQuery<T> {
+
+		/**
+		 * Define the target type fields should be mapped to. <br />
+		 * Skip this step if you are anyway only interested in the original domain type.
+		 *
+		 * @param resultType must not be {@literal null}.
+		 * @param <R>        result type.
+		 * @return new instance of {@link FindWithProjection}.
+		 * @throws IllegalArgumentException if resultType is {@literal null}.
+		 */
+		<R> FindWithQuery<R> as(Class<R> resultType);
+	}
+
+	/**
+	 * Entry point for creating executable find operations.
+	 *
+	 * @param <T> returned type
+	 */
+	interface ExecutableFind<T> extends FindWithProjection<T> {
+	}
+}

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

@@ -0,0 +1,101 @@
+/*
+ * 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.Collections;
+import java.util.List;
+import java.util.Map;
+
+import org.springframework.util.Assert;
+
+/**
+ * Implementation of {@link FluentFindOperation}.
+ *
+ * @author Michael J. Simons
+ * @since 6.1
+ */
+final class FluentFindOperationSupport implements FluentFindOperation {
+
+	private final Neo4jTemplate template;
+
+	FluentFindOperationSupport(Neo4jTemplate template) {
+		this.template = template;
+	}
+
+	@Override
+	public <T> ExecutableFind<T> find(Class<T> domainType) {
+
+		Assert.notNull(domainType, "DomainType must not be null!");
+
+		return new ExecutableFindSupport<>(template, domainType, domainType, null, Collections.emptyMap());
+	}
+
+	private static class ExecutableFindSupport<T>
+			implements ExecutableFind<T>, FindWithProjection<T>, FindWithQuery<T>, TerminatingFind<T> {
+
+		private final Neo4jTemplate template;
+		private final Class<?> domainType;
+		private final Class<T> returnType;
+		private final String query;
+		private final Map<String, Object> parameters;
+
+		ExecutableFindSupport(Neo4jTemplate template, Class<?> domainType, Class<T> returnType, String query,
+				Map<String, Object> parameters) {
+			this.template = template;
+			this.domainType = domainType;
+			this.returnType = returnType;
+			this.query = query;
+			this.parameters = parameters;
+		}
+
+		@Override
+		@SuppressWarnings("HiddenField")
+		public <T1> FindWithQuery<T1> as(Class<T1> returnType) {
+
+			Assert.notNull(returnType, "ReturnType must not be null!");
+
+			return new ExecutableFindSupport<>(template, domainType, returnType, query, parameters);
+		}
+
+		@Override
+		@SuppressWarnings("HiddenField")
+		public TerminatingFind<T> matching(String query, Map<String, Object> parameters) {
+
+			Assert.notNull(query, "Query must not be null!");
+
+			return new ExecutableFindSupport<>(template, domainType, returnType, query, parameters);
+		}
+
+		@Override
+		public T oneValue() {
+
+			List<T> result = doFind(TemplateSupport.FetchType.ONE);
+			if (result.isEmpty()) {
+				return null;
+			}
+			return result.iterator().next();
+		}
+
+		@Override
+		public List<T> all() {
+			return doFind(TemplateSupport.FetchType.ALL);
+		}
+
+		private List<T> doFind(TemplateSupport.FetchType fetchType) {
+			return template.doFind(query, parameters, domainType, returnType, fetchType);
+		}
+	}
+}

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

@@ -0,0 +1,30 @@
+/*
+ * 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 org.apiguardian.api.API;
+
+/**
+ * An additional interface accompanying the {@link Neo4jOperations} and adding a couple of fluent operations, especially
+ * around finding and projecting things.
+ *
+ * @author Michael J. Simons
+ * @soundtrack Ozzy Osbourne - Ordinary Man
+ * @since 6.1
+ */
+@API(status = API.Status.STABLE, since = "6.1")
+public interface FluentNeo4jOperations extends FluentFindOperation {
+}

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

@@ -180,6 +180,19 @@ public interface Neo4jOperations {
 	 */
 	<T> T save(T instance);
 
+	/**
+	 * Saves an instance of an entity, including the properties and relationship defined by the projected {@code resultType}.
+	 *
+	 * @param instance the entity to be saved. Must not be {@code null}.
+	 * @param <T> the type of the entity.
+	 * @param <R> the type of the projection to be used during save.
+	 * @return the saved, projected instance.
+	 * @since 6.1
+	 */
+	default <T, R> R saveAs(T instance, Class<R> resultType) {
+		throw new UnsupportedOperationException();
+	}
+
 	/**
 	 * Saves several instances of an entity, including all the related entities of the entity.
 	 *
@@ -189,6 +202,19 @@ public interface Neo4jOperations {
 	 */
 	<T> List<T> saveAll(Iterable<T> instances);
 
+	/**
+	 * Saves an instance of an entity, including the properties and relationship defined by the project {@code resultType}.
+	 *
+	 * @param instances the instances to be saved. Must not be {@code null}.
+	 * @param <T> the type of the entity.
+	 * @param <R> the type of the projection to be used during save.
+	 * @return the saved, projected instance.
+	 * @since 6.1
+	 */
+	default <T, R> List<R> saveAllAs(Iterable<T> instances, Class<R> resultType) {
+		throw new UnsupportedOperationException();
+	}
+
 	/**
 	 * Deletes a single entity including all entities related to that entity.
 	 *