Spring/spring-data-neo4j
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

documentation updates

Browse Source
This commit is contained in:
Michael Hunger
2011-08-11 16:18:20 +02:00
parent b18b56a3ce
commit 645bc9676b
10 changed files with 160 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
src/docbkx/index.xml
View File

@@ -19,12 +19,6 @@
<releaseinfo>&version;</releaseinfo>
<date/>
<mediaobject>
<imageobject>
<imagedata fileref="springdatagraph.png" scalefit="1" contentwidth="15cm"/>
</imageobject>
</mediaobject>
<authorgroup>
<author>
<firstname>Michael</firstname>
@@ -59,10 +53,18 @@
<part id="tutorial">
<title>Tutorial</title>
<partintro>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="tutorial/cineasts.png" scale="80" align="center"/>
</imageobject>
</mediaobject>
</para>
<para>
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.
</para>
@@ -94,16 +96,32 @@
<part id="reference">
<title>Reference</title>
<title>Reference Documentation</title>
<partintro>
<para>
This is the reference part of the book. It has information about the
programming model, APIs, concepts, and annotations of Spring Data Graph.
<mediaobject>
<imageobject>
<imagedata fileref="introduction/springdatagraph.png" scalefit="1" contentwidth="15cm"/>
</imageobject>
</mediaobject>
</para>
<para>
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.
</para>
<para>
Its content covers information about the programming model, APIs, concepts, annotations and
technical details of Spring Data Graph.
</para>
<para>
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.
</para>
</partintro>
<xi:include href="reference/preface.xml"/>
<xi:include href="reference/spring-data.xml" />
<xi:include href="reference/neo4j.xml"/>
<xi:include href="reference/programming-model/programming-model.xml"/>
<xi:include href="reference/setup.xml"/>

131
src/docbkx/reference/preface.xml
View File

@@ -2,23 +2,130 @@
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<preface id="reference:preface">
<title>Preface</title>
<title>Reference Documentation</title>
<section>
<title>Spring Data and Spring Data Graph</title>
<para>
<ulink url="http://springsource.org/spring-data">Spring Data</ulink> 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.
</para>
<para>
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.
</para>
<para>
Spring Data Graph allows, at anytime, to drop down to the <xref linkend="neo4j" >Neo4j-API</xref> level to execute functionality with
the highest performance possible.
</para>
<para>
For Integration of Neo4j and Grails/GORM please refer to the Neo4j
<ulink url="http://www.grails.org/plugin/neo4j">grails plugin</ulink>. For other language bindings or frameworks
visit the <ulink url="http://wiki.neo4j.org/content/Main_Page#Language_and_framework_bindings">Neo4j Wiki</ulink>.
</para>
</section>
<para>
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 <xref linkend="reference:aspectj"/>.
It also explains some of the common issues around AspectJ tooling with the current IDEs.
</para>
<para>
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
<ulink url="http://www.grails.org/plugin/neo4j">grails plugin</ulink>.
To get started with a simple application, you need only your domain model and the annotations
(see <xref linkend="reference:programming-model:annotations"/>) 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.
</para>
<para>
To get started with a simple application, only the basic annotations
(see <xref linkend="reference:programming-model:annotations"/>) and the additional aspect-introduced
entity methods (see <xref linkend="reference:programming-model:introduced-methods"/>) 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
<xref linkend="reference:programming_model:relationships" >chapter</xref> describing their usage in Spring Data Graph.
</para>
<para>
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 <xref linkend="neo4j" >Neo4j-API</xref> chapter. Then you can start adding purely
dynamically gathered fields to your entities.
</para>
<para>
You might probably use the additional
entity methods (see <xref linkend="reference:programming-model:introduced-methods"/>) 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.
</para>
<para>
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.
(<xref linkend="reference:programming-model:indexing"/>)
</para>
<para>
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. (<xref linkend="reference:programming-model:repositories"/>).
</para>
<para>
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. (<xref linkend="reference:programming-model:transactions"/>)
</para>
<para>
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.
(<xref linkend="reference:programming-model:lifecycle"/>)
</para>
<para>
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.
(<xref linkend="reference:programming-model:typerepresentationstrategy"/>)
</para>
<para>
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: <xref linkend="reference:programming-model:projection"/>.
</para>
<para>
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 <xref linkend="reference:programming-model:validation"/>)
</para>
<!--
<xi:include href="reference/neo4j.xml"/>
<xi:include href="reference/programming-model/programming-model.xml"/>
<xi:include href="aspectj.xml"/>
<xi:include href="node-entities.xml"/>
<xi:include href="relationships.xml"/>
<xi:include href="introducedmethods.xml"/>
<xi:include href="indexing.xml"/>
<xi:include href="repositories.xml"/>
<xi:include href="transactions.xml"/>
<xi:include href="attachdetach.xml"/>
<xi:include href="typerepresentationstrategy.xml"/>
<xi:include href="projection.xml"/>
<xi:include href="beanvalidation.xml"/>
<xi:include href="reference/setup.xml"/>
<xi:include href="reference/cross-store.xml"/>
<xi:include href="reference/samples.xml"/>
<xi:include href="reference/performance.xml" />
<xi:include href="reference/template.xml" />
<xi:include href="reference/aspectj-details.xml" />
<xi:include href="reference/neo4j-server.xml" />
-->
<para>
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 <xref linkend="neo4j">Neo4j</xref>.
</para>
<para>
<note>

