diff --git a/src/docbkx/reference/neo4j-server.xml b/src/docbkx/reference/neo4j-server.xml index d51d96b61..850359877 100644 --- a/src/docbkx/reference/neo4j-server.xml +++ b/src/docbkx/reference/neo4j-server.xml @@ -86,7 +86,12 @@ public void foo( @Context WorldRepository repo ) { that Spring Data Graph is not transactional when running with a RestGraphDatabase. - + + Please also keep in mind that performing graph operations via the REST-API is about one order of + magnitude slower than location operations. Try to use the Neo4j-Query-Language or + server-side traversals whenever possible (RestTraversal) for retrieving large sets of data. + Future versions of Spring Data Graph will use the more performant batching as well as a binary protocol. + To set up your project to use the REST bindings, add this dependency to your pom.xml: diff --git a/src/docbkx/reference/preface.xml b/src/docbkx/reference/preface.xml index 67c09055a..188083350 100644 --- a/src/docbkx/reference/preface.xml +++ b/src/docbkx/reference/preface.xml @@ -9,10 +9,24 @@ the AspectJ aspects in the Spring Data Graph framework, mapping the POJO entities and their fields to nodes, relationships, and properties in the graph database. + + Spring Data Graph allows anytime to drop down to the Neo4j-API level to execute functionality with + the highest performance possible. For Integration of Neo4j and Grails/GORM please refer to the Neo4j + grails plugin. + To get started with a simple application, only the basic annotations (see ) and the additional aspect-introduced entity methods (see ) are required. Basic knowledge of graph stores is needed to access advanced functionality like traversals. + + + + As Spring Data Graph is based on AspectJ and uses some advanced features of that toolset, please + be aware of that. Please see the section on AspectJ () for + details if you run into any problems. + + + diff --git a/src/docbkx/reference/programming-model/aspectj.xml b/src/docbkx/reference/programming-model/aspectj.xml index 70324572a..0765890d4 100644 --- a/src/docbkx/reference/programming-model/aspectj.xml +++ b/src/docbkx/reference/programming-model/aspectj.xml @@ -1,6 +1,6 @@ -
+
AspectJ support Behind the scenes, Spring Data Graph leverages AspectJ @@ -34,11 +34,19 @@ include: introduction of methods to interfaces, declaration of additional interfaces for annotated classes, and generified introduced methods. + + IDE's not providing the full AJ support might mark parts of your code as errors. + You should rely on your build-system and test to verify the correctness of the code. You might also have + your Entities (or their interfaces) implement the NodeBacked and RelationshipBacked + interfaces directly to benefit from completion support and error checking. + Eclipse and STS support AspectJ via the AJDT plugin which can be installed from the update-site: http://download.eclipse.org/tools/ajdt/36/update/ - (or for the latest development snapshot of the plugin + (it might be necessary to use the latest development snapshot of the plugin http://download.eclipse.org/tools/ajdt/36/dev/update). + The current version that does not show incorrect errors is AspectJ 1.6.12.M1 (included in STS 2.7.0.M2), previous versions are reported + to mislead the user. The AspectJ support in IntelliJ IDEA lacks some of the features. JetBrains is working on improving diff --git a/src/docbkx/reference/programming-model/attachdetach.xml b/src/docbkx/reference/programming-model/attachdetach.xml index 945d93c58..4e4f7feee 100644 --- a/src/docbkx/reference/programming-model/attachdetach.xml +++ b/src/docbkx/reference/programming-model/attachdetach.xml @@ -81,6 +81,14 @@ movie.setTopActor(actor); this behavior is not dependent on any configured relationship direction on the annotations. It is a matter of Java references and is not related to the data model in the database. + + The persist operation (merge) stores all properties of the entity to the graph database + and puts the entity in attached mode. There is no need to update the reference to the Java + POJO as the underlying backing node handles the read-through transparently. If multiple + object instances that point to the same node are persisted, the ordering is not important + as long as they contain distinct changes. For concurrent changes a concurrent modification + exception is thrown (subject to be parametrizable in the future). + If the relationships form a cycle, then the entities will first all be assigned a node in the database, and then the relationships will be created. The cascading of persist() diff --git a/src/docbkx/reference/programming-model/node-entities.xml b/src/docbkx/reference/programming-model/node-entities.xml index 98ead57b0..e4eb93ace 100644 --- a/src/docbkx/reference/programming-model/node-entities.xml +++ b/src/docbkx/reference/programming-model/node-entities.xml @@ -15,6 +15,10 @@ useShortNames attribute overridden to false, the property and relationship names will have the class name of the entity prepended. + + @NodeEntity annotations are inherited from super-types and interfaces. It is not necessary + to annotate your domain objects at every inheritance level. + If the partial attribute is set to true, this entity takes part in a cross-store setting, where the entity lives in both the graph database and a JPA data source. See @@ -44,6 +48,10 @@ public class Movie { custom conversion factory that comes with converters for Enums and Dates. Transient fields are not persisted. + + Currently there is no support for handling arbitrary collections of primitive or convertable values. + Support for this will be added by the 1.1. release. + This annotation is typically used with cross-store persistence. When a node entity is configured as partial, then all fields that should be persisted to the graph must be explicitly annotated @@ -63,6 +71,30 @@ public class Movie {
+
+ @GraphQuery: fields as query result views + + The @GraphQuery annotation leverages the delegation infrastructure used by the + Spring Data Graph aspects. It provides dynamic fields which, when accessed, return the values + selected by the provided query language expression. The provided query must contain a placeholder + for the id of the current entity start n=(%d) match n-[:FRIEND]->friend return friend + As graph queries can return variable number of entities the annotation can be put onto fields + with a single value, an Iterable of a type or an Iterable of Map<String,Object>. + The class of the resulting node entities must right now provided with the elementClass attribute. + Additional parameters are added to the query with Java's String.format substitution. + + + @GraphQuery from a node entity + (friend) return friend", + elementClass = Person.class, params = "FRIEND") + private Iterable friends; +} +]]> + + +
@GraphTraversal: fields as traversal result views diff --git a/src/docbkx/reference/programming-model/relationships.xml b/src/docbkx/reference/programming-model/relationships.xml index 5e976aba4..bd5d36fbb 100644 --- a/src/docbkx/reference/programming-model/relationships.xml +++ b/src/docbkx/reference/programming-model/relationships.xml @@ -9,6 +9,11 @@ Spring Data Graph has special support to represent Neo4j relationships as entities too, but it is often not needed. + + + As of Neo4j 1.4.M03, circular references are allowed. Spring Data Graph reflects this accordingly. + +
@RelatedTo: Connecting node entities @@ -69,7 +74,12 @@ public class Actor { - By setting direction to BOTH, relationships are created in the outgoing direction, but when the + When you use an Interface as target type for the Set and/or as elementClass + please make sure that it implements NodeBacked either by extending that Super-Interface manually + or by annotating the Interface with @NodeEntity too. + + + 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. @@ -79,8 +89,15 @@ public class Actor { 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. + Using these methods is significantly faster than adding/removing from the collection of + relationships as it doesn't have to re-synchronize a whole set of relationships with the graph. + + + Other collection types than Set are not supported so far, also currently NO + Map<RelationshipType,Set<NodeBacked>>. + +
diff --git a/src/docbkx/reference/setup.xml b/src/docbkx/reference/setup.xml index f09ad2665..36c51cb06 100644 --- a/src/docbkx/reference/setup.xml +++ b/src/docbkx/reference/setup.xml @@ -10,8 +10,65 @@ - + + Spring Data Graph projects can be built using maven, we also added means to build them with gradle and ant/ivy. +
+ Gradle configuration + + The necessary build plugin to build Spring Data Graph projects with gradle is available as part of the + SDG distribution or on github which makes the usage as easy as: + + + Gradle Build Configuration + + + + The actual springdatagraph.gradle is very simple just decorating the javac tasks with the iajc ant task. + +
+
+ Ant/Ivy configuration + + The supplied sample ant build configuration is mainly about resolving + the dependencies for Spring Data Graph and AspectJ using Ivy and integrating the iajc ant task in the build. + + + Ant/Ivy Build Configuration + + + + + + + + + + + + + +]]> + +
Maven configuration Spring Data Graph projects are easiest to build with Apache Maven. The main dependencies are: Spring