diff --git a/src/docbkx/index.xml b/src/docbkx/index.xml index 906cf69f6..727db06c2 100644 --- a/src/docbkx/index.xml +++ b/src/docbkx/index.xml @@ -12,14 +12,14 @@ Tutorial - In this first part of the book we run a tutorial that creates a complete web application built on top of Spring Data Graph. - It uses a domain that should be familiar to most - movies. So for cineasts.net we decided to add a social - touch to the whole movie rating business, allowing friends to share their ratings and get recommendations + 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. + It uses a domain that should be familiar - movies. So for cineasts.net we decided to add a social + touch to rating movies, allowing friends to share their scores and get recommendations for new friends and movies. - The tutorial is presented as a colloquial description of the steps necessary to create the application. - It provides the configuration and code examples that are needed to understand what's happening. The complete - source code repository for running the app is available on github. + The tutorial walks the steps necessary to create the application. + It provides the configuration and code examples that are needed to understand what's happening in Spring Data Graph. Of course the complete source code for the app is available at github. diff --git a/src/docbkx/introduction/get-started.xml b/src/docbkx/introduction/get-started.xml index 5d7f430c2..47f259c05 100644 --- a/src/docbkx/introduction/get-started.xml +++ b/src/docbkx/introduction/get-started.xml @@ -4,24 +4,23 @@ Getting Started - NOSQL databases has come into focus only recently, even if some of them have existed for a few years by now. + NOSQL databases have only recently come to prominence, even though some of them have existed for a few years now. That's why this document will not only guide you through the relevant parts of the Spring Data Graph API, but also explain some key concepts of graph databases. - After reading this document, you should be able to integrate Spring Data Graph into your existing or future applications. - If there are any issues that you don't understand or think are explained in a too complicated way, please report back any - problems or suggestions. Your input will also benefit future readers of this documentation. For details on how to get help + After reading this document, you should be able to integrate Spring Data Graph into your applications. + If there are any inaccuracies, issues or if you just think the explanations are too complicated, please feed that back to us. Your input will also benefit future readers of this documentation. For details on how to get help and provide feedback, see .
First Steps - As explained in , Spring Data Graph (Spring Data Graph) provides integration - between the Spring framework and graph databases. Familiarity with the Spring framework is assumed as stated in , and only - minimally cross-referenced here. Graph databases and Neo4j in particular are explained in a bit more detail. - The main focus of this document is however on explaining the steps needed to get a Spring Data Graph-backed application up and running. + As explained in , Spring Data Graph provides integration + between the Spring framework and graph databases. As we said in the introduction , familiarity with the Spring framework is assumed to get the most out of this book. + But we will explain graph databases and Neo4j in particular in a little more detail. + The main focus of this document is to explain the steps needed to get an interesting Spring Data Graph application up and running.
@@ -33,16 +32,13 @@ to know the Spring APIs, understanding the concepts behind them is essential. The Spring Framework documentation home page is a good starting point for - developers who want to become more familiar with Spring Framework. + developers who want to become more familiar with the Spring Framework.
Knowing NOSQL and graph databases - The recent interest in NOSQL databases is mainly driven by the need to find the best suited storage solution for data - structured in a specific way. It should fit the data, not the other way round. Another issue is the scalability of the - database, especially with today's fast growing user bases. There are many NOSQL databases, - and one should become familiar with the different concepts, advantages, and disadvantages before choosing - a solution. A problem with the NOSQL databases is the different data access APIs that are provided. Spring Data aims at easing this burden by - providing consistent abstractions over those APIs, leveraging SpringSource's experience and good reputation in this area. + The recent interest in NOSQL databases has been driven by the need to find the better storage solutions for different kinds of data and access patterns. The NOSQL mantra is that databases should fit the data, not the other way round. + The NOSQL space is overflowing with interesting and useful technology. But as a consequence, each store tends to implement its own data access API, leading to a steep learning curve for developers intent on using polyglot persistence. Spring Data aims to ease this burden by + providing consistent abstractions over those underlying data access APIs. Graph databases are a particularly good fit for large networks of connected information (objects). They map objects to nodes and connections to @@ -63,7 +59,7 @@
Need Help? - If you encounter issues or you are just looking for an advice, feel free to use one of the links below: + If you encounter issues or you are just looking for advice, feel free to use one of the links below:
Spring Data homepage @@ -73,7 +69,7 @@
Professional Support Professional, from-the-source support, with guaranteed response time, is available from SpringSource, - the company behind Spring Data and Spring. + the company behind Spring Data and the Spring Framework.
@@ -84,9 +80,9 @@ For information on the Spring Data source code repository, nightly builds and snapshot artifacts please see the Spring Data home page. - You can help make Spring Data best serve the needs of the Spring community by interacting with developers through the + You can help make Spring Data better serve the needs of the Spring community by interacting with developers through the community forums. - If you encounter a bug or want to suggest an improvement, + If you find a bug or want to suggest an improvement, please create a ticket on the Spring Data Graph issue tracker. To stay up to date with the latest news and announcements in the Spring eco system, subscribe to the Spring Community Portal. diff --git a/src/docbkx/introduction/introduction.xml b/src/docbkx/introduction/introduction.xml index b08608af8..6d4495a35 100644 --- a/src/docbkx/introduction/introduction.xml +++ b/src/docbkx/introduction/introduction.xml @@ -5,7 +5,7 @@ This document is the reference guide for Spring Data Graph. - It explains the underlying concepts, usage, infrastructure of the framework and the semantics for the used graph database. + It explains the underlying concepts, usage, infrastructure of the framework and the behaviour of the underlying graph database. For an introduction to graph databases, Spring, or Spring Data examples, please refer to diff --git a/src/docbkx/introduction/preface.xml b/src/docbkx/introduction/preface.xml index a3c1e0df9..440873886 100644 --- a/src/docbkx/introduction/preface.xml +++ b/src/docbkx/introduction/preface.xml @@ -22,19 +22,18 @@
About this Guide Book - Welcome to the Spring Data Graph Guide Book. Thank you for taking the time to get an in depth look into the - usage and workings of the Spring Data Graph Library. Spring Data Graph is part of the Spring Data project which - aims to provide the convenient programming model of the Spring Framework to the big field modern datastores - (mostly NoSQL). Spring Data Graph in particular currently provides integration for the Neo4j Graph Database. + Welcome to the Spring Data Graph Guide Book. Thank you for taking the time to get an in depth look into Spring Data Graph Library. Spring Data Graph is part of the Spring Data project which + brings the convenient programming model of the Spring Framework to modern (mainly NoSQL) datastores. + Spring Data Graph currently provides integration for the Neo4j Graph Database. - It was written by developers for developers. So hopefully we created a documentation that is well received by + It was written by developers for developers. So hopefully we've created a documentation that is well received by our peers. If you have any feedback to the Spring Data Graph Library or this book, please provide it via SpringSource JIRA, the SpringSource NoSQL Forum, github comments or issues or the Neo4j mailing list. - This book is presented as a duplex book, a term coined by Martin Fowler. A duplex book consists of at least two + This book is presented as a duplex book, a term coined by Martin Fowler. A duplex book consists of at least two parts. The first part is an easily accessible narrative, that gives the reader an overview of the topics contained in the book. It contains lots of examples and more general discussion topics. This should be the only part of the book that is required to be read cover-to-cover. diff --git a/src/docbkx/introduction/requirements.xml b/src/docbkx/introduction/requirements.xml index 267835e9a..cb016d702 100644 --- a/src/docbkx/introduction/requirements.xml +++ b/src/docbkx/introduction/requirements.xml @@ -4,15 +4,15 @@ Requirements - The Spring Data Graph 1.x binaries requires JDK level 6.0 or higher, + Spring Data Graph 1.x requires JDK level 6.0 or higher, and Spring Framework 3.0.x or higher. - For the graph database binary, Neo4j version 1.2 or higher is required. + For the graph database, Neo4j 1.2 or higher is required. Neo4j has a dependency on Apache Lucene for indexing. Users are encouraged to use the latest version of Neo4j available. - For building the project, Apache Maven (version 2.10 and above) is strongly recommended. + For building the project, Apache Maven (version 2.10 and above) is recommended. diff --git a/src/docbkx/introduction/why-sd-graph.xml b/src/docbkx/introduction/why-sd-graph.xml index ea5573d50..9c42214df 100644 --- a/src/docbkx/introduction/why-sd-graph.xml +++ b/src/docbkx/introduction/why-sd-graph.xml @@ -5,30 +5,29 @@ Why Spring Data Graph? NOSQL - stores provide storage solutions that are more tailored to the specific - data storage requirements of each project than just using a relational - database as a "one-size-fits-all" solution. + stores provide novel storage solutions to suit the + data storage requirements of modern applications. - Graph databases provide excellent support for graph-like data (networks); that is data that easily can - be structured as connected nodes. - Property graph databases like Neo4j support an arbitrary number of named properties on both - nodes and relationships. Neo4j is highly performant when traversing large, complex datasets with + Graph databases provide excellent support for connected data - that is data that easily can + be structured as connected nodes in a network. + Property graph databases like Neo4j support an arbitrary number of named properties on + nodes and relationships. Neo4j is highly performant when traversing large, highly-connected datasets with millions of nodes and relationships, even on commodity hardware. Neo4j is an open source graph database written in Java. It has excellent performance characteristics while providing ACID - semantics and transactional support (both JTA and XA transactions). Neo4j can run as a lightweight embedded database as well as a standalone + semantics and full transactional support (both JTA and XA transactions). Neo4j can run as a lightweight embedded database as well as a standalone server that exposes the API via a rich REST interface. - The Spring Data Graph (or Spring Data Graph) framework makes it easy to + The Spring Data Graph framework makes it easy to integrate graph databases in existing or new Spring applications. It provides - infrastructure that reduces the amount of boilerplate data access code and uses - common patterns and idioms that are well known in the Spring Framework community such as declarative transaction managment. + infrastructure that reduces boilerplate data access code and uses + common patterns and idioms that are well-known in the Spring community, such as declarative transaction management. Those practices are based on a simple POJO programming model that leverages annotations to add metadata. It can be integrated in any part of a Spring application, - like the web or service layers. + including the Web or service layers. A special use case of Spring Data Graph is the cross-store functionality that can extend diff --git a/src/docbkx/reference/cross-store.xml b/src/docbkx/reference/cross-store.xml index eb1bf27cf..3ab1aaa8b 100644 --- a/src/docbkx/reference/cross-store.xml +++ b/src/docbkx/reference/cross-store.xml @@ -39,7 +39,7 @@
@NodeEntity(partial = "true") - When annotating an entity with partial true, Spring Data Graph assumes that this is a cross-store entity. So it is only responsible for the fields + When annotating an entity with partial true, Spring Data Graph assumes that this is a cross-store entity. So its only responsibility is for the fields annotated with Spring Data Graph annotations. JPA should not take care of these fields (they should be annotated with @Transient). In this mode of operation Spring Data Graph also handles the cross-store connection via the content of the JPA id field. diff --git a/src/docbkx/reference/neo4j.xml b/src/docbkx/reference/neo4j.xml index 52d9a8c37..aace3d190 100644 --- a/src/docbkx/reference/neo4j.xml +++ b/src/docbkx/reference/neo4j.xml @@ -3,7 +3,7 @@ Introduction to Neo4j - Neo4j is a graph database. It is a fully transactional database that + Neo4j is a graph database. It is a fully ACID transactional database that stores data structured as graphs. A graph consists of nodes, connected by relationships. It is a flexible data structure that allows for high query performance on complex data, while being intuitive for the developer. diff --git a/src/docbkx/tutorial/about-tutorial.xml b/src/docbkx/tutorial/about-tutorial.xml index 700faaad7..20d77d233 100644 --- a/src/docbkx/tutorial/about-tutorial.xml +++ b/src/docbkx/tutorial/about-tutorial.xml @@ -3,12 +3,12 @@ Allow me to introduce - Cineasts.net -Once upon a time I wanted to build a social movie database myself. First things first - I had a name: "Cineasts" - the people -crazy about movies. So I went ahead and got the domain, cineasts.net. So, the project was almost done. +Once upon a time we wanted to build a social movie database. First things first - we had a name: "Cineasts" - the cinema enthusiasts who are +crazy about movies. So we went ahead and got the domain, cineasts.net and the project was almost complete. -I had some ideas as well. Of course there should be Actors who play Roles in Movies. I needed the Cineast, too, someone -had to rate the movies after all. And while they were there, they could also make friends. Find someone to accompany them to the cinema or share -movie preferences. Even better, the engine behind all that could recommend new friends and movies to them, derived from their interests and +We had some ideas about the domain too. Of course there should be actors who play roles in movies. We needed the Cineast, too, someone +to rate the movies. And while they were there, they could also make friends. Find someone to accompany them to the cinema or share +movie preferences. Even better, the engine behind all that should recommend new friends and movies to cineasts, based on their interests and existing friends. @@ -16,11 +16,9 @@ existing friends. -I looked for possible sources for data, IMDB was my first stop, but they charge 15k USD for data usage. Fortunately I found TheMoviedb.org which has - built its data independently by users and provides the data for free for any usecase. The also have liberal terms and conditions and a nice API for fetching the data. +When we looked for possible sources for data, IMDB was our first stop, but they're a little expensive for our tastes, charging 15k USD for data access. Fortunately we found TheMoviedb.org which provides user-generated data for free. The also have liberal terms and conditions and a nice API for fetching the data. -There were many more ideas but I wanted to get something done over the course of one day. So this was the scope I was going to tackle. And this is how it should look - like. +There were many more ideas but we wanted to get something done quickly. And this is how it should look. diff --git a/src/docbkx/tutorial/annotations.xml b/src/docbkx/tutorial/annotations.xml index 49744a102..3967d3520 100644 --- a/src/docbkx/tutorial/annotations.xml +++ b/src/docbkx/tutorial/annotations.xml @@ -3,16 +3,16 @@ Decorations - Annotated Domain - I looked at the documentation again, found a simple Hello-World example and tried to understand it. - The entities were annotated with @NodeEntity, that was simple, so I added the annotation to my domain classes too. - Relationships got their own annotation named @RelationshipEntity. Property fields should be taken care of automatically. + Looking at the documentation again, we found a simple Hello-World example and tried to understand it. + The entities were annotated with @NodeEntity, that was simple, so we added the annotation to our domain classes too. + Relationships got their own annotation named @RelationshipEntity. Property fields are taken care of automatically. - Ok lets put this into a test. How to assure that a field was persisted to the graph store? There seemed to be two possibilities. First was to get a - GraphDatabaseContext injected and use its getById() method. The other one was a Finder approach which I ignored for now. Let's keep things simple. - How to persist an entity and how to get its id? No idea. So further study of the documentation revealed that there were a bunch of methods introduced to the - entities by the aspects. That was not obvious. But I found the two that would help me here - entity.persist() and entity.getNodeId(). + It's time to put this to a test. How can we be assured that a field is persisted to the graph store? There seemed to be two possibilities. First was to get a + GraphDatabaseContext injected and use its getById() method. The other one was a Finder approach. But let's try to keep things simple. + How can we persist an entity and how to get its id? No idea, so time to hit the documentation again, revealing that there are a bunch of methods introduced to the + entities by the aspects. That's not obvious, but we found the two that would help here - entity.persist() and entity.getNodeId(). - So my test looked like this. + So our test looked like this. - That worked, cool. But what about transactions I didn't declare the test to be transactional? After further reading I learned that persist() creates an - implicit transaction - so that was like an EntityManager would behave. Ok for me. I also learned that for more complex operations on the entities I needed + That worked! But what about transactions? We didn't declare the test to be transactional. After further reading we learned that persist() creates an + implicit transaction - so that was like an EntityManager would behave. Ok, now we're getting somewhere. We also learned that for more complex operations on the entities we'd need external transactions. diff --git a/src/docbkx/tutorial/domain.xml b/src/docbkx/tutorial/domain.xml index bdcc4213d..f875b49dc 100644 --- a/src/docbkx/tutorial/domain.xml +++ b/src/docbkx/tutorial/domain.xml @@ -3,8 +3,8 @@ Setting the Stage - Movies Domain - The domain model was the next thing I planned to work on. I wanted to flesh it out first before diving into library details. Going along the ideas outlined before I - came up with this. I also peeked in the datamodel of my import data source themoviedb to confirm that it matched my expectations. + The domain model was the next thing we planned to work on. We wanted to sketch it out first before diving into library details. We also looked at the datamodel of core themoviedb data to + confirm that it matched our expectations. - The importer used a simple caching mechanism, to keep downloaded actor and movie data on the filesystem, so that I didn't have to strain the remote API that much and that often. - In the code below you can see, that I changed the actor to a person so that I can also accomodate for all the other - people that contribute in movie making. + The importer used a simple caching mechanism, to keep downloaded actor and movie data on the filesystem, so that we didn't have to overload the remote API. + In the code below you can see, that we've changed the actor to a person so that we can also accommodate the other folks that participate in movie production. - The last part was adding some protected URI to the MovieController to allow to import ranges of movies. - During testing it became obvious that the calls to themoviedb where the limiting factor. As soon as + The last part involved adding a protected URI to the MovieController to allow importing ranges of movies. + During testing it became obvious that the calls to themoviedb were a limiting factor. As soon as the data was stored locally it took only subseconds to create the data in the Neo4j graph database. diff --git a/src/docbkx/tutorial/indexing.xml b/src/docbkx/tutorial/indexing.xml index 4e5268c79..1fcc294b0 100644 --- a/src/docbkx/tutorial/indexing.xml +++ b/src/docbkx/tutorial/indexing.xml @@ -3,9 +3,9 @@ Do I know you? - Indexing - Then there was an @Indexed annotation for fields. I wanted to try this too. That would guide the next test. I added an @Indexed to the id field of the movie. - This field is intended to represent the external id that will be used in URIs and will stable over database imports and updates. This time I went with the - Finder to retrieve my indexed movie. + There an @Indexed annotation for fields. We wanted to try this out, and use it to guide the next test. We added an @Indexed to the id field of the movie. + This field is intended to represent the external id that will be used in URIs and will stable over database imports and updates. This time we went with the + Finder to retrieve the indexed movie. @@ -33,6 +33,6 @@ class Movie { ]]> - TODO This failed with an exception about not being in a transaction. Oh, I forgot to add the @Transactional. So I added it to the test. + Surprisingly, this failed with an exception about not being in a transaction, which means we forgot to add the @Transactional annotation. That's easy enough to add to the test, and resume the test/code cycle. diff --git a/src/docbkx/tutorial/neo4j.xml b/src/docbkx/tutorial/neo4j.xml index 7b6af07c3..faa706ee2 100644 --- a/src/docbkx/tutorial/neo4j.xml +++ b/src/docbkx/tutorial/neo4j.xml @@ -3,16 +3,14 @@ Graphs ahead - Learning Neo4j - Then came the unknown - how to put these domain objects into the graph. First I read up about graph databases, especially Neo4j. - Their datamodel consists of nodes and relationships all of which can have properties. Relationships as first class citizens - I liked that. - Then there was the possibility to index nodes and relationships by field, value pairs to quickly get hold of them. - Those could then be the starting points for further processing. Other useful operations were manual traversal of relationships - and a powerful traversal based on a query-like Traversal Description. That all seemed pretty easy. + Then came the unknown - how to put these domain objects into the graph. First we read up about graph databases, especially Neo4j. + The Neo4j datamodel consists of nodes and relationships all of which can have properties. Relationships are first class citizens in Neo4j, meaning we can link together nodes into semantically rich networks - we really liked that. + Then we found we could index nodes and relationships by {name, value} pairs to quickly get hold of them as starting points for further processing. We also found we could imperatively traverse of relationships using the core API, and in a declarative way using a query-like Traversal Description. - I also learned that Neo4j was transactional and provided the known ACID guarantees for my data. This was unsual for a NoSQL database but easier for me to get - my head around than non-transactional eventual persistence. That also meant that I had to manage transactions somehow. Keep that in mind. + We also learned that Neo4j was fully transactional and completely upholds ACID guarantees for out data. This is unusual for NoSQL databases, but easier for us to get + my head around than non-transactional eventual consistency. It also makes us feel safe, though it also means that we had to manage transactions. Keep that in mind. - So I tried to use the raw Neo4j-API so get a feeling for that. And also see, how (probably) the domain would end up in the graph store. After adding the maven + Initially we used the core Neo4j API to get a feeling for that. And also to see, how (probably) the domain might look when it's saved in the graph store. After adding the maven dependency, it was ready to go. Movies! Friends! Bargains! - Recommendations - In the last part of this exercise I wanted to add some recommendation algorithms to my app. One was the recommendation of movies that my friends liked very much - (and their friends in descending importance). The second was recommendations for new friends that also liked the movies that I liked most. + In the last part of this exercise we wanted to add recommendations to the app. One obvious recommendation is movies that our friends liked + (and their friends too, but with less importance). The second was recommendations for new friends that also liked the movies that we liked most. - Doing this kind of ranking algorithms is the real fun with graph databases. They are applied to the graph by traversing it in a certain order, collecting information + Doing this kind of ranking algorithms is really fun with graph databases. They are applied to the graph by traversing it in a certain order, collecting information on the go and deciding which paths to follow and what to include in the results. Lets say I'm only interested in the top 10 recommendations each. diff --git a/src/docbkx/tutorial/relationships.xml b/src/docbkx/tutorial/relationships.xml index f8c2c583c..aefcf645a 100644 --- a/src/docbkx/tutorial/relationships.xml +++ b/src/docbkx/tutorial/relationships.xml @@ -5,9 +5,9 @@
Value in Relationships - Creating them - Next were relationships. Direct relationships didn't require any annotation. Unfortunately I had none of those, because mine had more semantics. - So I went for the Role relationship between Movie and Actor. - It had to be annotated with @RelationshipEntity and the @StartNode and @EndNode had to be marked. So my Role looked like this: + Next were relationships. Direct relationships didn't require any annotation. Unfortunately we had none of those, because ours had more semantics. + So we went for the Role relationship between Movie and Actor. + It had to be annotated with @RelationshipEntity and the @StartNode and @EndNode had to be marked. So our Role looked like this: - When writing a test for that I tried to create the relationship entity with new, but got an exception saying that this was not allowed. Some weird restriction -about having only correctly constructed RelationshipEntities. So I remembered a relateTo method from the list of introduced methods on the NodeEntities. After -quickly checking it turned out to be exactly what I needed. I added the method for connecting movies and actors to the actor - seemed more natural. + When writing a test for that we tried to create the relationship entity with new, but got an exception saying that this is not allowed. This must be a strange restriction +about having only correctly constructed RelationshipEntities. To fix it, we had to recall the relateTo method from the introduced methods on the NodeEntities. After +checking it turned out to be exactly what we needed. We then added the method for connecting movies and actors to the actor - which seems a more natural fit. Who's there ? - Accessing related entities - What was left - accessing those relationships. I already had the appropriate fields in both classes. Time to annotate them correctly. For the fields providing + What was left? Accessing those relationships. We already had the appropriate fields in both classes. Time to annotate them correctly. For the fields providing access to the entities on the each side of the relationship this was straightforward. Providing the target type again (thanks to Java's type erasure) and the -relationship type (that I learned from the Neo4j lesson before) there was only the direction left. Which defaults to OUTGOING so only for the movie I had to +relationship type (learned from the Neo4j lesson before) there was only the direction left. Which defaults to OUTGOING so only for the movie we had to specify it. @@ -72,20 +72,20 @@ class Actor { ]]> - While reading about those relationship-sets I learned that they are handled by managed collections of spring data graph. So whenever I add something to the - set or remove it, it automatically reflects that in the underlying relationships. Neat. But this also meant I mustn't initialize the fields. Something I will + While reading about those relationship-sets we learned that they are handled by managed collections of Spring Data Graph. So whenever we add something to the + set or remove it, it automatically reflects that in the underlying relationships. Neat. But this also meant we mustn't initialize the fields. Something we will certainly forget not to do in the future, so watch out for it. - I didn't forget to add test for those. So I could assure that the collections worked as advertised (and also ran into the intialization problem above). + We made sure to add a test for those, so are assured that the collections worked as advertised (and also ran into the intialization problem above).
May I introduce ? - Accessing Relationships themselves - But I still couldn't access the Role relationships. There was more to read about this. For accessing the relationship in between the nodes there was a separate - annotation @RelatedToVia. And I had to declare the field as readonly Iterable<Role>. That should make sure that I never tried to add Roles (which I couldn't create on my own anyway) - to this field. Otherwise the annotation attributes were similar to those used for @RelatedTo. So off I went, creating my first real relationship (just kidding). + But we still couldn't access the Role relationships. There was more to read about this. For accessing the relationship in between the nodes there was a separate + annotation @RelatedToVia. And we had to declare the field as readonly Iterable<Role>. That should make sure that we never tried to add Roles (which I couldn't create on my own anyway) + to this field. Otherwise the annotation attributes were similar to those used for @RelatedTo. So off we went, creating our first real relationship (just kidding). - After the tests proved that those relationship fields really mirrored the underlying relationships in the graph and instantly reflected additions and removals I was - satisfied with my domain so far and went for some coffee and chocolate. + After the tests proved that those relationship fields really mirrored the underlying relationships in the graph and instantly reflected additions and removals we were + pretty satisfied with our domain.
diff --git a/src/docbkx/tutorial/repository.xml b/src/docbkx/tutorial/repository.xml index f5f6e092b..817ae3c75 100644 --- a/src/docbkx/tutorial/repository.xml +++ b/src/docbkx/tutorial/repository.xml @@ -3,8 +3,8 @@ Serving a good cause - Repository - That was the first method to add to the brand new repository. So I created a repository for my application, annotated - it with @Repository and @Transactional. I did the same for the Actor. + That was the first method to add to the brand new repository. So we created a repository for the application, annotated + it with @Repository and @Transactional. We did the same for the Actor. Requisites - Populating the database - Time to put this on display. But I needed some test data first. So I wrote a small class for populating the database which could be called from my controller. - To make it safe to call it several times I added index lookups to check for existing entries. A simple /populate endpoint for the controller that called it would + Time to put this on display. But we needed some test data first. So we wrote a small class for populating the database which could be called from our controller. + To make it safe to call several times we added index lookups to check for existing entries. A simple /populate endpoint for the controller that called it would be enough for now. @@ -69,8 +69,8 @@ public class MovieController { ]]> - See the misused GET parameter for that (don't do this at home). This is only for running it from the browser - address line. Better use POST and curl for the call. So I called the URI and it showed the single added movie + See the misused GET parameter for that (don't do this at home, the REST guys will be upset). This is only for running it from the browser + address line. Better use POST and curl for the call. So we called the URI and it showed the single added movie on screen.
@@ -80,7 +80,7 @@ public class MovieController {
Eye candy - Neoclipse visualization - After filling the database I wanted to see what the graph looked like. So I checked out two tools that are available for inspecting the graph. First Neoclipse, an + After filling the database we wanted to see what the graph looked like. So we checked out two tools that are available for inspecting the graph. First Neoclipse, an eclipse RCP application or plugin that connects to existing graph stores and visualizes their content. After getting an exception about concurrent access, I learned that I have to use Neoclipse in readonly mode when my webapp had an active connection to the store. Good to know. @@ -95,11 +95,11 @@ public class MovieController {
Hardcore "Hacking" - Neo4j Shell - Besides my movies and actors connected by ACTS_IN relationships there were some other nodes. The reference node which is kind of a root node in Neo4j and can be used + Besides our movies and actors connected by ACTS_IN relationships there were some other nodes. The reference node which is an automatically provided "root node" in Neo4j and can be used to anchor subgraphs for easier access. And Spring Data Graph also represented the type hierarchy of my entities in the graph. Obviously for some internal housekeeping and type checking. - For us console junkies there is also a shell that can reach into a running neo4j store (if that one was started with enableRemoteShell) or provide readonly access + For console junkies there is also a shell that can reach into a running neo4j store (if that one was started with enableRemoteShell) or provide readonly access to a graph store directory. diff --git a/src/docbkx/tutorial/security.xml b/src/docbkx/tutorial/security.xml index 0e1201a5a..484e59756 100644 --- a/src/docbkx/tutorial/security.xml +++ b/src/docbkx/tutorial/security.xml @@ -3,10 +3,10 @@ Protecting Assets - Adding Security - To have a user in the webapp I had to put it in the session and add login and registration pages. Of course the pages that only worked with a valid user + To have a user in the webapp we had to put it in the session and add login and registration pages. Of course the pages that only worked with a valid user account had to be secured as well. -I used Spring Security to that, writing a simple UserDetailsService that used a repository for looking up the users and validating their credentials. The config is located +We used Spring Security for that, writing a simple UserDetailsService that used a repository for looking up the users and validating their credentials. The config is located in a separate applicationContext-security.xml. But first, as always, maven and web.xml setup. @@ -155,8 +155,8 @@ public class CineastsUserDetails implements UserDetails { After that a logged in user was available in the session and could so be used for all the social interactions. Most of the work done next was adding controller methods -and JSPs for the views. I used the helper method getUserFromSession() in the controllers to access the logged in user and put it in the model for rendering. - As a teaser I'd like to show off the user profile page, as it will be rendered after heavy UX lifting. +and JSPs for the views. We used the helper method getUserFromSession() in the controllers to access the logged in user and put it in the model for rendering. + As a teaser we'd like to show off the user profile page, as it will be rendered after UX heavy lifting. diff --git a/src/docbkx/tutorial/setup.xml b/src/docbkx/tutorial/setup.xml index 24adaee8c..48be97832 100644 --- a/src/docbkx/tutorial/setup.xml +++ b/src/docbkx/tutorial/setup.xml @@ -3,23 +3,23 @@ Scope: Spring - Being a Spring Developer, I would, of course, choose components of the Spring Framework to do most of the work. I'd already come up with the ideas - + Being Spring developers, we would, of course, choose components of the Spring Framework to do most of the work. We'd already come up with the ideas - that should be enough. What database would fit both the complex network of cineasts, movies, actors, roles, ratings and friends? And also be able to support the recommendation algorithms that I thought of? I had no idea. - But, wait, there was the new Spring Data project that started in 2010 bringing - the convenience of the Spring programming model to NoSQL databases. That should fit my experience and help me getting started. I looked - at the list of projects supporting the different NoSQL databases. Only one mentioned the kind of social network I was thinking of - - Spring Data Graph for Neo4j, a graph database. Neo4j's pitch of "value in relationships" and the accompanying docs looked like what I needed. - I decided to give it a try. + But, wait, there is the new Spring Data project, started in 2010, which brings + the convenience of the Spring programming model to NoSQL databases. That should fit our experience and help us to get started. We looked + at the list of projects supporting the different NoSQL databases. Only one mentioned the kind of social network we were thinking of - + Spring Data Graph for Neo4j, a graph database. Neo4j's pitch of "value in relationships" and the accompanying docs looked like what we needed. + So we decided to give it a try.
Preparations - Required Setup - To setup the project I created a public github account and began setting up the infrastructure for a spring web project using maven as build - system. So I added the dependencies for the springframework libraries, put the web.xml for the DispatcherServlet and the applicationContext.xml + To setup the project we created a public github account and began setting up the infrastructure for a spring web project using maven as build + system. So we added the dependencies for the springframework libraries, put the web.xml for the DispatcherServlet and the applicationContext.xml in the webapp directory. @@ -83,9 +83,9 @@ - With this setup I was ready for the first spike: creating a simple MovieController showing a static view. Check. Next was the setup for Spring Data Graph. - I looked at the README at github and then checked it with the manual. Quite a lot of maven setup for aspectj but otherwise not so much to add. - I added just a few lines to my spring configuration. + With this setup we were ready for the first spike: creating a simple MovieController showing a static view. Check. Next was the setup for Spring Data Graph. + We looked at the README at github and then checked it with the manual. Quite a lot of maven setup for aspectj but otherwise not so much to add. + Time to add a few lines to our spring configuration. @@ -133,7 +133,7 @@ - I spun up jetty to see if there were any obvious issues with the config. Check. + We spun up jetty to see if there were any obvious issues with the config. Check.
diff --git a/src/docbkx/tutorial/social.xml b/src/docbkx/tutorial/social.xml index 266d27e6d..1c5b5f1ce 100644 --- a/src/docbkx/tutorial/social.xml +++ b/src/docbkx/tutorial/social.xml @@ -3,13 +3,13 @@ Movies 2.0 - Adding social - But this was just a plain old movie database (POMD). My idea of socializing this business was not realized. + But this was just a plain old movie database (POMD). Our idea of socializing this business wasn't yet realized.
- See, mom a Cineast! - Users + Look, mom a Cineast! - Users - So I took the User class that I already coded up before and made it a full fledged Spring Data Graph member. - Added the ability to make friends and to rate movies. With that there was also a simple UserRepository that + So we took the User class that we'd already coded and made it a full fledged Spring Data Graph member. + We added the ability to make friends and to rate movies. With that there was also a simple UserRepository that was able to look up users by id. @@ -48,7 +48,7 @@ class Rating { - I extended my DatabasePopulator to add some users and ratings to the initial setup. + We extended my DatabasePopulator to add some users and ratings to the initial setup. populateDatabase() {
Beware, Critics - Rating - I also put a ratings field into the movie to be able to show its ratings. And a method to average the stars it got. + We also put a ratings field into the movie to be able to show its ratings. And a method to average its star rating. - Fortunately my tests showed my the division by zero error when calculating the stars for a movie without ratings. + Fortunately our tests highlighted the division by zero error when calculating the stars for a movie without ratings. Next steps were to add this information to the UI of movie and create a user profile page. But for that to happen they must be able to log in. diff --git a/src/docbkx/tutorial/spring-data-graph.xml b/src/docbkx/tutorial/spring-data-graph.xml index 638006a6f..77c61f4cf 100644 --- a/src/docbkx/tutorial/spring-data-graph.xml +++ b/src/docbkx/tutorial/spring-data-graph.xml @@ -3,11 +3,11 @@ Conjuring Magic - Spring Data Graph - But that was the pure graph database. Using this in my domain would pollute my classes with lots of graph - database details. I didn't want that. Spring Data Graph - promised to do the heavy lifting for me. So I checked that next. Obviously it heavily depended on aspectj magic. - So there would be certain behavour that was - just observable without being visible in my code. But I was going to give it a try. + But that was the pure graph database. Using this in our domain would pollute my classes with lots of graph + database details. We don't want that. Spring Data Graph + promised to do the heavy lifting for us. So we checked that next. Obviously it heavily depended on aspectj magic. + So there would be certain behavior that was + just observable without being visible in our code, but we were going to give it a try. First step was lots of maven configuration. diff --git a/src/docbkx/tutorial/user-experience.xml b/src/docbkx/tutorial/user-experience.xml index 87f0d3144..5b92a7ccc 100644 --- a/src/docbkx/tutorial/user-experience.xml +++ b/src/docbkx/tutorial/user-experience.xml @@ -3,13 +3,13 @@ Oh the Glamour - More UI - To create a nice user experience, I wanted to have a nice looking app, not something that looked like a developer - made it. So I got some UX people involved and the results were impressive. This sections presents some of the + To create a nice user experience, we wanted to have a nice looking app, not something that looked like a toddler + made it. So we got some UX people involved and the results were impressive. This sections presents some of the remaining screenshots of cineasts.net. Some of the noteworthy things. As Spring Data Graph does a read-through to the datastore for property and relationship - access I tried to minimize that by using <c:var/> several times. + access we tried to minimize that by using <c:var/> several times. The app contains very little javascript / ajax code right now, that will change when it moves ahead. diff --git a/src/docbkx/tutorial/webapp.xml b/src/docbkx/tutorial/webapp.xml index d0c3ceb9c..e415c6232 100644 --- a/src/docbkx/tutorial/webapp.xml +++ b/src/docbkx/tutorial/webapp.xml @@ -3,7 +3,7 @@ Showing off - Web views - After I had the means to put some data in the graph database, I also wanted to show it. So adding the controller method to show a single movie with its attributes + After we had the means to put some data in the graph database, we also wanted to show it. So adding the controller method to show a single movie with its attributes and cast in a jsp was straightforward. Actually just using the repository to look the movie up and add it to the model. Then forward to the /movies/show view and voilá. What was his name? - Searching - The next thing was to allow users to search for some movies. So I needed some fulltext-search capabilities. As the index provider implementation of Neo4j builds on -lucene I was delighted to see that fulltext indexes are supported out of the box. + The next thing was to allow users to search for some movies. So we needed some fulltext-search capabilities. As the index provider implementation of Neo4j builds on +lucene we were delighted to see that fulltext indexes are supported out of the box. - So I happily annotated the title field of my Movie class with @Index(fulltext=true) and was told with an exception that I have to specify a separate index name for that. -So it became @Indexed(fulltext = true, indexName = "search"). The corresponding finder method is called findAllByQuery. So there was my second repository method for -searching movies. To restrict the size of the returned set I just added a limit for now that cuts the result after that many entries. + We happily annotated the title field of my Movie class with @Index(fulltext=true) and was told with an exception that we have to specify a separate index name for that. +So it became @Indexed(fulltext = true, indexName = "search"). The corresponding finder method is called findAllByQuery. So there was our second repository method for +searching movies. To restrict the size of the returned set we just added a limit for now that truncates the result after so many entries. searchForMovie(String query, int count) {
- Look what i've found - Listing Results + Look what we've found - Listing Results - I then used this result in the controller to render a list of movies driven by a search box. The movie properties and the cast was accessed by the getters in the + We then used this result in the controller to render a list of movies driven by a search box. The movie properties and the cast was accessed by the getters in the domain classes.