DATAGRAPH-1393 - Add support for OGM's CompositeAttributeConverter.

This brings in the necessary infrastructure for decomposing single attributes of an entity into a map of properties that are all written to the node or relationship.

The `CompositeProperty`-annotation lives in the `schema` package as it defines the schema from the point of the Java mapping code.

`CompositeProperty` will work out of the box on maps with key of types string or enum, with configurable prefix and separator. In addition with additional converters it can be applied to attributes of custom types, too.

Author: michael-simons

src/main/asciidoc/appendix/conversions.adoc

@@ -210,3 +210,13 @@ and an optional `Neo4jPersistentPropertyConverterFactory` to construct the forme
 With an implementation of `Neo4jPersistentPropertyConverter` all specific conversions for a given type can be addressed.
 
 We provide `@DateLong` and `@DateString` as meta-annotated annotations for backward compatibility with Neo4j-OGM schemes not using native types.
+
+[[composite-properties]]
+==== Composite properties
+
+With `@CompositeProperty`, attributes of type `Map<String, Object>` or Map<? extends Enum, Object>` can be stored as composite properties.
+All entries inside the map will be added as properties to the node or relationship containing the property.
+Either with a configured prefix or prefixed with the name of the property.
+While we only offer that feature for maps out of the box, you can `Neo4jPersistentPropertyToMapConverter` and configure it
+as the converter to use on `@CompositeProperty`. A `Neo4jPersistentPropertyToMapConverter` needs to know how a given type can
+be decomposed to and composed back from a map.

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

@@ -22,8 +22,19 @@ If you do not use this annotation, your application takes a slight performance h
 * `@Id`: Applied at the field level to mark the field used for identity purpose.
 * `@GeneratedValue`: Applied at the field level together with `@Id` to specify how unique identifiers should be generated.
 * `@Property`: Applied at the field level to modify the mapping from attributes to properties.
+* `@CompositeProperty`: Applied at the field level on attributes of type Map that shall be read back as a composite. See <<composite-properties>>.
 * `@Relationship`: Applied at the field level to specify the details of a relationship.
 * `@DynamicLabels`: Applied at the field level to specify the source of dynamic labels.
+* `@RelationshipProperties`: Applied at the class level to indicate this class as the target for properties of a relationship.
+* `@TargetNode`: Applied on a field of a class annotated with `@RelationshipProperties` to mark the target of that relationship from the perspective of the other end.
+
+The following annotations are used to specify conversions and ensure backwards compatibility with OGM.
+
+* `@DateLong`
+* `@DateString`
+* `@ConvertWith`
+
+See <<conversions>> for more information on that.
 
 ==== From Spring Data commons
 

src/main/java/org/springframework/data/neo4j/core/mapping/Neo4jConversionService.java renamed to src/main/java/org/springframework/data/neo4j/core/convert/Neo4jConversionService.java

@@ -13,14 +13,13 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.springframework.data.neo4j.core.mapping;
+package org.springframework.data.neo4j.core.convert;
 
 import java.util.function.Function;
 
 import org.apiguardian.api.API;
 import org.neo4j.driver.Value;
 import org.springframework.dao.TypeMismatchDataAccessException;
-import org.springframework.data.neo4j.core.convert.Neo4jSimpleTypes;
 import org.springframework.data.util.TypeInformation;
 import org.springframework.lang.Nullable;
 
@@ -32,7 +31,7 @@
  * @soundtrack Die Ärzte - Die Nacht der Dämonen
  * @since 6.0
  */
-@API(status = API.Status.INTERNAL, since = "6.0")
+@API(status = API.Status.STABLE, since = "6.0")
 public interface Neo4jConversionService {
 
 	/**

src/main/java/org/springframework/data/neo4j/core/convert/Neo4jPersistentPropertyConverterFactory.java

@@ -21,8 +21,10 @@
  * This interface needs to be implemented to provide custom configuration for a {@link Neo4jPersistentPropertyConverter}. Use cases may
  * be specific date formats or the like. The build method will receive the whole property. It is safe to assume that at
  * least  the {@link ConvertWith @ConvertWith} annotation is present on the property, either directly or meta-annotated.
- * <p>Classes implementing this interface should have a default constructor. In a normal Spring setup (not CDI), they
- * might declare autowired constructor parameters, too.
+ *
+ * <p>Classes implementing this interface should have a default constructor. In case they provide a constructor asking for
+ * an instance of {@link Neo4jConversionService}, such service is provided. This allows for conversions delegating part
+ * of the conversion.
  *
  * @author Michael J. Simons
  * @soundtrack Antilopen Gang - Abwasser

src/main/java/org/springframework/data/neo4j/core/convert/Neo4jPersistentPropertyToMapConverter.java

@@ -0,0 +1,57 @@
+/*
+ * Copyright 2011-2020 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.convert;
+
+import java.util.Map;
+
+import org.apiguardian.api.API;
+import org.neo4j.driver.Value;
+
+/**
+ * You need to provide an implementation of this interface in case you want to store a property of an entity as separate
+ * properties on a node. The entity needs to be decomposed into a map and composed from a map for that purpose.
+ *
+ * <p>The calling mechanism will take care of adding and removing configured prefixes and transforming keys and values into
+ * something that Neo4j can understand.
+ *
+ * @param <K> The type of the keys (Only Strings and Enums are supported).
+ * @param <P> The type of the property.
+ * @author Michael J. Simons
+ * @soundtrack Metallica - Helping Hands… Live & Acoustic At The Masonic
+ * @since 6.0
+ */
+@API(status = API.Status.STABLE, since = "6.0")
+public interface Neo4jPersistentPropertyToMapConverter<K, P> {
+
+	/**
+	 * Decomposes an object into a map. A conversion service is provided in case delegation is needed.
+	 *
+	 * @param property               The source property
+	 * @param neo4jConversionService The conversion service to delegate to if necessary
+	 * @return The decomposed object.
+	 */
+	Map<K, Value> decompose(P property, Neo4jConversionService neo4jConversionService);
+
+	/**
+	 * Composes the object back from the map. The map contains the raw driver values, as SDN cannot know how you want to
+	 * handle them. Therefore, the conversion service to convert driver values is provided.
+	 *
+	 * @param source                 The source map
+	 * @param neo4jConversionService The conversion service in case you want to delegate the work for some values in the map
+	 * @return The composed object.
+	 */
+	P compose(Map<K, Value> source, Neo4jConversionService neo4jConversionService);
+}

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

@@ -41,6 +41,7 @@ public final class Constants {
 	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__";
+	public static final String NAME_OF_ALL_PROPERTIES = "__allProperties__";
 
 	public static final String FROM_ID_PARAMETER_NAME = "fromId";
 

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

@@ -434,14 +434,22 @@ private List<Object> projectNodeProperties(NodeDescription<?> nodeDescription, S
 
 		List<Object> nodePropertiesProjection = new ArrayList<>();
 		Node node = anyNode(nodeName);
-		for (GraphPropertyDescription property : nodeDescription.getGraphPropertiesInHierarchy()) {
-			if (!includeField.test(property.getFieldName())) {
+		boolean hasCompositeProperties = false;
+		for (GraphPropertyDescription graphProperty : nodeDescription.getGraphPropertiesInHierarchy()) {
+
+			Neo4jPersistentProperty property = (Neo4jPersistentProperty) graphProperty;
+			hasCompositeProperties = hasCompositeProperties || property.isComposite();
+
+			if (!includeField.test(property.getFieldName()) || property.isDynamicLabels() || property.isComposite()) {
 				continue;
 			}
 
-			if (!((Neo4jPersistentProperty) property).isDynamicLabels()) {
-				nodePropertiesProjection.add(property.getPropertyName());
-			}
+			nodePropertiesProjection.add(graphProperty.getPropertyName());
+		}
+
+		if (hasCompositeProperties) {
+			nodePropertiesProjection.add(Constants.NAME_OF_ALL_PROPERTIES);
+			nodePropertiesProjection.add(node.project(Cypher.asterisk()));
 		}
 
 		nodePropertiesProjection.add(Constants.NAME_OF_LABELS);

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

@@ -27,6 +27,7 @@
 import org.springframework.core.convert.support.ConfigurableConversionService;
 import org.springframework.core.convert.support.DefaultConversionService;
 import org.springframework.dao.TypeMismatchDataAccessException;
+import org.springframework.data.neo4j.core.convert.Neo4jConversionService;
 import org.springframework.data.neo4j.core.convert.Neo4jConversions;
 import org.springframework.data.util.TypeInformation;
 import org.springframework.lang.Nullable;
@@ -69,6 +70,7 @@ public Object readValue(@Nullable Value source, TypeInformation<?> targetType,
 		BiFunction<Value, Class<?>, Object> conversion = conversionOverride == null ?
 				(v, t) -> conversionService.convert(v, t) :
 				(v, t) -> conversionOverride.apply(v);
+
 		return readValueImpl(source, targetType, conversion);
 	}
 

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

@@ -50,6 +50,7 @@
 import org.springframework.data.mapping.PropertyHandler;
 import org.springframework.data.mapping.model.EntityInstantiators;
 import org.springframework.data.mapping.model.ParameterValueProvider;
+import org.springframework.data.neo4j.core.convert.Neo4jConversionService;
 import org.springframework.data.neo4j.core.schema.TargetNode;
 import org.springframework.data.util.TypeInformation;
 import org.springframework.lang.NonNull;
@@ -150,8 +151,12 @@ public void write(Object source, Map<String, Object> parameters) {
 				return;
 			}
 
-			final Object value = conversionService.writeValue(propertyAccessor.getProperty(p), p.getTypeInformation(), p.getOptionalWritingConverter());
-			properties.put(p.getPropertyName(), value);
+			final Value value = conversionService.writeValue(propertyAccessor.getProperty(p), p.getTypeInformation(), p.getOptionalWritingConverter());
+			if (p.isComposite()) {
+				value.keys().forEach(k -> properties.put(k, value.get(k)));
+			} else {
+				properties.put(p.getPropertyName(), value);
+			}
 		});
 
 		parameters.put(Constants.NAME_OF_PROPERTIES_PARAM, properties);
@@ -518,7 +523,6 @@ private Optional<Object> createInstanceOfRelationships(Neo4jPersistentProperty p
 				return Optional.ofNullable(value.isEmpty() ? null : value.get(0));
 			}
 		}
-
 	}
 
 	private MapAccessor extractNextNodeAndAppendPath(Node possibleValueNode, List<Path> allPaths) {
@@ -534,12 +538,30 @@ private static Value extractValueOf(Neo4jPersistentProperty property, MapAccesso
 		if (property.isInternalIdProperty()) {
 			return propertyContainer instanceof Node ? Values.value(((Node) propertyContainer).id())
 					: propertyContainer.get(Constants.NAME_OF_INTERNAL_ID);
+		} else if (property.isComposite()) {
+			String prefix = property.computePrefixWithDelimiter();
+
+			if (propertyContainer.containsKey(Constants.NAME_OF_ALL_PROPERTIES)) {
+				return extractCompositePropertyValues(propertyContainer.get(Constants.NAME_OF_ALL_PROPERTIES), prefix);
+			} else {
+				return extractCompositePropertyValues(propertyContainer, prefix);
+			}
 		} else {
 			String graphPropertyName = property.getPropertyName();
 			return propertyContainer.get(graphPropertyName);
 		}
 	}
 
+	private static Value extractCompositePropertyValues(MapAccessor propertyContainer, String prefix) {
+		Map<String, Value>  hlp = new HashMap<>(propertyContainer.size());
+		propertyContainer.keys().forEach(k -> {
+			if (k.startsWith(prefix)) {
+				hlp.put(k, propertyContainer.get(k));
+			}
+		});
+		return Values.value(hlp);
+	}
+
 	static class KnownObjects {
 
 		private final ReentrantReadWriteLock lock = new ReentrantReadWriteLock();

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

@@ -27,6 +27,7 @@
 import org.springframework.data.mapping.model.Property;
 import org.springframework.data.mapping.model.SimpleTypeHolder;
 import org.springframework.data.neo4j.core.convert.Neo4jPersistentPropertyConverter;
+import org.springframework.data.neo4j.core.schema.CompositeProperty;
 import org.springframework.data.neo4j.core.schema.Relationship;
 import org.springframework.data.neo4j.core.schema.RelationshipProperties;
 import org.springframework.data.neo4j.core.schema.TargetNode;
@@ -71,7 +72,7 @@ final class DefaultNeo4jPersistentProperty extends AnnotationBasedPersistentProp
 
 			Class<?> targetType = getActualType();
 			return !(simpleTypeHolder.isSimpleType(targetType) || this.mappingContext.hasCustomWriteTarget(targetType)
-					|| isAnnotationPresent(TargetNode.class));
+					|| isAnnotationPresent(TargetNode.class) || isComposite());
 		});
 
 		this.customConversion = Lazy.of(() -> {
@@ -182,7 +183,7 @@ public boolean isAssociation() {
 
 	@Override
 	public boolean isEntity() {
-		return super.isEntity() && isAssociation() || (super.isEntity() && isEntityInRelationshipWithProperties());
+		return super.isEntity() && isAssociation() || (super.isEntity() && isEntityInRelationshipWithProperties() && !isComposite());
 	}
 
 	private static Function<Object, Value> nullSafeWrite(Function<Object, Value> delegate) {
@@ -260,6 +261,12 @@ public boolean isRelationship() {
 		return isAssociation();
 	}
 
+	@Override
+	public boolean isComposite() {
+
+		return isAnnotationPresent(CompositeProperty.class);
+	}
+
 	static String deriveRelationshipType(String name) {
 
 		Assert.hasText(name, "The name to derive the type from is required.");