From 645bc9676bc7dd4783d99f1d36f3031ad70b9796 Mon Sep 17 00:00:00 2001 From: Michael Hunger Date: Thu, 11 Aug 2011 16:18:20 +0200 Subject: [PATCH] documentation updates --- src/docbkx/index.xml | 40 ++++-- src/docbkx/reference/preface.xml | 131 ++++++++++++++++-- .../reference/programming-model/aspectj.xml | 13 +- .../programming-model/attachdetach.xml | 2 +- .../programming-model/beanvalidation.xml | 2 +- .../programming-model/programming-model.xml | 4 +- .../programming-model/projection.xml | 2 +- .../programming-model/transactions.xml | 2 +- src/docbkx/reference/spring-data.xml | 11 -- src/docbkx/tutorial/about-tutorial.xml | 7 - 10 files changed, 160 insertions(+), 54 deletions(-) delete mode 100644 src/docbkx/reference/spring-data.xml diff --git a/src/docbkx/index.xml b/src/docbkx/index.xml index ac3ca748e..68d9e7807 100644 --- a/src/docbkx/index.xml +++ b/src/docbkx/index.xml @@ -19,12 +19,6 @@ &version; - - - - - - Michael @@ -59,10 +53,18 @@ Tutorial + + + + + + + + The first part of the book provides a tutorial that walks through the creation of a complete web application called cineasts.net, built with Spring Data Graph and Neo4j. - Cineasts are people who love movies, and the site is a gathering place for these people. For + Cineasts are people who love movies, and the site is a gathering place for moviegoers. For cineasts.net we decided to add a social aspect to the rating of movies, allowing friends to share their scores and get recommendations for new friends and movies. @@ -94,16 +96,32 @@ - Reference + Reference Documentation - This is the reference part of the book. It has information about the - programming model, APIs, concepts, and annotations of Spring Data Graph. + + + + + + + + + This part of the Spring Data Graph Guide book provides the reference documentation. It details many + aspects of the tutorial and also explains concepts that were only just mentioned there. + + + Its content covers information about the programming model, APIs, concepts, annotations and + technical details of Spring Data Graph. + + + Whenever you look for the means to employ the full power of the Spring Data Graph library you find your + answers in the reference section. If you don't, please inform us about missing or incorrect content so that + we can fix that. - diff --git a/src/docbkx/reference/preface.xml b/src/docbkx/reference/preface.xml index 409bc027d..16f7c9406 100644 --- a/src/docbkx/reference/preface.xml +++ b/src/docbkx/reference/preface.xml @@ -2,23 +2,130 @@ - Preface + Reference Documentation +
+ Spring Data and Spring Data Graph + + + Spring Data is a SpringSource project that aims to + provide Spring's convenient programming model and well known conventions for NOSQL databases. Currently there + is support for graph (Neo4j), key-value (Redis, Riak), document (MongoDB) and relational (Oracle) + databases. Mark Pollack, the author of Spring.NET, is the project lead for the Spring Data project. + + + + The Spring Data Graph project, as part of the Spring Data initiative, aims to simplify development + with the Neo4j graph database. Like JPA, it uses annotations on simple POJO domain objects. + The annotations activate 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, at 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. For other language bindings or frameworks + visit the Neo4j Wiki. + +
+ - The Spring Data Graph project, as part of the Spring Data initiative, aims to simplify development - with graph databases. Like JPA, it uses annotations on simple POJO beans. The annotations activate - 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. + The explanation of Spring Data Graphs programming model starts with some underlying details. + The basic internal workings of Spring Data Graph are explained in the initial chapter about AspectJ . + It also explains some of the common issues around AspectJ tooling with the current IDEs. - Spring Data Graph allows, at 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, you need only your domain model and the annotations + (see ) provided by the library. You use annotations to + mark domain objects to be backed by nodes and relationships of the graph database. For individual fields the + annotations allow you to declare how they should be processed and mapped to the graph. For property fields and + references to other entities this is straightforward. - 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. + Relationships between entities are first class citizens in a graph database and therefore worth a separate + chapter describing their usage in Spring Data Graph. + + + To add fields that are just backed by graph operations is a bit more involved. First you should know + about traversals, Cypher queries and Gremlin expressions. + Those are explained in the Neo4j-API chapter. Then you can start adding purely + dynamically gathered fields to your entities. + + + You might probably use the additional + entity methods (see ) that are added to your + domain objects by Spring Data Graph. Those allow you to manage the entity lifecycles 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. + + + Indexing operations are useful for finding individual nodes and relationships in a graph. They can be used to + start graph operations or to be processed in your application. Indexing in the plain Neo4j API is a bit more involved. + Spring Data Graph maintains automatic indexes per entity class, with @Indexed annotations on relevant fields. + () + + + If you don't want to go the path of persistence aware domain objects (Active-Record) but rather use a DAO layer, + Spring Data Commons provides a repository abstraction that is also implemented in Spring Data Graph. Those repositories + just consist of a composition of interfaces that declare the available methods on the concrete repository. The implementation + details are handled by the library. At least for typical CRUD, Index- and Query-operatoins that is very convenient. + For custom implementations of repository methods you are free to add your own code. (). + + + Neo4j is an ACID database, it uses Java transactions (and internally even a 2 phase commit protocol) to guarantee the + safety of your data. The implications of that are described in the chapter around transactions. () + + + The need of an active transaction for mutating the state of nodes or relationships implies that direct changes to + the graph are only possible in a transactional context. Unfortunately many higher level application layers don't + want to care about transactions and the open-session-in-view pattern is not widely used. Therefore Spring Data + Graph introduced an entity lifecyle and added support for detached entities which can be used for temporary + domain objects that are not intended to be stored in the graph or which will be attached to the graph only later. + () + + + Unlike Neo4j which is a schema free database, Spring Data Graph works on Java domain objects. So it needs to store + the type information of the entities in the graph to be able to reconstruct them when just nodes are retrieved. To + achieve that it employs type-representation-strategies which are described in a separate chapter. + () + + + To be able to leverage the schema-free nature of Neo4j it is possible to project any entity to another entity type. That + is useful as long as they share some properties (or relationships). The entities don't have to share any super-types + or hierarchies. How that works is explained here: . + + + Spring Data Graph offers basic support for bean property validation (JSR-303). Annotations from that JSR are recognized + and evaluated whenever a property is set, or when a previously detached entity is persisted to the graph. + (see ) + + + + To use advanced functionality like traversals, Cypher and Gremlin, a basic understanding of the graph data model is required. + The graph data model is explained in the chapter about Neo4j. diff --git a/src/docbkx/reference/programming-model/aspectj.xml b/src/docbkx/reference/programming-model/aspectj.xml index 6a3b0f9ee..c664fab1d 100644 --- a/src/docbkx/reference/programming-model/aspectj.xml +++ b/src/docbkx/reference/programming-model/aspectj.xml @@ -11,12 +11,10 @@ The aspect introduces some internal fields and some public methods - (see ) in the entities, such as + (see ) to the entities, such as entity.getPersistentState() and entity.relateTo. - It also introduces repository methods like - find(Class<? extends NodeEntity>, TraversalDescription), - and equals() and hashCode delegation, making equals() - honor the backing state. + It also introduces repository methods likefind(Class<? extends NodeEntity>, TraversalDescription). + Introduced methods for equals() and hashCode() use the underlying node or relationship. Spring Data Graph internally uses an abstraction called EntityState that the field @@ -24,7 +22,7 @@ minimum, focusing mainly on the pointcuts and delegation code. The EntityState then uses a number of FieldAccessorFactories to create a FieldAccessor instance per field that does the specific handling needed for the concrete field type. There are various layers of - caching involved as well, so it handles repeat instantiation efficiently. + caching involved as well, so it handles repeated instantiation efficiently.
AspectJ IDE support @@ -50,7 +48,8 @@ - There might be some issues with the eclipse maven plugin not adding AspectJ files correctly to the build path. If you encounter issues, please try the following: + There might be some issues with the eclipse maven plugin not adding AspectJ files correctly to the build path. + If you encounter issues, please try the following: Try editing the build path to include **/*.aj for the spring-data-neo4j project. You can do this by selecting "Build Path -> Configure Build Path ..." from the Package Explorer. diff --git a/src/docbkx/reference/programming-model/attachdetach.xml b/src/docbkx/reference/programming-model/attachdetach.xml index 4e4f7feee..7275ab28a 100644 --- a/src/docbkx/reference/programming-model/attachdetach.xml +++ b/src/docbkx/reference/programming-model/attachdetach.xml @@ -1,6 +1,6 @@ -
+
Detached node entities Node entities can be in two different persistence state: attached or detached. By default, newly created node diff --git a/src/docbkx/reference/programming-model/beanvalidation.xml b/src/docbkx/reference/programming-model/beanvalidation.xml index de0d6203d..a360a22cc 100644 --- a/src/docbkx/reference/programming-model/beanvalidation.xml +++ b/src/docbkx/reference/programming-model/beanvalidation.xml @@ -1,6 +1,6 @@ -
+
Bean validation (JSR-303) Spring Data Graph supports property-based validation support. When a property is changed, it is diff --git a/src/docbkx/reference/programming-model/programming-model.xml b/src/docbkx/reference/programming-model/programming-model.xml index 91377d676..27267cd4c 100644 --- a/src/docbkx/reference/programming-model/programming-model.xml +++ b/src/docbkx/reference/programming-model/programming-model.xml @@ -5,18 +5,18 @@ This chapter covers the fundamentals of the programming model behind Spring Data Graph. It discusses the AspectJ features used and the annotations provided by Spring Data Graph and how to use them. - Examples for this section are taken from the imdb project of + Examples for this section are taken from the "IMDB" project of Spring Data Graph examples. + - diff --git a/src/docbkx/reference/programming-model/projection.xml b/src/docbkx/reference/programming-model/projection.xml index e7c52e502..6bf282ec7 100644 --- a/src/docbkx/reference/programming-model/projection.xml +++ b/src/docbkx/reference/programming-model/projection.xml @@ -1,6 +1,6 @@ -
+
Projecting entities As the underlying data model of a graph database doesn't imply and enforce strict type constraints like a diff --git a/src/docbkx/reference/programming-model/transactions.xml b/src/docbkx/reference/programming-model/transactions.xml index a84ede1de..39b36d998 100644 --- a/src/docbkx/reference/programming-model/transactions.xml +++ b/src/docbkx/reference/programming-model/transactions.xml @@ -1,6 +1,6 @@ -
+
Transactions Neo4j is a transactional database, only allowing modifications to be performed within transaction diff --git a/src/docbkx/reference/spring-data.xml b/src/docbkx/reference/spring-data.xml deleted file mode 100644 index 70a755e30..000000000 --- a/src/docbkx/reference/spring-data.xml +++ /dev/null @@ -1,11 +0,0 @@ - - - - About Spring Data - - Spring Data is a SpringSource project that aims to - provide Spring's convenient programming model and well known conventions for NOSQL databases. Currently there - is support for graph (e.g. Neo4j), key-value (e.g. Redis), document (e.g. MongoDB) and relational (e.g. Oracle) - databases. Mark Pollack, the author of Spring.NET, is the project lead for the Spring Data project. - - diff --git a/src/docbkx/tutorial/about-tutorial.xml b/src/docbkx/tutorial/about-tutorial.xml index 813ecd48f..43c07425b 100644 --- a/src/docbkx/tutorial/about-tutorial.xml +++ b/src/docbkx/tutorial/about-tutorial.xml @@ -15,13 +15,6 @@ with, or share movie preferences with. Even better, finding new friends and movies based on what you and your friends like. - - - - - - - When we looked for possible sources of data, IMDB was our first stop. But they're a bit expensive for our taste, charging $15k USD for data access. Fortunately, we found