DATAGRAPH-1452 - Support known entities as parameter for repository methods.

Introduce a `Neo4jNestedMapEntityWriter`, responsible for turning mapped entities into nested maps of Neo4j values.

The `Neo4jNestedMapEntityWriter` is called from the repository infrasctructure, not from the templates itself to be consistent in the way that the templates don’t do automatic conversions of parameters.

Author: michael-simons

src/main/asciidoc/faq/faq.adoc

@@ -171,6 +171,176 @@ The Spring Boot Maven and Gradle plugins do this automatically for you.
 If this is not feasible for any reason, you can either add
 `@Param`  and specify the name explicitly or use the parameters index.
 
+Mapped entities (everything with a `@Node`) passed as parameter to a function that is annotated with
+a custom query will be turned into a nested map.
+The following example represents the structure as Neo4j parameters.
+
+Given are a `Movie`, `Person` and `Actor` classes annotated as shown in <<movie-model, the movie model>>:
+
+[[movie-model]]
+[source,java]
+."Standard" movies model
+----
+@Node
+public final class Movie {
+
+    @Id
+    private final String title;
+
+    @Property("tagline")
+    private final String description;
+
+    @Relationship(value = "ACTED_IN", direction = Direction.INCOMING)
+    private final List<Actor> actors;
+
+    @Relationship(value = "DIRECTED", direction = Direction.INCOMING)
+    private final List<Person> directors;
+}
+
+@Node
+public final class Person {
+
+    @Id @GeneratedValue
+    private final Long id;
+
+    private final String name;
+
+    private Integer born;
+
+    @Relationship("REVIEWED")
+    private List<Movie> reviewed = new ArrayList<>();
+}
+
+@RelationshipProperties
+public final class Actor {
+
+    @TargetNode
+    private final Person person;
+
+    private final List<String> roles;
+}
+
+interface MovieRepository extends Neo4jRepository<Movie, String> {
+
+    @Query("MATCH (m:Movie {title: $movie.__id__})\n"
+           + "MATCH (m) <- [r:DIRECTED|REVIEWED|ACTED_IN] - (p:Person)\n"
+           + "return m, collect(r), collect(p)")
+    Movie findByMovie(@Param("movie") Movie movie);
+}
+----
+
+Passing an instance of `Movie` to the repository method above, will generate the following Neo4j map parameter:
+
+[source,json]
+----
+{
+  "movie": {
+    "__labels__": [
+      "Movie"
+    ],
+    "__id__": "The Da Vinci Code",
+    "__properties__": {
+      "ACTED_IN": [
+        {
+          "__properties__": {
+            "roles": [
+              "Sophie Neveu"
+            ]
+          },
+          "__target__": {
+            "__labels__": [
+              "Person"
+            ],
+            "__id__": 402,
+            "__properties__": {
+              "name": "Audrey Tautou",
+              "born": 1976
+            }
+          }
+        },
+        {
+          "__properties__": {
+            "roles": [
+              "Sir Leight Teabing"
+            ]
+          },
+          "__target__": {
+            "__labels__": [
+              "Person"
+            ],
+            "__id__": 401,
+            "__properties__": {
+              "name": "Ian McKellen",
+              "born": 1939
+            }
+          }
+        },
+        {
+          "__properties__": {
+            "roles": [
+              "Dr. Robert Langdon"
+            ]
+          },
+          "__target__": {
+            "__labels__": [
+              "Person"
+            ],
+            "__id__": 360,
+            "__properties__": {
+              "name": "Tom Hanks",
+              "born": 1956
+            }
+          }
+        },
+        {
+          "__properties__": {
+            "roles": [
+              "Silas"
+            ]
+          },
+          "__target__": {
+            "__labels__": [
+              "Person"
+            ],
+            "__id__": 403,
+            "__properties__": {
+              "name": "Paul Bettany",
+              "born": 1971
+            }
+          }
+        }
+      ],
+      "DIRECTED": [
+        {
+          "__labels__": [
+            "Person"
+          ],
+          "__id__": 404,
+          "__properties__": {
+            "name": "Ron Howard",
+            "born": 1954
+          }
+        }
+      ],
+      "tagline": "Break The Codes",
+      "released": 2006
+    }
+  }
+}
+----
+
+A node is represented by a map. The map will always contain `__id__`  which is the mapped id property.
+Under `__labels__` all labels, static and dynamic, will be available.
+All properties - and type of relationships - appear in those maps as they would appear in the graph when the entity would
+have been written by SDN.
+Values will have the correct Cypher type and won't need further conversion.
+
+All relationships are lists of maps. Dynamic relationships will be resolved accordingly.
+If an entity has a relationship with the same type to different types of others nodes, they will all appear in the same list.
+If you need such a mapping and also have the need to work with those custom parameters, you have to unroll it accordingly.
+One way to do this are correlated subqueries (Neo4j 4.1+ required).
+
+
 [[faq.custom-queries]]
 == How do I use custom queries with repository methods returning `Page<T>` or `Slice<T>`?
 

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

