GH-2201 - Allow interfaces in domain model hierachies.

While technically possible, Spring Data Neo4j prevented a proper use of
interfaces in domain hierachies due to the fact that it checks whether a
primary label has been used already in a domain model. That check can be
triggered at different point in times: Either when initializing the
persistence context with a predefined set of entities or when an
interface based entity is refered from an implementation of itself.

This commit changes the following approaches:
* Interfaces won't contribute to the index of entities by primary label
* The explicit or implicit names of interfaces implemented by an entity
  will contribute to the list of additional labels. However, we don't
  traverse the graph of interfaces to the top
* When hydrating instances we must check whether the target is an
  interface. If so, we go through the list of all known persistent
  entities and look for one that can be assigned to the interface and
  which spots all the mapped labels

In addition we fixed some bugs when selecting the target entity type
when saving relationships. Also, `@Relationship` without a given
relationship type name will work now without messing up the type name.

This allows for the following scenarios:

1. Creating an API module being free of Spring or Neo4j based
   annotations. That API module can than be implemented by different
   Spring Data stores that support interfaces in their hierachies like
   we do now then.
2. Putting an explicit `@Node` annotation onto an interface so that the
   implementation can be arbitrary named (Which is probably a rarer use
   case).
3. Using polymorpmic relationships: If an interface has multiple
   implementations in the same project, the interface and it's
   implementations can both be annotated. The annotation on the
   interface is going to be the primary label and the labels on the
   annotated implementations are the selectors for picking out the class
   to hydrate during loading.

This closes #2201.

Author: michael-simons

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

@@ -74,12 +74,57 @@ The primary label should always be the most concrete label that reflects your do
 For each instance of an annotated class that is written through a repository or through the Neo4j template, one node in the graph with at least the primary label will be written.
 Vice versa, all nodes with the primary label will be mapped to the instances of the annotated class.
 
+==== A note on class hierarchies
+
 The `@Node` annotation is not inherited from super-types and interfaces.
 You can however annotate your domain classes individually at every inheritance level.
 This allows polymorphic queries: You can pass in base or intermediate classes and retrieve the correct, concrete instance for your nodes.
 This is only supported for abstract bases annotated with `@Node`.
 The labels defined on such a class will be used as additional labels together with the labels of the concrete implementations.
 
+We also support interfaces in domain-class-hierarchies for some scenarios:
+
+.Domain model in a separate module, same primary label like the interface name
+[source,java,indent=0,tabsize=4]
+----
+include::../../../../src/test/java/org/springframework/data/neo4j/integration/shared/common/Inheritance.java[tag=interface1]
+----
+<.> Just the plain interface name, as you would name your domain
+<.> As we need to synchronize the primary labels, we put `@Node` on the implementing class, which
+    is probably in another module. Note that the value is exactly the same as the name of the interface
+    implemented. Renaming is not possible.
+
+Using a different primary label instead of the interface name is possible, too:
+
+.Different primary label
+[source,java,indent=0,tabsize=4]
+----
+include::../../../../src/test/java/org/springframework/data/neo4j/integration/shared/common/Inheritance.java[tag=interface2]
+----
+<.> Put the `@Node` annotation on the interface
+
+It's also possible to use different implementations of an interface and have a polymorph domain model.
+When doing so, at least two labels are required: A label determining the interface and one determining the concrete class:
+
+.Multiple implementations
+[source,java,indent=0,tabsize=4]
+----
+include::../../../../src/test/java/org/springframework/data/neo4j/integration/shared/common/Inheritance.java[tag=interface3]
+----
+<.> Explicitly specifying the label that identifies the interface is required in this scenario
+<.> Which applies for the first…
+<.> and second implementation as well
+<.> This is a client or parent model, using `SomeInterface3` transparently for two relationships
+<.> No concrete type is specified
+
+The data structure needed is shown in the following test. The same would be written by the OGM:
+
+.Data structure needed for using multiple, different interface implementations
+[source,java,indent=0,tabsize=4]
+----
+include::../../../../src/test/java/org/springframework/data/neo4j/integration/imperative/InheritanceMappingIT.java[tag=interface3]
+----
+
 [[mapping.annotations.node.dynamic.labels]]
 ==== Dynamic or "runtime" managed labels
 

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

