documentation updates
This commit is contained in:
Michael Hunger
@@ -86,7 +86,12 @@ public void foo( @Context WorldRepository repo ) {
|
||||
that Spring Data Graph is not transactional when running with a <code>RestGraphDatabase</code>.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<para>
|
||||
Please also keep in mind that performing graph operations via the REST-API is about one order of
|
||||
magnitude slower than location operations. Try to use the Neo4j-Query-Language or
|
||||
server-side traversals whenever possible (<code>RestTraversal</code>) for retrieving large sets of data.
|
||||
Future versions of Spring Data Graph will use the more performant batching as well as a binary protocol.
|
||||
</para>
|
||||
<para>
|
||||
To set up your project to use the REST bindings, add this dependency to your pom.xml:
|
||||
<example>
|
||||
|
||||
@@ -9,10 +9,24 @@
|
||||
the AspectJ aspects in the Spring Data Graph framework, mapping the POJO entities and their fields
|
||||
to nodes, relationships, and properties in the graph database.
|
||||
</para>
|
||||
<para>
|
||||
Spring Data Graph allows anytime to drop down to the Neo4j-API level to execute functionality with
|
||||
the highest performance possible. For Integration of Neo4j and Grails/GORM please refer to the Neo4j
|
||||
<ulink url="http://www.grails.org/plugin/neo4j">grails plugin</ulink>.
|
||||
</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.
|
||||
</para>
|
||||
<para>
|
||||
<note>
|
||||
<para>
|
||||
As Spring Data Graph is based on AspectJ and uses some advanced features of that toolset, please
|
||||
be aware of that. Please see the section on AspectJ (<xref linkend="reference:aspectj"/>) for
|
||||
details if you run into any problems.
|
||||
</para>
|
||||
</note>
|
||||
</para>
|
||||
</preface>
|
||||
|
||||
@@ -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:aspectj">
|
||||
<title>AspectJ support</title>
|
||||
<para>
|
||||
Behind the scenes, Spring Data Graph leverages <ulink url="http://www.eclipse.org/aspectj/">AspectJ</ulink>
|
||||
@@ -34,11 +34,19 @@
|
||||
include: introduction of methods to interfaces, declaration of additional interfaces for annotated
|
||||
classes, and generified introduced methods.
|
||||
</para>
|
||||
<para>
|
||||
IDE's not providing the full AJ support might mark parts of your code as errors.
|
||||
You should rely on your build-system and test to verify the correctness of the code. You might also have
|
||||
your Entities (or their interfaces) implement the <code>NodeBacked</code> and <code>RelationshipBacked</code>
|
||||
interfaces directly to benefit from completion support and error checking.
|
||||
</para>
|
||||
<para>
|
||||
Eclipse and STS support AspectJ via the AJDT plugin which can be installed from the update-site:
|
||||
<ulink url="http://download.eclipse.org/tools/ajdt/36/update/">http://download.eclipse.org/tools/ajdt/36/update/</ulink>
|
||||
(or for the latest development snapshot of the plugin
|
||||
(it might be necessary to use the latest development snapshot of the plugin
|
||||
<ulink url="http://download.eclipse.org/tools/ajdt/36/dev/update">http://download.eclipse.org/tools/ajdt/36/dev/update</ulink>).
|
||||
The current version that does not show incorrect errors is AspectJ 1.6.12.M1 (included in STS 2.7.0.M2), previous versions are reported
|
||||
to mislead the user.
|
||||
</para>
|
||||
<para>
|
||||
The AspectJ support in IntelliJ IDEA lacks some of the features. JetBrains is working on improving
|
||||
|
||||
@@ -81,6 +81,14 @@ movie.setTopActor(actor);
|
||||
this behavior is not dependent on any configured relationship direction on the annotations.
|
||||
It is a matter of Java references and is not related to the data model in the database.
|
||||
</para>
|
||||
<para>
|
||||
The persist operation (merge) stores all properties of the entity to the graph database
|
||||
and puts the entity in attached mode. There is no need to update the reference to the Java
|
||||
POJO as the underlying backing node handles the read-through transparently. If multiple
|
||||
object instances that point to the same node are persisted, the ordering is not important
|
||||
as long as they contain distinct changes. For concurrent changes a concurrent modification
|
||||
exception is thrown (subject to be parametrizable in the future).
|
||||
</para>
|
||||
<para>
|
||||
If the relationships form a cycle, then the entities will first all be assigned a node in
|
||||
the database, and then the relationships will be created. The cascading of <code>persist()</code>
|
||||
|
||||
@@ -15,6 +15,10 @@
|
||||
<code>useShortNames</code> attribute overridden to false, the property and relationship names will
|
||||
have the class name of the entity prepended.
|
||||
</para>
|
||||
<para>
|
||||
<code>@NodeEntity</code> annotations are inherited from super-types and interfaces. It is not necessary
|
||||
to annotate your domain objects at every inheritance level.
|
||||
</para>
|
||||
<para>
|
||||
If the <code>partial</code> attribute is set to true, this entity takes part in a cross-store setting,
|
||||
where the entity lives in both the graph database and a JPA data source. See
|
||||
@@ -44,6 +48,10 @@ public class Movie {
|
||||
custom conversion factory that comes with converters for <code>Enum</code>s and <code>Date</code>s.
|
||||
Transient fields are not persisted.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
This annotation is typically used with cross-store persistence. When a node entity is configured
|
||||
as partial, then all fields that should be persisted to the graph must be explicitly annotated
|
||||
@@ -63,6 +71,30 @@ public class Movie {
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>@GraphQuery: fields as query result views</title>
|
||||
<para>
|
||||
The <code>@GraphQuery</code> annotation leverages the delegation infrastructure used by the
|
||||
Spring Data Graph aspects. It provides dynamic fields which, when accessed, return the values
|
||||
selected by the provided query language expression. The provided query must contain a placeholder
|
||||
for the id of the current entity <code>start n=(%d) match n-[:FRIEND]->friend return friend</code>
|
||||
As graph queries can return variable number of entities the annotation can be put onto fields
|
||||
with a single value, an Iterable of a type or an Iterable of <code>Map<String,Object></code>.
|
||||
The class of the resulting node entities must right now provided with the <code>elementClass</code> attribute.
|
||||
Additional parameters are added to the query with Java's String.format substitution.
|
||||
</para>
|
||||
<example>
|
||||
<title>@GraphQuery from a node entity</title>
|
||||
<programlisting language="java"><![CDATA[@NodeEntity
|
||||
public class Group {
|
||||
@GraphQuery(value = "start n=(%d) match (n)-[:%s]->(friend) return friend",
|
||||
elementClass = Person.class, params = "FRIEND")
|
||||
private Iterable<Person> friends;
|
||||
}
|
||||
]]></programlisting>
|
||||
|
||||
</example>
|
||||
</section>
|
||||
<section>
|
||||
<title>@GraphTraversal: fields as traversal result views</title>
|
||||
<para>
|
||||
|
||||
@@ -9,6 +9,11 @@
|
||||
Spring Data Graph has special support to represent Neo4j relationships as entities too, but it is often
|
||||
not needed.
|
||||
</para>
|
||||
<note>
|
||||
<para>
|
||||
As of Neo4j 1.4.M03, circular references are allowed. Spring Data Graph reflects this accordingly.
|
||||
</para>
|
||||
</note>
|
||||
<section id="reference:programming_model:relationships:relatedto">
|
||||
<title>@RelatedTo: Connecting node entities</title>
|
||||
<para>
|
||||
@@ -69,7 +74,12 @@ public class Actor {
|
||||
</para>
|
||||
</note>
|
||||
<para>
|
||||
By setting direction to BOTH, relationships are created in the outgoing direction, but when the
|
||||
When you use an Interface as target type for the <code>Set</code> and/or as <code>elementClass</code>
|
||||
please make sure that it implements <code>NodeBacked</code> either by extending that Super-Interface manually
|
||||
or by annotating the Interface with <code>@NodeEntity</code> too.
|
||||
</para>
|
||||
<para>
|
||||
By setting direction to <code>BOTH</code>, relationships are created in the outgoing direction, but when the
|
||||
1:N field is read, it will include relationships in both directions. A cardinality of M:N is
|
||||
not necessary because relationships can be navigated in both directions.
|
||||
</para>
|
||||
@@ -79,8 +89,15 @@ public class Actor {
|
||||
<code>entity.relateTo(target, type)</code> available on each NodeEntity.
|
||||
These methods find and create Neo4j relationships. It is also possible to manually remove
|
||||
relationships by using <code>entity.removeRelationshipTo(target, type)</code>.
|
||||
Using these methods is rarely necessary though.
|
||||
Using these methods is significantly faster than adding/removing from the collection of
|
||||
relationships as it doesn't have to re-synchronize a whole set of relationships with the graph.
|
||||
</para>
|
||||
<note>
|
||||
<para>
|
||||
Other collection types than <code>Set</code> are not supported so far, also currently NO
|
||||
<code>Map<RelationshipType,Set<NodeBacked>></code>.
|
||||
</para>
|
||||
</note>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
|
||||
@@ -10,8 +10,65 @@
|
||||
<!--Examples for this setup can be found in the -->
|
||||
<!--<ulink url="http://github.com/SpringSource/spring-data-graph-examples">Spring Data Graph examples</ulink>.-->
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Spring Data Graph projects can be built using maven, we also added means to build them with gradle and ant/ivy.
|
||||
</para>
|
||||
<section>
|
||||
<title>Gradle configuration</title>
|
||||
<para>
|
||||
The necessary build plugin to build Spring Data Graph projects with gradle is available as part of the
|
||||
SDG distribution or on github which makes the usage as easy as:
|
||||
</para>
|
||||
<example>
|
||||
<title>Gradle Build Configuration</title>
|
||||
<programlisting language="groovy"><![CDATA[sourceCompatibility = 1.6
|
||||
targetCompatibility = 1.6
|
||||
|
||||
springVersion = "3.0.5.RELEASE"
|
||||
springDataGraphVersion = "1.1.0.M1"
|
||||
aspectjVersion = "1.6.12.M1
|
||||
|
||||
apply from:'https://github.com/SpringSource/spring-data-graph/raw/master/build/gradle/springdatagraph.gradle'
|
||||
|
||||
configurations {
|
||||
runtime
|
||||
testCompile
|
||||
}
|
||||
repositories {
|
||||
mavenCentral()
|
||||
mavenLocal()
|
||||
mavenRepo urls: "http://maven.springframework.org/release"
|
||||
}]]></programlisting>
|
||||
</example>
|
||||
<para>
|
||||
The actual springdatagraph.gradle is very simple just decorating the javac tasks with the iajc ant task.
|
||||
</para>
|
||||
</section>
|
||||
<section>
|
||||
<title>Ant/Ivy configuration</title>
|
||||
<para>
|
||||
The supplied sample ant <ulink
|
||||
url="https://github.com/SpringSource/spring-data-graph/raw/master/build/ivy">build configuration</ulink> is mainly about resolving
|
||||
the dependencies for Spring Data Graph and AspectJ using Ivy and integrating the iajc ant task in the build.
|
||||
</para>
|
||||
<example>
|
||||
<title>Ant/Ivy Build Configuration</title>
|
||||
<programlisting language="xml"><![CDATA[ <taskdef resource="org/aspectj/tools/ant/taskdefs/aspectjTaskdefs.properties" classpath="${lib.dir}/aspectjtools.jar"/>
|
||||
|
||||
<target name="compile" description="Compile production classes" depends="lib.retrieve">
|
||||
<mkdir dir="${main.target}" />
|
||||
|
||||
<iajc sourceroots="${main.src}" destDir="${main.target}" classpathref="path.libs" source="1.6">
|
||||
<aspectpath>
|
||||
<pathelement location="${lib.dir}/spring-aspects.jar"/>
|
||||
</aspectpath>
|
||||
<aspectpath>
|
||||
<pathelement location="${lib.dir}/spring-data-neo4j.jar"/>
|
||||
</aspectpath>
|
||||
</iajc>
|
||||
</target>]]></programlisting>
|
||||
</example>
|
||||
</section>
|
||||
<title>Maven configuration</title>
|
||||
<para>
|
||||
Spring Data Graph projects are easiest to build with Apache Maven. The main dependencies are: Spring
|
||||
|
||||
Reference in New Issue
Block a user