@@ -34,11 +34,22 @@ public final class Constants {
 	public static final SymbolicName NAME_OF_ROOT_NODE = Cypher.name("n");
 
 	public static final String NAME_OF_INTERNAL_ID = "__internalNeo4jId__";
+	/**
+	 * Indicates the list of dynamic labels.
+	 */
 	public static final String NAME_OF_LABELS = "__nodeLabels__";
+	/**
+	 * Indicates the list of all labels.
+	 */
+	public static final String NAME_OF_ALL_LABELS = "__labels__";
 	public static final String NAME_OF_IDS = "__ids__";
 	public static final String NAME_OF_ID = "__id__";
 	public static final String NAME_OF_VERSION_PARAM = "__version__";
 	public static final String NAME_OF_PROPERTIES_PARAM = "__properties__";
+	/**
+	 * Indicates the parameter that contains the static labels which are required to correctly compute the difference
+	 * in the list of dynamic labels when saving a node.
+	 */
 	public static final String NAME_OF_STATIC_LABELS_PARAM = "__staticLabels__";
 	public static final String NAME_OF_ENTITY_LIST_PARAM = "__entities__";
 	public static final String NAME_OF_PATHS = "__paths__";

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

@@ -25,6 +25,7 @@
 import org.apiguardian.api.API;
 import org.neo4j.driver.Value;
 import org.neo4j.driver.types.Type;
+import org.springframework.lang.Nullable;
 
 /**
  * @author Michael J. Simons
@@ -43,15 +44,16 @@ public final class MappingSupport {
 	 * @return A unified collection (Either a collection of Map.Entry for dynamic and relationships with properties or a
 	 *         list of related values)
 	 */
-	public static Collection<?> unifyRelationshipValue(Neo4jPersistentProperty property, Object rawValue) {
+	public static @Nullable Collection<?> unifyRelationshipValue(Neo4jPersistentProperty property, Object rawValue) {
 		Collection<?> unifiedValue;
 		if (property.isDynamicAssociation()) {
 			if (property.isDynamicOneToManyAssociation()) {
-				unifiedValue = ((Map<String, Collection<?>>) rawValue).entrySet().stream()
-						.flatMap(e -> e.getValue().stream().map(v -> new SimpleEntry(e.getKey(), v))).collect(
-								Collectors.toList());
+				unifiedValue = ((Map<?, Collection<?>>) rawValue)
+						.entrySet().stream()
+						.flatMap(e -> e.getValue().stream().map(v -> new SimpleEntry(e.getKey(), v)))
+						.collect(Collectors.toList());
 			} else {
-				unifiedValue = ((Map<String, Object>) rawValue).entrySet();
+				unifiedValue = ((Map<?, Object>) rawValue).entrySet();
 			}
 		} else if (property.isRelationshipWithProperties()) {
 			unifiedValue = (Collection<Object>) rawValue;
@@ -92,7 +94,7 @@ private MappingSupport() {}
 	 * Class that defines a tuple of relationship with properties and the connected target entity.
 	 */
 	@API(status = API.Status.INTERNAL)
-	final static class RelationshipPropertiesWithEntityHolder {
+	public final static class RelationshipPropertiesWithEntityHolder {
 		private final Object relationshipProperties;
 		private final Object relatedEntity;
 
@@ -101,11 +103,11 @@ final static class RelationshipPropertiesWithEntityHolder {
 			this.relatedEntity = relatedEntity;
 		}
 
-		Object getRelationshipProperties() {
+		public Object getRelationshipProperties() {
 			return relationshipProperties;
 		}
 
-		Object getRelatedEntity() {
+		public Object getRelatedEntity() {
 			return relatedEntity;
 		}
 	}

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

@@ -148,7 +148,6 @@ boolean hasCustomWriteTarget(Class<?> targetType) {
 		return conversionService.hasCustomWriteTarget(targetType);
 	}
 
-
 	/*
 	 * (non-Javadoc)
 	 * @see org.springframework.data.mapping.context.AbstractMappingContext#createPersistentEntity(org.springframework.data.util.TypeInformation)
@@ -339,7 +338,7 @@ public CreateRelationshipStatementHolder createStatement(Neo4jPersistentEntity<?
 			String dynamicRelationshipType = null;
 			if (relationshipContext.getRelationship().isDynamic()) {
 				TypeInformation<?> keyType = relationshipContext.getInverse().getTypeInformation().getRequiredComponentType();
-				Object key = ((Map.Entry<String, ?>) relatedValue).getKey();
+				Object key = ((Map.Entry) relatedValue).getKey();
 				dynamicRelationshipType = conversionService.writeValue(key, keyType, relationshipContext.getInverse().getOptionalWritingConverter()).asString();
 			}
 			return createStatementForRelationShipWithProperties(