From 1a050d9dd15688b075aed443b50fc2a67a06adc6 Mon Sep 17 00:00:00 2001 From: David Montag Date: Thu, 7 Apr 2011 20:56:14 -0700 Subject: [PATCH] Edited relationships reference chapter. --- .../programming-model/node-entities.xml | 2 +- .../programming-model/relationships.xml | 223 ++++++++++-------- 2 files changed, 126 insertions(+), 99 deletions(-) diff --git a/src/docbkx/reference/programming-model/node-entities.xml b/src/docbkx/reference/programming-model/node-entities.xml index bf4d09ad3..538254fd3 100644 --- a/src/docbkx/reference/programming-model/node-entities.xml +++ b/src/docbkx/reference/programming-model/node-entities.xml @@ -1,7 +1,7 @@
- Using annotations to define POJO Node Entities + Annotations define POJO node entities Entities are declared using the @NodeEntity annotation. Relationship entities use the @RelationshipEntity annotation. diff --git a/src/docbkx/reference/programming-model/relationships.xml b/src/docbkx/reference/programming-model/relationships.xml index 891397cfb..7a4f01331 100644 --- a/src/docbkx/reference/programming-model/relationships.xml +++ b/src/docbkx/reference/programming-model/relationships.xml @@ -1,74 +1,84 @@
- How to relate Node Entities using Relationships - As relationships are first level citizens in Neo4j, associations between Node-Entities are represented by - relationships. In general, relationships are categorized by a type and start and end-nodes (which also imply its direction). - They can have an arbitrary number of properties. Spring Data Graph has special support to represent Neo4j relationships - as Relationship Entities but this is not mandatory. + Relationships relate node entities + + Since relationships are first-class citizens in Neo4j, associations between node entities are represented + by relationships. In general, relationships are categorized by a type, and start and end nodes (which + imply the direction of the relationship). Relationships can have an arbitrary number of properties. + Spring Data Graph has special support to represent Neo4j relationships as entities too, but it is often + not needed.
- @RelatedTo: Connecting NodeEntities + @NodeEntity - Every attribute of a Node Entity that refers to one or more Node Entity represents relationships and - is handled by the field-aspects to be reflected in the graph. + Any class annotated with @NodeEntity will be backed by a node in the graph. Its fields will, if their + types are supported, be persisted as properties to the node for each entity. + +
+
+ @RelatedTo: Connecting node entities + + Every field of a node entity that references one or more other node entities is backed by relationships + in the graph. These relationships are managed by Spring Data Graph automatically. - Those can either be single relationships (1:1) or multiple relationships (1:N). - In most cases single relationships to other node entities don't have to be annotated, as Spring Data Graph - can extract all necessary information - from the field using reflection. In the case of multiple relationships, the elementClass - parameter of @RelatedTo must be specified because of type erasure. The direction - (default OUTGOING) and type (inferred from field name) parameters of the annotation are - optional. + The simplest kind of relationship is a single field pointing to another node entity (1:1). + In this case, the field does not have to be annotated at all, although the annotation may be + used to control the direction and type of the relationship. When setting the field, a + relationship is created. If the field is set to null, the relationship is removed. - - Single Relationships to other node entities are created when setting the field (deleting previously set - relationships) and deleted when setting it to null. - - - References to a set of Node Entities are declared as fields with a Set<T> type, where T - is a concrete Node-Entity. @RelatedTo is used again to provide information about type-name, elementClass and - direction. - It is not necessary to initialize the set as it is managed by Spring Data Graph, representing the relationships - from (to) this entity with the given type. Adding and removing from the set is reflected on the graph. - - - Spring Data Graph also ensures that there is only one relationship of the given type between two - given entities. - - - By setting direction to BOTH, relationships are created in the outgoing direction, but when the 1:N field - is read, it will include relationships in both directions. A cardinality of M:N is not necessary because - relationships can be navigated in both directions. - - - Node Entity with Relationships - + Single relationship field + movies; + private Actor mostPaidActor; } ]]> - + + - Other means of handling relationships are the introduced entity.getRelationshipTo(target,type) and - entity.relateTo(target,type) methods that are available on each NodeEntity. Those methods create - and return Neo4j relationships. It is possible to remove relationships manually using - entity.removeRelationshipTo(target,type). For creating and accessing relationship-entities, - their equivalents are available. + It is also possible to have fields that reference a set of node entities (1:N). These fields come in + two forms, modifiable or read-only. Modifiable fields are of the type java.util.Set<T>, + and read-only fields are java.lang.Iterable<T>, where T is a @NodeEntity-annotated + class. The Java implementation of generics uses type erasure, meaning that the type parameters are + typically not available at runtime. Therefore, the elementClass attribute must be + specified on the annotation, which must always be present for 1:N fields. + + + Node entity with relationships + mostPaidIn; + + @RelatedTo(type = "ACTS_IN", elementClass = Movie.class) + private Set movies; +} +]]> + + + Fields referencing other entities should not be manually initialized, as they are managed by + Spring Data Graph under the hood. 1:N fields can be accessed immediately, and Spring Data Graph + will provide a java.util.Set representing the relationships. If the returned set is modified, + the changes are reflected in the graph. Spring Data Graph also ensures that there is only one + relationship of a given type between any two given entities. + + + By setting direction to BOTH, relationships are created in the outgoing direction, but when the + 1:N field is read, it will include relationships in both directions. A cardinality of M:N is + not necessary because relationships can be navigated in both directions. + + + The relationships can also be accessed by using the aspect-introduced methods + entity.getRelationshipTo(target, type) and + entity.relateTo(target, type) available on each NodeEntity. + These methods find and create Neo4j relationships. It is also possible to manually remove + relationships by using entity.removeRelationshipTo(target, type). + Using these methods is rarely necessary though.
@@ -76,54 +86,71 @@ private Set movies; @RelationshipEntity: Rich relationships To access the full data model of graph relationships, POJOs can also be annotated with - @RelationshipEntity. Relationship entities can not be instantiated directly but are rather accessed via - node entities, either by @RelatedToVia fields or by the introduced - entity.relateTo(target,relationshipClass,type) and - entity.getRelationshipTo(target,relationshipClass,type) methods - (). - - Relationship entities may contain fields that are mapped to simple properties and two special fields that are - annotated with @StartNode and @EndNode which point to the start and end node entities respectively. These - fields are treated as read only fields. + @RelationshipEntity, making them relationship entities. Just as node entities represent + nodes in the graph, relationship entities represent relationships. As described above, + fields annotated with @RelatedTo provide a way to link node entities together + via relationships, but it provides no way of accessing the relationships themselves. - - Relationship Entity - - -
- -
- @RelatedToVia: Connecting Node Entitites via Relationship Entities - To provide easy programmatic access to the richer relationship entities of the data model, a different - annotation @RelatedToVia can be declared on fields of Iterables of the relationship entity type. - These Iterables then provide read only access to instances of the entity that backs the relationship of this - relationship type. Those instances are initialized with the properties of the relationship and the start - and end node. + Relationship entities cannot be instantiated directly but are rather created via + node entities, either by @RelatedToVia-annotated fields + (see ), + or by the introduced + entity.relateTo(target, relationshipClass, type) and + entity.getRelationshipTo(target, relationshipClass, type) methods + (see ). - - Using Relationship Entities and @RelatedToVia - + Fields in relationship entities are, similarly to node entities, persisted as properties on + the relationship. For accessing the two endpoints of the relationship, two special annotations + are available: @StartNode and @EndNode. A field annotated with + one of these annotations will provide read-only access to the corresponding endpoint, depending + on the chosen annotation. + + + Relationship entity + roles; - -public Role playedIn(Movie movie, String title) { - Role role=relateTo(movie,Role.class,"ACTS_IN"); - role.setTitle(title); - return role; + public Role playedIn(Movie movie, String title) { + return relatedTo(movie, Role.class, "ACTS_IN"); + } } + +@RelationshipEntity +public class Role { + String title; + + @StartNode private Actor actor; + @EndNode private Movie movie; +} + ]]> + + +
+
+ @RelatedToVia: Accessing relationship entities + + To provide easy programmatic access to the richer relationship entities of the data model, + the annotation @RelatedToVia can be added on fields of type + java.lang.Iterable<T>, where T is a @RelationshipEntity-annotated + class. These fields provide read-only access to relationship entities. + + + Accessing relationship entities using @RelatedToVia + roles; + + public Role playedIn(Movie movie, String title) { + Role role = relateTo(movie, Role.class, "ACTS_IN"); + role.setTitle(title); + return role; + } } ]]> - +
\ No newline at end of file