13
src/docbkx/reference/programming-model/aspectj.xml
View File

@@ -11,12 +11,10 @@
</para>
<para>
The aspect introduces some internal fields and some public methods
(see <xref linkend="reference:programming-model:introduced-methods"/>) in the entities, such as
(see <xref linkend="reference:programming-model:introduced-methods"/>) to the entities, such as
<code>entity.getPersistentState()</code> and <code>entity.relateTo</code>.
It also introduces repository methods like
<code>find(Class&lt;? extends NodeEntity>, TraversalDescription)</code>,
and <code>equals()</code> and <code>hashCode</code> delegation, making <code>equals()</code>
honor the backing state.
It also introduces repository methods like<code>find(Class&lt;? extends NodeEntity>, TraversalDescription)</code>.
Introduced methods for <code>equals()</code> and <code>hashCode()</code> use the underlying node or relationship.
</para>
<para>
Spring Data Graph internally uses an abstraction called <code>EntityState</code> that the field
@@ -24,7 +22,7 @@
minimum, focusing mainly on the pointcuts and delegation code. The <code>EntityState</code> then uses
a number of <code>FieldAccessorFactories</code> to create a <code>FieldAccessor</code> 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.
</para>
<section>
<title>AspectJ IDE support</title>
@@ -50,7 +48,8 @@
</para>
<note>
<para>
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 <code>include **/*.aj</code> for the spring-data-neo4j project.
You can do this by selecting "Build Path -> Configure Build Path ..." from the Package Explorer.

2
src/docbkx/reference/programming-model/attachdetach.xml
View File

@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<section>
<section id="reference:programming-model:lifecycle">
<title>Detached node entities</title>
<para>
Node entities can be in two different persistence state: attached or detached. By default, newly created node

2
src/docbkx/reference/programming-model/beanvalidation.xml
View File

@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<section>
<section id="reference:programming-model:validation">
<title>Bean validation (JSR-303)</title>
<para>
Spring Data Graph supports property-based validation support. When a property is changed, it is

4
src/docbkx/reference/programming-model/programming-model.xml
View File

@@ -5,18 +5,18 @@
<para>
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
<ulink url="http://github.com/SpringSource/spring-data-graph-examples">Spring Data Graph examples</ulink>.
</para>
<xi:include href="aspectj.xml"/>
<xi:include href="node-entities.xml"/>
<xi:include href="relationships.xml"/>
<xi:include href="introducedmethods.xml"/>
<xi:include href="indexing.xml"/>
<xi:include href="repositories.xml"/>
<xi:include href="transactions.xml"/>
<xi:include href="attachdetach.xml"/>
<xi:include href="typerepresentationstrategy.xml"/>
<xi:include href="introducedmethods.xml"/>
<xi:include href="projection.xml"/>
<xi:include href="beanvalidation.xml"/>
</chapter>

2
src/docbkx/reference/programming-model/projection.xml
View File

@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<section>
<section id="reference:programming-model:projection">
<title>Projecting entities</title>
<para>
As the underlying data model of a graph database doesn't imply and enforce strict type constraints like a

2
src/docbkx/reference/programming-model/transactions.xml
View File

@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<section>
<section id="reference:programming-model:transactions">
<title>Transactions</title>
<para>
Neo4j is a transactional database, only allowing modifications to be performed within transaction

11
src/docbkx/reference/spring-data.xml
View File

@@ -1,11 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<chapter id="reference:spring-data">
<title>About Spring Data</title>
<para>
<ulink url="http://springsource.org/spring-data">Spring Data</ulink> 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.
</para>
</chapter>

7
src/docbkx/tutorial/about-tutorial.xml
View File

@@ -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.
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="cineasts.png" scale="80" align="center"/>
</imageobject>
</mediaobject>
</para>
<para>
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