@@ -678,8 +678,7 @@ private <T> T processNestedRelations(Neo4jPersistentEntity<?> sourceEntity, Pers
 				if (stateMachine.hasProcessedValue(relatedValueToStore)) {
 					relatedInternalId = queryRelatedNode(newRelatedObject, targetEntity);
 				} else {
-					relatedInternalId = saveRelatedNode(newRelatedObject, relationshipContext.getAssociationTargetType(),
-							targetEntity);
+					relatedInternalId = saveRelatedNode(newRelatedObject, targetEntity);
 				}
 				stateMachine.markValueAsProcessed(relatedValueToStore);
 
@@ -750,9 +749,10 @@ private <Y> Long queryRelatedNode(Object entity, Neo4jPersistentEntity<?> target
 				.fetchAs(Long.class).one().get();
 	}
 
-	private <Y> Long saveRelatedNode(Object entity, Class<Y> entityType, NodeDescription targetNodeDescription) {
+	private <Y> Long saveRelatedNode(Object entity, NodeDescription targetNodeDescription) {
 
 		DynamicLabels dynamicLabels = determineDynamicLabels(entity, (Neo4jPersistentEntity) targetNodeDescription);
+		Class<Y> entityType = (Class<Y>) ((Neo4jPersistentEntity<?>) targetNodeDescription).getType();
 		Optional<Long> optionalSavedNodeId = neo4jClient
 				.query(() -> renderer.render(cypherGenerator.prepareSaveOf(targetNodeDescription, dynamicLabels)))
 				.bind((Y) entity).with(neo4jMappingContext.getRequiredBinderFunctionFor(entityType))

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

@@ -778,7 +778,7 @@ private <T> Mono<T> processNestedRelations(Neo4jPersistentEntity<?> sourceEntity
 							if (stateMachine.hasProcessedValue(relatedValueToStore)) {
 								queryOrSave = queryRelatedNode(newRelatedObject, targetEntity);
 							} else {
-								queryOrSave = saveRelatedNode(newRelatedObject, relationshipContext.getAssociationTargetType(), targetEntity);
+								queryOrSave = saveRelatedNode(newRelatedObject, targetEntity);
 							}
 							stateMachine.markValueAsProcessed(relatedValueToStore);
 							return queryOrSave.flatMap(relatedInternalId -> {
@@ -869,12 +869,12 @@ private <Y> Mono<Long> queryRelatedNode(Object entity, Neo4jPersistentEntity<?>
 				.fetchAs(Long.class).one();
 	}
 
-	private <Y> Mono<Long> saveRelatedNode(Object relatedNode, Class<Y> entityType,
-										   Neo4jPersistentEntity<?> targetNodeDescription) {
+	private <Y> Mono<Long> saveRelatedNode(Object relatedNode, Neo4jPersistentEntity<?> targetNodeDescription) {
 
 		return determineDynamicLabels((Y) relatedNode, targetNodeDescription)
 				.flatMap(t -> {
 					Y entity = t.getT1();
+					Class<Y> entityType = (Class<Y>) ((Neo4jPersistentEntity<?>) targetNodeDescription).getType();
 					DynamicLabels dynamicLabels = t.getT2();
 
 					return neo4jClient

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

@@ -245,7 +245,7 @@ private <ET> ET map(MapAccessor queryResult, MapAccessor allValues, Neo4jPersist
 		Supplier<Object> mappedObjectSupplier = () -> {
 
 			List<String> allLabels = getLabels(queryResult, nodeDescription);
-			NodeDescriptionAndLabels nodeDescriptionAndLabels = NodeDescriptionStore
+			NodeDescriptionAndLabels nodeDescriptionAndLabels = nodeDescriptionStore
 					.deriveConcreteNodeDescription(nodeDescription, allLabels);
 			Neo4jPersistentEntity<ET> concreteNodeDescription = (Neo4jPersistentEntity<ET>) nodeDescriptionAndLabels
 					.getNodeDescription();
@@ -306,7 +306,7 @@ private Neo4jPersistentEntity<?> getMostConcreteTargetNodeDescription(
 			Neo4jPersistentEntity<?> genericTargetNodeDescription, MapAccessor possibleValueNode) {
 
 		List<String> allLabels = getLabels(possibleValueNode, null);
-		NodeDescriptionAndLabels nodeDescriptionAndLabels = NodeDescriptionStore
+		NodeDescriptionAndLabels nodeDescriptionAndLabels = nodeDescriptionStore
 				.deriveConcreteNodeDescription(genericTargetNodeDescription, allLabels);
 		return (Neo4jPersistentEntity<?>) nodeDescriptionAndLabels
 				.getNodeDescription();

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

@@ -32,6 +32,7 @@
 import java.util.stream.Stream;
 
 import org.apache.commons.logging.LogFactory;
+import org.springframework.core.annotation.AnnotatedElementUtils;
 import org.springframework.core.log.LogAccessor;
 import org.springframework.data.annotation.Persistent;
 import org.springframework.data.mapping.Association;
@@ -90,7 +91,7 @@ final class DefaultNeo4jPersistentEntity<T> extends BasicPersistentEntity<T, Neo
 	DefaultNeo4jPersistentEntity(TypeInformation<T> information) {
 		super(information);
 
-		this.primaryLabel = computePrimaryLabel();
+		this.primaryLabel = computePrimaryLabel(this.getType());
 		this.additionalLabels = Lazy.of(this::computeAdditionalLabels);
 		this.graphProperties = Lazy.of(this::computeGraphProperties);
 		this.dynamicLabelsProperty = Lazy.of(() -> getGraphProperties().stream().map(Neo4jPersistentProperty.class::cast)
@@ -206,6 +207,10 @@ public void verify() {
 
 	private void verifyIdDescription() {
 
+		if (this.describesInterface()) {
+			return;
+		}
+
 		if (this.getIdDescription() == null
 			&& (this.isAnnotationPresent(Node.class) || this.isAnnotationPresent(Persistent.class))) {
 
@@ -298,13 +303,15 @@ private void verifyDynamicLabels() {
 	 * 3. If only {@link Node#labels()} property is set, use the first one as the primary label 4. If the
 	 * {@link Node#primaryLabel()} property is set, use this as the primary label
 	 *
+	 * @param type the type of the underlying class
 	 * @return computed primary label
 	 */
-	private String computePrimaryLabel() {
+	@Nullable
+	static String computePrimaryLabel(Class<?> type) {
 
-		Node nodeAnnotation = this.findAnnotation(Node.class);
-		if (nodeAnnotation == null || hasEmptyLabelInformation(nodeAnnotation)) {
-			return this.getType().getSimpleName();
+		Node nodeAnnotation = AnnotatedElementUtils.findMergedAnnotation(type, Node.class);
+		if ((nodeAnnotation == null || hasEmptyLabelInformation(nodeAnnotation))) {
+			return type.getSimpleName();
 		} else if (StringUtils.hasText(nodeAnnotation.primaryLabel())) {
 			return nodeAnnotation.primaryLabel();
 		} else {
@@ -320,28 +327,52 @@ private String computePrimaryLabel() {
 	private List<String> computeAdditionalLabels() {
 
 		return Stream.concat(computeOwnAdditionalLabels().stream(), computeParentLabels().stream())
+				.distinct() // In case the interfaces added a duplicate of the primary label.
+				.filter(v -> !getPrimaryLabel().equals(v))
 				.collect(Collectors.toList());
 	}
 
 	/**
 	 * The additional labels will get computed and returned by following rules:<br>
 	 * 1. If there is no {@link Node} annotation, empty {@code String} array.<br>
 	 * 2. If there is an annotation but it has no properties set, empty {@code String} array.<br>
-	 * 3. If only {@link Node#labels()} property is set, use the all but the first one as the additional labels.<br>
-	 * 3. If the {@link Node#primaryLabel()} property is set, use the all but the first one as the additional labels.<br>
+	 * 3a. If only {@link Node#labels()} property is set, use the all but the first one as the additional labels.<br>
+	 * 3b. If the {@link Node#primaryLabel()} property is set, use the all but the first one as the additional labels.<br>
+	 * 4. If the class has any interfaces that are explicitly annotated with {@link Node}, we take all values from them.
 	 *
 	 * @return computed additional labels of the concrete class
 	 */
 	@NonNull
 	private List<String> computeOwnAdditionalLabels() {
+		List<String> result = new ArrayList<>();
+
 		Node nodeAnnotation = this.findAnnotation(Node.class);
-		if (nodeAnnotation == null || hasEmptyLabelInformation(nodeAnnotation)) {
-			return Collections.emptyList();
-		} else if (StringUtils.hasText(nodeAnnotation.primaryLabel())) {
-			return Arrays.asList(nodeAnnotation.labels());
-		} else {
-			return Arrays.asList(Arrays.copyOfRange(nodeAnnotation.labels(), 1, nodeAnnotation.labels().length));
+		if (!(nodeAnnotation == null || hasEmptyLabelInformation(nodeAnnotation))) {
+			if (StringUtils.hasText(nodeAnnotation.primaryLabel())) {
+				result.addAll(Arrays.asList(nodeAnnotation.labels()));
+			} else {
+				result.addAll(Arrays.asList(Arrays.copyOfRange(nodeAnnotation.labels(), 1, nodeAnnotation.labels().length)));
+			}
+		}
+
+		// Add everything we find on _direct_ interfaces
+		// We don't traverse interfaces of interfaces
+		for (Class<?> anInterface : this.getType().getInterfaces()) {
+			nodeAnnotation = AnnotatedElementUtils.findMergedAnnotation(anInterface, Node.class);
+			if (nodeAnnotation == null) {
+				continue;
+			}
+			if (hasEmptyLabelInformation(nodeAnnotation)) {
+				result.add(anInterface.getSimpleName());
+			} else {
+				if (StringUtils.hasText(nodeAnnotation.primaryLabel())) {
+					result.add(nodeAnnotation.primaryLabel());
+				}
+				result.addAll(Arrays.asList(nodeAnnotation.labels()));
+			}
 		}
+
+		return Collections.unmodifiableList(result);
 	}
 
 	@NonNull
@@ -350,8 +381,7 @@ private List<String> computeParentLabels() {
 		Neo4jPersistentEntity<?> parentNodeDescriptionCalculated = (Neo4jPersistentEntity<?>) parentNodeDescription;
 
 		while (parentNodeDescriptionCalculated != null) {
-			if (parentNodeDescriptionCalculated.isAnnotationPresent(Node.class)
-					|| parentNodeDescriptionCalculated.isAnnotationPresent(Persistent.class)) {
+			if (isExplicitlyAnnotatedAsEntity(parentNodeDescriptionCalculated)) {
 
 				parentLabels.add(parentNodeDescriptionCalculated.getPrimaryLabel());
 				parentLabels.addAll(parentNodeDescriptionCalculated.getAdditionalLabels());
@@ -361,6 +391,20 @@ private List<String> computeParentLabels() {
 		return parentLabels;
 	}
 
+	/**
+	 * @param entity The entity to check for annotation
+	 * @return True if the type is explicitly annotated as entity and as such eligible to contribute to the list of labels
+	 * and required to be part of the label lookup.
+	 */
+	private static boolean isExplicitlyAnnotatedAsEntity(Neo4jPersistentEntity<?> entity) {
+		return entity.isAnnotationPresent(Node.class) || entity.isAnnotationPresent(Persistent.class);
+	}
+
+	@Override
+	public boolean describesInterface() {
+		return this.getTypeInformation().getRawTypeInformation().getType().isInterface();
+	}
+
 	private static boolean hasEmptyLabelInformation(Node nodeAnnotation) {
 		return nodeAnnotation.labels().length < 1 && !StringUtils.hasText(nodeAnnotation.primaryLabel());
 	}

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

@@ -39,6 +39,7 @@
 import org.springframework.lang.NonNull;
 import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
+import org.springframework.util.StringUtils;
 
 /**
  * @author Michael J. Simons
@@ -145,7 +146,7 @@ protected Association<Neo4jPersistentProperty> createAssociation() {
 		Relationship outgoingRelationship = this.findAnnotation(Relationship.class);
 
 		String type;
-		if (outgoingRelationship != null && outgoingRelationship.type() != null) {
+		if (outgoingRelationship != null && StringUtils.hasText(outgoingRelationship.type())) {
 			type = outgoingRelationship.type();
 		} else {
 			type = deriveRelationshipType(this.getName());