diff --git a/src/docbkx/reference/programming-model/node-entities.xml b/src/docbkx/reference/programming-model/node-entities.xml new file mode 100644 index 000000000..bf4d09ad3 --- /dev/null +++ b/src/docbkx/reference/programming-model/node-entities.xml @@ -0,0 +1,99 @@ + + +
+ Using annotations to define POJO Node Entities + Entities are declared using the @NodeEntity annotation. + Relationship entities use the @RelationshipEntity annotation. + +
+ @NodeEntity: The basic building block + + The @NodeEntity annotation is used to declare a POJO entity to be backed by a node in the + graph store. Simple fields on the entity are mapped by default to properties of the node. Object + references to other NodeEntities (whether single or Collection) are mapped via relationships. If + the annotation parameter useShortNames is set to false, the properties and relationship + names used will be prepended with the class name of the entity. + + If the partial + parameter is set to true, this entity takes part in a cross-store setting /) + where only the specifically annotated parts of the entity not handled by JPA will be mapped to the graph store. + + Entity fields can be annotated with @GraphProperty, @RelatedTo, @RelatedToVia, @Indexed, @GraphId and + @GraphTraversal. + + + Simple Node Entity + + +
+
+ @GraphProperty: Optional Annotation for Property Fields + It is not necessary to annotate fields as they are persisted by default; all fields that contain primitive + values are persisted directly to the graph. All fields + convertible to String using the Spring conversion services will be stored as a string. + (Spring Data Graph adds a custom conversion factory that comes with converters for Enums and Dates). + Transient fields are not persisted. + This annotation is mainly used for cross-store persistence. + +
+ +
+ @Indexed: Making entities searchable by field value + The @Indexed annotation can be declared on fields that are intended to be indexed by the Neo4j + indexing facilities, triggered by value modification. + The resulting index can be used to later retrieve nodes or relationships that contain a certain property + value (for example a name). Often an index is used to establish the start node for a traversal. + Indexes are accessed by a Repository for a particular node or relationship entity, created via a + DirectGraphRepositoryFactory. + + + GraphDatabaseContext exposes the indexes for Nodes and Relationships via the getIndex method. + Index names default to the domain class + name, but can also be named (indexName attribute)individually to reflect domain concepts. + be named, for instance to keep separate domain concepts in separate indexes. + + + Numerical values are indexed as such by default, allowing for range queries. + Fulltext indexing is also possible by setting the fulltext attribute to true. For details see + the indexing section . + +
+ +
+ @GraphTraversal: fields providing direct access to traversal results + The @GraphTraversal annotation leverages the delegation infrastructure used by the Spring Data Graph + aspects. It provides dynamic fields which, when accessed, return an Iterable of NodeEntities that are + the result of a traversal starting at the current NodeEntity. The TraversalDescription used for this + is created by a TraversalDescriptionBuilder whose class is referred to by the traversalBuilder + attribute of the annotation. The class of the expected NodeEntities is provided with the + elementClass attribute. + + @GraphTraversal in a Node Entity + people; + +private static class PeopleTraversalBuilder implements FieldTraversalDescriptionBuilder { + @Override + public TraversalDescription build(NodeBacked start, Field field, String...params) { + return new TraversalDescriptionImpl() + .relationships(DynamicRelationshipType.withName(params[0])) + .filter(Traversal.returnAllButStartNode()); + } +} +} +]]> + + + +
+
\ No newline at end of file diff --git a/src/docbkx/reference/programming-model/relationships.xml b/src/docbkx/reference/programming-model/relationships.xml new file mode 100644 index 000000000..891397cfb --- /dev/null +++ b/src/docbkx/reference/programming-model/relationships.xml @@ -0,0 +1,129 @@ + + +
+ 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. + +
+ @RelatedTo: Connecting NodeEntities + + 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. + + + 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. + + + 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 + movies; +} +]]> + + + 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. + +
+ +
+ @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. + + + 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. + + + Using Relationship Entities and @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