DATAGRAPH-1414 - Improve relationship documentation.

Author: meistermeier

src/main/asciidoc/appendix/query-creation.adoc

@@ -38,7 +38,7 @@ A save operation call in general issues multiple statements against the database
 . For the next defined relationship on the root entity start with 2. but replace _first_ with _next_.
 
 
-NOTE: As you can see SDN does its best to keep your graph model in sync with the Java world.
+WARNING: As you can see SDN does its best to keep your graph model in sync with the Java world.
 This is one of the reasons why we really advise you to not load, manipulate and save sub-graphs as this might cause relationships to get removed from the database.
 
 === Multiple entities
@@ -84,3 +84,10 @@ The above return part will then look like:
 
 The map projection and pattern comprehension used by SDN ensures that only the properties and relationships you have defined are getting queried.
 
+In cases where you have self-referencing nodes or creating schemas that potentially lead to cycles in the data that gets returned,
+SDN falls back to a path-based query creation that does a wildcard mapping on all available relationship types reachable from
+the initial domain entity.
+
+The return pattern looks similar to this:
+
+`RETURN n{..., __paths__: [p = (n)-[:HAS|KNOWS*]-() | p]}`

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

@@ -133,15 +133,15 @@ The `type` or the `value` attribute allow configuration of the relationship's ty
 The default direction in SDN is `Relationship.Direction#OUTGOING`.
 
 We support dynamic relationships.
-Dynamic relationships are represented as a `Map<String, AnnotatedDomainClass>`.
+Dynamic relationships are represented as a `Map<String, AnnotatedDomainClass>` or `Map<Enum, AnnotatedDomainClass>`.
 In such a case, the type of the relationship to the other domain class is given by the maps key and must not be configured through the `@Relationship`.
 
 ==== Map relationship properties
 
 Neo4j supports defining properties not only on nodes but also on relationships.
 To express those properties in the model SDN provides `@RelationshipProperties` to be applied on a simple Java class.
-
-In the entity class the relationship can be modelled as before but its type has to be a `Map` with the related node as the key and the relation property class as value.
+Within the properties class there have to be exactly one field marked as `@TargetNode` to define the entity the relationship points towards.
+Or, in an `INCOMING` relationship context, is coming from.
 
 A relationship property class and its usage may look like this:
 
@@ -157,15 +157,18 @@ include::../../../../src/test/java/org/springframework/data/neo4j/documentation/
 include::../../../../src/test/java/org/springframework/data/neo4j/documentation/domain/MovieEntity.java[tags=mapping.relationship.properties]
 ----
 
-==== Relationship query limit
+==== Relationship query remarks
 
 In general there is no limitation of relationships / hops for creating the queries.
 SDN parses the whole reachable graph from your modelled nodes.
-It is possible to have self-referencing entities and self-referencing concrete instances.
 
-If these entities or instances for a cycle we have a strict limit of *2* repetitions of walking the same path through the graph.
-E.g. You model a social network of `(:Person)-[:HAS_FRIEND]->(:Person)-[:HAS_FRIEND]...` you will only get the friends of the second degree.
-If you need a more specific mapping for your domain we advise you to use custom queries.
+This said, when there is the idea of mapping a relationship bidirectional, meaning you define the relationship on both ends of your entity,
+you might do not only get what you are expecting.
+
+Consider an example where a _movie_ has _actors_, and you want to fetch a certain movie with all its actors.
+This won't be problematical if the relationship from _movie_ to _actor_ were just unidirectional.
+In a bidirectional scenario SDN would fetch the particular _movie_, its _actors_ but also the other movies defined for this _actor_ per definition of the relationship.
+In the worst case, this will cascade to fetching the whole graph for a single entity.
 
 === A complete example
 

src/test/java/org/springframework/data/neo4j/documentation/domain/MovieEntity.java

