diff --git a/src/docbkx/reference/aspectj-details.xml b/src/docbkx/reference/aspectj-details.xml index 5338f986e..ccca1cab4 100644 --- a/src/docbkx/reference/aspectj-details.xml +++ b/src/docbkx/reference/aspectj-details.xml @@ -14,12 +14,12 @@ The AspectJ pointcut language can be intimidating, but a developer using Spring Data Neo4j will not have - to deal with that. Users don't have care about to hooking into a framework mechanism, or having to extend + to deal with that. Users don't have care about hooking into a framework mechanism, or having to extend a framework superclass. - AspectJ uses a declarative approach, defining concrete advice, which is just pieces of code that contain - the implementation of the concern. AspectJ advice can for instance be applied before, after, or instead + AspectJ uses a declarative approach, defining concrete "advice", which is just pieces of code that contain + the implementation of the "concern", as it is called. AspectJ advice can for instance be applied before, after, or instead of a method or constructor call. It can also be applied on variable and field access. This is declared using AspectJ's expressive pointcut language, able to express any place within a code structure or flow. AspectJ is also able to introduce new methods, fields, annotations, interfaces, and superclasses to diff --git a/src/docbkx/reference/neo4j-server.xml b/src/docbkx/reference/neo4j-server.xml index bcc89f010..4d966f8e9 100644 --- a/src/docbkx/reference/neo4j-server.xml +++ b/src/docbkx/reference/neo4j-server.xml @@ -20,7 +20,7 @@ The Neo4j Server has two built-in extension mechanisms. It is possible to extend existing URI endpoints like the graph database, nodes, or relationships, adding new URIs or methods to those. This is achieved by writing a server plugin. - This plugin type has some restrictions though. + This plugin type has some restrictions however. For complete freedom in the implementation, an @@ -55,7 +55,7 @@ ]]> - Now, your resources can require the spring-beans they need, annotated with @Context like this: + Now, your resources can require the Spring beans they need, annotated with @Context like this: Jersey resource 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 Cypher query language, + magnitude slower than local operations. Try to use the Neo4j Cypher query language, server-side traversals (RestTraversal) or Gremlin expressions whenever possible for retrieving large sets of data. Future versions of Spring Data Neo4j will use the more performant batching as well as a binary protocol. @@ -119,7 +119,7 @@ public void foo( @Context WorldRepository repo ) { The remote REST implementation works for both the Neo4jTemplate as well as the GraphEntities. For traversals - and cypher-graph-queries it is sensible to forward those to the remote and execute them there instead of + and Cypher graph queries it is sensible to forward those to the remote endpoint and execute them there instead of walking the graph over the wire. RestGraphDatabase already supports that by providing methods that forward to the remote instance. (e.g. queryEngineFor(), index() and createTraversalDescription()). Please use those methods when interacting with a remote server for optimal performance. diff --git a/src/docbkx/reference/neo4j.xml b/src/docbkx/reference/neo4j.xml index d509b5e53..ce0ec0e27 100644 --- a/src/docbkx/reference/neo4j.xml +++ b/src/docbkx/reference/neo4j.xml @@ -24,7 +24,7 @@ Neo4j is a NOSQL graph database. It is a fully transactional database (ACID) that stores data structured as graphs. A graph consists of nodes, connected by relationships. - Inspired by the structure of the human brain, it allows for high query performance on complex data, + Inspired by the structure of the human mind, it allows for high query performance on complex data, while remaining intuitive and simple for the developer. @@ -159,13 +159,13 @@ for (Node foundNode : nodeIndex.get("property","value")) { Neo4j provides a graph query language called "Cypher" which draws from many sources. It resembles SQL but with an iconic representation of patterns in the graph (concepts drawn from SPARQL). - Cypher was written in Scala to leverage the high expressiveness for lazy sequence operations of the language and the + The Cypher execution engine was written in Scala to leverage the high expressiveness for lazy sequence operations of the language and the parser combinator library. Cypher queries always begin with a start set of nodes. Those can be either expressed by their id's or by a index lookup expression. Those start-nodes are then related to other nodes in the - match clause. Start and match clause can introduce new identifiers for nodes and + match clause. Start and match clauses can introduce new identifiers for nodes and relationships. In the where clause additional filtering of the result set is applied by evaluating expressions. The return clause defines which part of the query result will be available. Aggregation also happens in the return clause by using aggregation functions on some of the values. @@ -173,7 +173,7 @@ for (Node foundNode : nodeIndex.get("property","value")) { restrict the result set to a certain window. - Cypher can be executed on an embedded graph db using ExecutionEngine and + Cypher can be executed on an embedded graph db using an ExecutionEngine and CypherParser. This is encapsulated in Spring Data Neo4j with CypherQueryEngine. The Neo4j-REST-Server comes with a Cypher-Plugin that is accessible remotely and is available in the Spring Data Neo4j REST-Binding. @@ -211,11 +211,11 @@ start user=node:User(login='micha') match user-[:FRIEND]-()-[r,:RATED]->movie Gremlin a Graph Traversal DSL Gremlin is an expressive Groovy DSL developed by Marko Rodriguez - as part of the tinkerpop stack. It builds on top of a pipe implementation + as part of the Tinkerpop stack. It builds on top of a pipe implementation (Blueprints Pipes) that uses connected operations to traverse a graph. Gremlin has a concise syntax but is - turing complete. + Turing complete. - Gremlin can be executed by including the tinkerpop and blueprints dependencies and then requesting a ScriptEngine + Gremlin can be executed by including the Tinkerpop and Blueprints dependencies and then requesting a ScriptEngine of type "gremlin" from the javax.Script* facilities. In Spring Data Neo4j this is encapsulated in GremlinQueryEngine. The Neo4j-REST-Server also comes with a Gremlin-Plugin that is accessible remotely and is available in the Spring Data Neo4j REST-Binding. diff --git a/src/docbkx/reference/preface.xml b/src/docbkx/reference/preface.xml index 5a2f3dfa3..1e1d14d0a 100644 --- a/src/docbkx/reference/preface.xml +++ b/src/docbkx/reference/preface.xml @@ -73,9 +73,9 @@ Spring Data Commons provides a very powerful repository infrastructure that is also leveraged in Spring Data Neo4j. - Those repositories consist only of a composition of interfaces that declare the available functionality in the - each repository. The implementation-details of commonly used persistence methods are handled by the library. - At least for typical CRUD, Index- and Query-operatoins that is very convenient. + Those repositories consist only of a composition of interfaces that declare the available functionality in + each repository. The implementation details of commonly used persistence methods are handled by the library. + At least for typical CRUD, index- and query-operations that is very convenient. The repositories are extensible by annotated, named or derived finder methods. For custom implementations of repository methods you are free to add your own code. (). @@ -86,25 +86,25 @@ Spring Data Neo4j also allows you to integrate with the powerful geospatial graph library Neo4j-Spatial that offers - full support for working with any kind of geo-data. Spring Data Neo4j repositories expose a set of those operations + full support for working with any kind of geo-data. Spring Data Neo4j repositories expose a couple of those operations via bounding-box and near-location searches. . Using computed fields that are dynamically backed by graph operations is a bit more involved. First you should know about traversals, Cypher queries and Gremlin expressions. - Those are explained in Neo4j-API. Then you can start using virtual, computed fields - to your entities . + Those are explained in the Neo4j-API. Then you can start using virtual, computed fields + in your entities . - If you like the Active-Record approach that uses persistence methods mixed into the domain classes, you would + If you like the ActiveRecord approach that uses persistence methods mixed into the domain classes, you will want to look at the description of the additional entity methods (see ) that are added to your - domain objects by Spring Data Neo4j Aspects. Those allow you to manage the entity lifecycles as + domain objects by Spring Data Neo4j Aspects. Those allow you to manage the entity lifecycle as well as to connect entities. Those methods also provide the means to execute the mentioned graph operations with your entity as a starting point. - Neo4j is an fully ACID, enterprise grade database, it uses Java transactions (and internally even a 2 phase commit protocol) to guarantee the + Neo4j is a fully ACID, enterprise grade database. It uses Java transactions, and internally a 2 phase commit protocol, to guarantee the safety of your data. The implications of that are described in the chapter around transactions. () @@ -116,14 +116,14 @@ () - For the simple mapping this is not neccessary as domain objects are detached by default and have to be explicitely + For the simple mapping this is not neccessary as domain objects are detached by default and have to be explicitly reattached to the graph to store the changes. Unlike Neo4j which is a schema free database, Spring Data Neo4j works on Java domain objects. So it needs to store the type information in the graph to be able to reconstruct the entities when just nodes are retrieved. To achieve that it employs type-representation-strategies which are described in a separate chapter. - () + (see ) Spring Data Neo4j offers basic support for bean property validation (JSR-303). Annotations from that JSR are recognized @@ -131,24 +131,24 @@ (see ) - Unfortunately the setup of Spring Data Neo4j advanced mapping mode is more involved than we'd like. That is partly due to the maven setup - and dependencies for AspectJ, which can be alleviated by using different build systems like gradle or ant/ivy. The Spring configuration + Unfortunately the setup of Spring Data Neo4j advanced mapping mode is more involved than we'd like. That is partly due to the Maven setup + and dependencies for AspectJ, which can be alleviated by using different build systems like Gradle or Ant/Ivy. The Spring configuration itself boils down to two lines of <spring-neo4j> namespace setup. (see ) - In a poliglot persistence context Spring Data Neo4j can also be used in a JPA environment to add graph features to your JPA entities. In the + In a polyglot persistence context Spring Data Neo4j can also be used in a JPA environment to add graph features to your JPA entities. In the the slightly different behavior and setup of a Graph-JPA interaction are described. - The provided samples, which are also publicly hosted on github are explained in + The provided samples, which are also publicly hosted on Github, are explained in . The performance implications of using Spring Data Neo4j are detailed in . - This chapter also discusses which usecases should not be handled with Spring Data Neo4j. + This chapter also discusses which use cases should not be handled with Spring Data Neo4j. - As AspectJ might not be well known to everyone, some of the core concepts of the Aspect oriented, + As AspectJ might not be well known to everyone, some of the core concepts of the aspect oriented, advanced mapping mode for Java are explained in . diff --git a/src/docbkx/reference/programming-model/aspectj.xml b/src/docbkx/reference/programming-model/aspectj.xml index 02ac4e4bc..62e78473e 100644 --- a/src/docbkx/reference/programming-model/aspectj.xml +++ b/src/docbkx/reference/programming-model/aspectj.xml @@ -29,7 +29,7 @@ To use the advanced, AspectJ based mapping, please add spring-data-neo4j-aspects as a dependency and set up the AspectJ integration in Maven or other build tools as explained in . - Some hints your IDE setup are described below. + Some hints for your IDE setup are described below.
AspectJ IDE support @@ -41,7 +41,7 @@ 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 + You should rely on your build-system and tests 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. diff --git a/src/docbkx/reference/programming-model/attachdetach.xml b/src/docbkx/reference/programming-model/attachdetach.xml index b1107690c..42e558b77 100644 --- a/src/docbkx/reference/programming-model/attachdetach.xml +++ b/src/docbkx/reference/programming-model/attachdetach.xml @@ -3,7 +3,7 @@
Detached node entities - Node entities can be in two different persistence state: attached or detached. By default, newly created node + Node entities can be in two different persistence states: attached or detached. By default, newly created node entities are in the detached state. When persist() is called on the entity, it becomes attached to the graph, and its properties and relationships are stores in the database. If persist() is not called within a transaction, it automatically creates an implicit @@ -87,10 +87,10 @@ movie.setTopActor(actor); 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). + exception is thrown (subject to be parameterized in the future). - If the relationships form a cycle, then the entities will first all be assigned a node in + If the relationships form a cycle, then the entities will first of all be assigned a node in the database, and then the relationships will be created. The cascading of persist() is however only cascaded to related entity fields that have been modified. diff --git a/src/docbkx/reference/programming-model/mapping.xml b/src/docbkx/reference/programming-model/mapping.xml index 98bd4606c..716bb4b37 100644 --- a/src/docbkx/reference/programming-model/mapping.xml +++ b/src/docbkx/reference/programming-model/mapping.xml @@ -3,9 +3,9 @@
Object Graph Mapping - Up until recently Spring Data Neo4j supported the only more advanced and flexible AspectJ based mapping approach, see . + Up until recently Spring Data Neo4j supported only the more advanced and flexible AspectJ based mapping approach, see . Feedback about issues with the AspectJ tooling and other implications supported us in adding a simpler mapping (see ) to Spring Data Neo4j. - Both versions work with the same annotations and provide similar API's but different behaviour. + Both versions work with the same annotations and provide similar API's, but different behaviour. Reflection and Annotation-based metadata is collected about persistent entities in the Neo4jMappingContext diff --git a/src/docbkx/reference/programming-model/node-entities.xml b/src/docbkx/reference/programming-model/node-entities.xml index d207d50d0..1bf4b4fce 100644 --- a/src/docbkx/reference/programming-model/node-entities.xml +++ b/src/docbkx/reference/programming-model/node-entities.xml @@ -48,10 +48,6 @@ 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 @@ -78,8 +74,8 @@ public class Movie { Spring Data Neo4j 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 named {self} for the id of the current entity. For instance start n=({self}) match n-[:FRIEND]->friend return friend. - Graph queries can return variable number of entities. That's why annotation can be put onto fields - with a single value, an Iterable of a concrete type or an Iterable of Map<String,Object>. + Graph queries can return variable number of entities. That's why annotations can be put onto fields + with a single value, an Iterable of a concrete type or an Iterable of type Map<String,Object>. Additional parameters are taken from the params attribute of the @Query annotation. The tuples form key-value pairs that are provided to the query at execution time. diff --git a/src/docbkx/reference/programming-model/projection.xml b/src/docbkx/reference/programming-model/projection.xml index 543f90e06..3b8bfac1d 100644 --- a/src/docbkx/reference/programming-model/projection.xml +++ b/src/docbkx/reference/programming-model/projection.xml @@ -13,7 +13,7 @@ doesn't support mixins one would put the sum of all of those into the entity class and thereby making it very big, brittle and hard to understand. Being able to take a basic order and project it to a different (not related in the inheritance hierarchy or even an interface) order type that is valid in the current - context and only offers the attributes and methods needed here would be very benefitial. + context and only offers the attributes and methods needed here would be very beneficial. Spring Data Neo4j offers initial support for projecting node and relationship entities to different target types. All instances of this projected entity share the same backing node or relationship, so data changes are @@ -33,7 +33,7 @@ class Trainee { Set trainings; } -for (Person person : graphRepository.findAllByProperyValue("occupation","developer")) { +for (Person person : graphRepository.findAllByPropertyValue("occupation","developer")) { Developer developer = person.projectTo(Developer.class); if (developer.isJavaDeveloper()) { trainInSpringData(developer.projectTo(Trainee.class)); diff --git a/src/docbkx/reference/programming-model/relationships.xml b/src/docbkx/reference/programming-model/relationships.xml index 4793a1802..233504547 100644 --- a/src/docbkx/reference/programming-model/relationships.xml +++ b/src/docbkx/reference/programming-model/relationships.xml @@ -71,9 +71,9 @@ public class Actor { - When you use an Interface as target type for the Set and/or as elementClass + 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. + or by annotating the interface with @NodeEntity too. By setting direction to BOTH, relationships are created in the outgoing direction, but when the diff --git a/src/docbkx/reference/programming-model/repositories.xml b/src/docbkx/reference/programming-model/repositories.xml index f2efb2c18..3b7f837a5 100644 --- a/src/docbkx/reference/programming-model/repositories.xml +++ b/src/docbkx/reference/programming-model/repositories.xml @@ -128,13 +128,13 @@
- Cypher-Queries + Cypher queries
- Annotated Queries + Annotated queries - Queries for the cypher graph-query language can be supplied with the @Query annotation. + Queries using the Cypher graph query language can be supplied with the @Query annotation. That means every method annotated with @Query("start n=(%node) match (n)-->(m) return m") - will use the query string. The named parameter %node will be replaced by the actual method parameters. + will use the supplied query string. The named parameter %node will be replaced by the actual method parameters. Node and Relationship-Entities are resolved to their respective id's and all other parameters are replaced directly (i.e. Strings, Longs, etc). There is special support for the Sort and Pageable parameters from Spring Data Commons, which are supported to add programmatic paging and sorting (alternatively @@ -146,7 +146,7 @@
- Named Queries + Named queries Spring Data Neo4j also supports the notion of named queries which are externalized in property-config-files (META-INF/neo4j-named-queries.properties). Those files have the format: Entity.finderName=query (e.g. Person.findBoss=start p=({p_person}) match (p)<-[:BOSS]-(boss) return boss). @@ -162,28 +162,28 @@
- Cypher Examples + Cypher examples There is a screencast available showing many features of the query language. The following examples are taken from the cineasts dataset of the tutorial section. - start n=(0) return n + start n=node(0) return n returns the node with id 0 - start movie=(Movie,title,'Matrix') return movie - returns the nodes which are indexed as 'Matrix' + start movie=node:Movie(title='Matrix') return movie + returns the nodes which are indexed with title equal to 'Matrix' - start movie=(Movie,title,'Matrix') match (movie)<-[:ACTS_IN]-(actor) return actor.name - returns the names of the actors that have a ACTS_IN relationship to the movie node for matrix + start movie=node:Movie(title='Matrix') match (movie)<-[:ACTS_IN]-(actor) return actor.name + returns the names of the actors that have a ACTS_IN relationship to the movie node for 'Matrix' - start movie=(Movie,title,'Matrix') match (movie)<-[r,:RATED]-(user) where r.stars > 3 return user.name, r.stars, r.comment - returns users names and their ratings (>3) of the movie matrix + start movie=node:Movie(title='Matrix') match (movie)<-[r:RATED]-(user) where r.stars > 3 return user.name, r.stars, r.comment + returns users names and their ratings (>3) of the movie titled 'Matrix' - start user=(User,login,'micha') match (user)-[:FRIEND]-(friend)-[r,:RATED]->(movie) return movie.title, AVG(r.stars), count(*) order by AVG(r.stars) desc, count(*) desc + start user=node:User(login='micha') match (user)-[:FRIEND]-(friend)-[r:RATED]->(movie) return movie.title, AVG(r.stars), COUNT(*) order by AVG(r.stars) desc, COUNT(*) desc returns the movies rate by the friends of the user 'micha', aggregated by movie.title, with averaged ratings and rating-counts sorted by both @@ -268,7 +268,7 @@ Person michael = personRepository.save(new Person("Michael",36)); Person dave=personRepository.findOne(123); -Iterable devs = personRepository.findAllByProperyValue("occupation","developer"); +Iterable devs = personRepository.findAllByPropertyValue("occupation","developer"); Iterable aTeam = graphRepository.findAllByQuery( "name","A*"); diff --git a/src/docbkx/reference/programming-model/simple_mapping.xml b/src/docbkx/reference/programming-model/simple_mapping.xml index 64ce1996c..0dd612794 100644 --- a/src/docbkx/reference/programming-model/simple_mapping.xml +++ b/src/docbkx/reference/programming-model/simple_mapping.xml @@ -10,8 +10,8 @@ The simple object graph mapping comes into play whenever an entity is constructed from a node or relationship. - That could be explicitely like during the lookup or create operations of the repositories and the - Neo4jTemplate but also implicitely while executing + This could be done explicitly like during the lookup or create operations of the repositories and the + Neo4jTemplate but also implicitly while executing any graph operation that returns nodes or relationships and expecting mapped entities to be returned. @@ -23,7 +23,7 @@ We try to avoid loading the whole graph into memory by not following relationships eagerly. A dedicated @Fetch annotation controls instead if related entities are loaded or not. Whenever an entity is not fully loaded, then only its id is stored. Those - entities or collections of entities can then later be loaded explictely using the template.fetch() operation. + entities or collections of entities can then later be loaded explicitly using the template.fetch() operation. The additional fetch information is stored in a MappingPolicy which can be retrieved via the Neo4jTemplate diff --git a/src/docbkx/reference/programming-model/spatial.xml b/src/docbkx/reference/programming-model/spatial.xml index f9c51fd99..adfcbe35a 100644 --- a/src/docbkx/reference/programming-model/spatial.xml +++ b/src/docbkx/reference/programming-model/spatial.xml @@ -5,7 +5,7 @@ SpatialRepository is a dedicated Repository for spatial queries. Spring Data Neo4j provides an optional dependency to neo4j-spatial which is an advanced library - for gis operations. So if you include the maven dependency in your pom.xml, Neo4j-Spatial and + for GIS operations. So if you include the maven dependency in your pom.xml, Neo4j-Spatial and the required SPATIAL index provider is available. @@ -21,7 +21,7 @@ - For having your entities available for spatial index queries, please include a String property containing + To have your entities available for spatial index queries, please include a String property containing a "well known text", location string. WKT is the Well Known Text Spatial Format eg. POINT( LON LAT ) or POLYGON (( LON1 LAT1 LON2 LAT2 LON3 LAT3 LON1 LAT1 )) diff --git a/src/docbkx/reference/setup.xml b/src/docbkx/reference/setup.xml index 8ac73ea9b..925af0cd4 100644 --- a/src/docbkx/reference/setup.xml +++ b/src/docbkx/reference/setup.xml @@ -12,14 +12,14 @@ - Spring Data Neo4j projects can be built using maven, we also added means to build them with gradle and ant/ivy. + Spring Data Neo4j projects can be built using Maven. There are also means to build them with Gradle or Ant/Ivy.
Dependencies for Spring Data Neo4j POJO Mapping For the POJO mapping it is enough to add the org.springframework.data:spring-data-neo4j:2.0.0.RC1 dependency - to your project. If you want to use the cypher query language please add org.neo4j:neo4j-cypher:1.5 + to your project. If you want to use the Cypher query language please add org.neo4j:neo4j-cypher:1.5 Maven dependencies for Spring Data Neo4j @@ -36,8 +36,8 @@
Gradle configuration for AspectJ Mapping - The necessary build plugin to build Spring Data Neo4j projects with gradle is available as part of the - Spring Data Neo4j distribution or on github which makes the usage as easy as: + The necessary build plugin to build Spring Data Neo4j projects with Gradle is available as part of the + Spring Data Neo4j distribution or on Github which makes the usage as easy as: Gradle Build Configuration @@ -62,7 +62,7 @@ repositories { }]]> - The actual springdataneo4j.gradle is very simple just decorating the javac tasks with the iajc ant task. + The actual springdataneo4j.gradle file is very simple, just decorating the javac tasks with the iajc ant task.
@@ -93,8 +93,8 @@ repositories {
Maven configuration - Spring Data Neo4j projects are easiest to build with Apache Maven. The core dependencies is Spring - Data Neo4j which comes with transitive dependencies to Spring Data Commons, parts of the Spring Framework, and the Neo4j graph database. + Spring Data Neo4j projects are easiest to build with Apache Maven. The core dependency is Spring + Data Neo4j, which comes with transitive dependencies to Spring Data Commons, parts of the Spring Framework, and the Neo4j graph database.