@@ -43,9 +43,9 @@ public class MovieEntity {
 	@Property("tagline") // <.>
 	private final String description;
 
-	@Relationship(type = "ACTED_IN", direction = Direction.INCOMING) // <.>
 	// tag::mapping.relationship.properties[]
-	private Map<PersonEntity, Roles> actorsAndRoles = new HashMap<>();
+	@Relationship(type = "ACTED_IN", direction = Direction.INCOMING) // <.>
+	private List<Roles> actorsAndRoles;
 	// end::mapping.relationship.properties[]
 
 	@Relationship(type = "DIRECTED", direction = Direction.INCOMING) private List<PersonEntity> directors = new ArrayList<>();
@@ -66,7 +66,7 @@ public String getDescription() {
 		return description;
 	}
 
-	public Map<PersonEntity, Roles> getActorsAndRoles() {
+	public List<Roles> getActorsAndRoles() {
 		return actorsAndRoles;
 	}
 

src/test/java/org/springframework/data/neo4j/documentation/domain/Roles.java

@@ -18,6 +18,7 @@
 import java.util.List;
 
 import org.springframework.data.neo4j.core.schema.RelationshipProperties;
+import org.springframework.data.neo4j.core.schema.TargetNode;
 
 /**
  * @author Gerrit Meier
@@ -28,7 +29,11 @@ public class Roles {
 
 	private final List<String> roles;
 
-	public Roles(List<String> roles) {
+	@TargetNode
+	private final PersonEntity person;
+
+	public Roles(PersonEntity person, List<String> roles) {
+		this.person = person;
 		this.roles = roles;
 	}
 

src/test/java/org/springframework/data/neo4j/documentation/spring_boot/ReactiveTemplateExampleTest.java

@@ -59,8 +59,10 @@ void shouldSaveAndReadEntities(@Autowired ReactiveNeo4jTemplate neo4jTemplate) {
 				"A movie that follows the adventures of Herbie, Herbie's driver, "
 						+ "Jim Douglas (Dean Jones), and Jim's love interest, " + "Carole Bennett (Michele Lee)");
 
-		movie.getActorsAndRoles().put(new PersonEntity(1931, "Dean Jones"), new Roles(Collections.singletonList("Didi")));
-		movie.getActorsAndRoles().put(new PersonEntity(1942, "Michele Lee"), new Roles(Collections.singletonList("Michi")));
+		Roles role1 = new Roles(new PersonEntity(1931, "Dean Jones"), Collections.singletonList("Didi"));
+		Roles role2 = new Roles(new PersonEntity(1942, "Michele Lee"), Collections.singletonList("Michi"));
+		movie.getActorsAndRoles().add(role1);
+		movie.getActorsAndRoles().add(role2);
 
 		StepVerifier.create(neo4jTemplate.save(movie)).expectNextCount(1L).verifyComplete();
 

src/test/java/org/springframework/data/neo4j/documentation/spring_boot/TemplateExampleTest.java

@@ -46,8 +46,10 @@ void shouldSaveAndReadEntities(@Autowired Neo4jTemplate neo4jTemplate) {
 				"A movie that follows the adventures of Herbie, Herbie's driver, "
 						+ "Jim Douglas (Dean Jones), and Jim's love interest, " + "Carole Bennett (Michele Lee)");
 
-		movie.getActorsAndRoles().put(new PersonEntity(1931, "Dean Jones"), new Roles(Collections.singletonList("Didi")));
-		movie.getActorsAndRoles().put(new PersonEntity(1942, "Michele Lee"), new Roles(Collections.singletonList("Michi")));
+		Roles roles1 = new Roles(new PersonEntity(1931, "Dean Jones"), Collections.singletonList("Didi"));
+		Roles roles2 = new Roles(new PersonEntity(1942, "Michele Lee"), Collections.singletonList("Michi"));
+		movie.getActorsAndRoles().add(roles1);
+		movie.getActorsAndRoles().add(roles2);
 
 		neo4jTemplate.save(movie);